From 01a515383a6d31d619cb1217911d659c9a52ff21 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 27 Aug 2026 16:29:29 +0000 Subject: [PATCH 001/232] fix(openapi): strip empty-object defaults from the generated spec Stainless-Generated-From: a1c3d3b1255cb5f6b7047fb9146cdca8cd70c7db --- packages/mcp-server/src/local-docs-search.ts | 6 +++--- packages/mcp-server/src/server.ts | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/mcp-server/src/local-docs-search.ts b/packages/mcp-server/src/local-docs-search.ts index 6c9fbb33..8709272a 100644 --- a/packages/mcp-server/src/local-docs-search.ts +++ b/packages/mcp-server/src/local-docs-search.ts @@ -2356,12 +2356,12 @@ const EMBEDDED_READMES: { language: string; content: string }[] = [ { language: 'php', content: - "# Context Dev PHP API Library\n\nThe Context Dev PHP library provides convenient access to the Context Dev REST API from any PHP 8.1.0+ application.\n\n## Installation\n\n\n```\ncomposer require \"context-dev/context-dev-php 2.12.0\"\n```\n\n\n## Usage\n\n```php\nbrand->retrieve(domain: 'REPLACE_ME', type: 'by_domain');\n\nvar_dump($brand->cache_metadata);\n```", + "# Context Dev PHP API Library\n\nThe Context Dev PHP library provides convenient access to the Context Dev REST API from any PHP 8.1.0+ application.\n\n## Installation\n\n\n```\ncomposer require \"context-dev/context-dev-php 2.13.0\"\n```\n\n\n## Usage\n\n```php\nbrand->retrieve(domain: 'REPLACE_ME', type: 'by_domain');\n\nvar_dump($brand->cache_metadata);\n```", }, { language: 'go', content: - '# Context Dev Go API Library\n\nGo Reference\n\nThe Context Dev Go library provides convenient access to the [Context Dev REST API](https://docs.context.dev/)\nfrom applications written in Go.\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n## MCP Server\n\nUse the Context Dev MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0)\n[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D)\n\n> Note: You may need to set environment variables in your MCP client.\n\n## Installation\n\n\n\n```go\nimport (\n\t"github.com/context-dot-dev/context-go-sdk/v2" // imported as SDK_PackageName\n)\n```\n\n\n\nOr to pin the version:\n\n\n\n```sh\ngo get -u \'github.com/context-dot-dev/context-go-sdk/v2@v2.12.0\'\n```\n\n\n\n## Requirements\n\nThis library requires Go 1.22+.\n\n## Usage\n\nThe full API of this library can be found in [api.md](api.md).\n\n```go\npackage main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"), // defaults to os.LookupEnv("CONTEXT_DEV_API_KEY")\n\t)\n\tbrand, err := client.Brand.Get(context.TODO(), contextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", brand.CacheMetadata)\n}\n\n```\n\n### Request fields\n\nAll request parameters are wrapped in a generic `Field` type,\nwhich we use to distinguish zero values from null or omitted fields.\n\nThis prevents accidentally sending a zero value if you forget a required parameter,\nand enables explicitly sending `null`, `false`, `\'\'`, or `0` on optional parameters.\nAny field not specified is not sent.\n\nTo construct fields with values, use the helpers `String()`, `Int()`, `Float()`, or most commonly, the generic `F[T]()`.\nTo send a null, use `Null[T]()`, and to send a nonconforming value, use `Raw[T](any)`. For example:\n\n```go\nparams := FooParams{\n\tName: SDK_PackageName.F("hello"),\n\n\t// Explicitly send `"description": null`\n\tDescription: SDK_PackageName.Null[string](),\n\n\tPoint: SDK_PackageName.F(SDK_PackageName.Point{\n\t\tX: SDK_PackageName.Int(0),\n\t\tY: SDK_PackageName.Int(1),\n\n\t\t// In cases where the API specifies a given type,\n\t\t// but you want to send something else, use `Raw`:\n\t\tZ: SDK_PackageName.Raw[int64](0.01), // sends a float\n\t}),\n}\n```\n\n### Response objects\n\nAll fields in response structs are value types (not pointers or wrappers).\n\nIf a given field is `null`, not present, or invalid, the corresponding field\nwill simply be its zero value.\n\nAll response structs also include a special `JSON` field, containing more detailed\ninformation about each property, which you can use like so:\n\n```go\nif res.Name == "" {\n\t// true if `"name"` is either not present or explicitly null\n\tres.JSON.Name.IsNull()\n\n\t// true if the `"name"` key was not present in the response JSON at all\n\tres.JSON.Name.IsMissing()\n\n\t// When the API returns data that cannot be coerced to the expected type:\n\tif res.JSON.Name.IsInvalid() {\n\t\traw := res.JSON.Name.Raw()\n\n\t\tlegacyName := struct{\n\t\t\tFirst string `json:"first"`\n\t\t\tLast string `json:"last"`\n\t\t}{}\n\t\tjson.Unmarshal([]byte(raw), &legacyName)\n\t\tname = legacyName.First + " " + legacyName.Last\n\t}\n}\n```\n\nThese `.JSON` structs also include an `Extras` map containing\nany properties in the json response that were not specified\nin the struct. This can be useful for API features not yet\npresent in the SDK.\n\n```go\nbody := res.JSON.ExtraFields["my_unexpected_field"].Raw()\n```\n\n### RequestOptions\n\nThis library uses the functional options pattern. Functions defined in the\n`SDK_PackageOptionName` package return a `RequestOption`, which is a closure that mutates a\n`RequestConfig`. These options can be supplied to the client or at individual\nrequests. For example:\n\n```go\nclient := SDK_PackageName.SDK_ClientInitializerName(\n\t// Adds a header to every request made by the client\n\tSDK_PackageOptionName.WithHeader("X-Some-Header", "custom_header_info"),\n)\n\nclient.Brand.Get(context.TODO(), ...,\n\t// Override the header\n\tSDK_PackageOptionName.WithHeader("X-Some-Header", "some_other_custom_header_info"),\n\t// Add an undocumented field to the request body, using sjson syntax\n\tSDK_PackageOptionName.WithJSONSet("some.json.path", map[string]string{"my": "object"}),\n)\n```\n\nSee the [full list of request options](https://pkg.go.dev/github.com/context-dot-dev/context-go-sdk/v2/SDK_PackageOptionName).\n\n### Pagination\n\nThis library provides some conveniences for working with paginated list endpoints.\n\nYou can use `.ListAutoPaging()` methods to iterate through items across all pages:\n\n\n\nOr you can use simple `.List()` methods to fetch a single page and receive a standard response object\nwith additional helper methods like `.GetNextPage()`, e.g.:\n\n\n\n### Errors\n\nWhen the API returns a non-success status code, we return an error with type\n`*SDK_PackageName.Error`. This contains the `StatusCode`, `*http.Request`, and\n`*http.Response` values of the request, as well as the JSON of the error body\n(much like other response objects in the SDK).\n\nTo handle errors, we recommend that you use the `errors.As` pattern:\n\n```go\n_, err := client.Brand.Get(context.TODO(), contextdev.BrandGetParams{\n\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\tDomain: "stripe.com",\n\t},\n})\nif err != nil {\n\tvar apierr *contextdev.Error\n\tif errors.As(err, &apierr) {\n\t\tprintln(string(apierr.DumpRequest(true))) // Prints the serialized HTTP request\n\t\tprintln(string(apierr.DumpResponse(true))) // Prints the serialized HTTP response\n\t}\n\tpanic(err.Error()) // GET "/brand/retrieve": 400 Bad Request { ... }\n}\n```\n\nWhen other errors occur, they are returned unwrapped; for example,\nif HTTP transport fails, you might receive `*url.Error` wrapping `*net.OpError`.\n\n### Timeouts\n\nRequests do not time out by default; use context to configure a timeout for a request lifecycle.\n\nNote that if a request is [retried](#retries), the context timeout does not start over.\nTo set a per-retry timeout, use `SDK_PackageOptionName.WithRequestTimeout()`.\n\n```go\n// This sets the timeout for the request, including all the retries.\nctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)\ndefer cancel()\nclient.Brand.Get(\n\tctx,\n\tcontextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t},\n\t// This sets the per-retry timeout\n\toption.WithRequestTimeout(20*time.Second),\n)\n```\n\n### File uploads\n\nRequest parameters that correspond to file uploads in multipart requests are typed as\n`param.Field[io.Reader]`. The contents of the `io.Reader` will by default be sent as a multipart form\npart with the file name of "anonymous_file" and content-type of "application/octet-stream".\n\nThe file name and content-type can be customized by implementing `Name() string` or `ContentType()\nstring` on the run-time type of `io.Reader`. Note that `os.File` implements `Name() string`, so a\nfile returned by `os.Open` will be sent with the file name on disk.\n\nWe also provide a helper `SDK_PackageName.FileParam(reader io.Reader, filename string, contentType string)`\nwhich can be used to wrap any `io.Reader` with the appropriate file name and content type.\n\n\n\n### Retries\n\nCertain errors will be automatically retried 2 times by default, with a short exponential backoff.\nWe retry by default all connection errors, 408 Request Timeout, 409 Conflict, 429 Rate Limit,\nand >=500 Internal errors.\n\nYou can use the `WithMaxRetries` option to configure or disable this:\n\n```go\n// Configure the default for all requests:\nclient := contextdev.NewClient(\n\toption.WithMaxRetries(0), // default is 2\n)\n\n// Override per-request:\nclient.Brand.Get(\n\tcontext.TODO(),\n\tcontextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t},\n\toption.WithMaxRetries(5),\n)\n```\n\n\n### Accessing raw response data (e.g. response headers)\n\nYou can access the raw HTTP response data by using the `option.WithResponseInto()` request option. This is useful when\nyou need to examine response headers, status codes, or other details.\n\n```go\n// Create a variable to store the HTTP response\nvar response *http.Response\nbrand, err := client.Brand.Get(\n\tcontext.TODO(),\n\tcontextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t},\n\toption.WithResponseInto(&response),\n)\nif err != nil {\n\t// handle error\n}\nfmt.Printf("%+v\\n", brand)\n\nfmt.Printf("Status Code: %d\\n", response.StatusCode)\nfmt.Printf("Headers: %+#v\\n", response.Header)\n```\n\n### Making custom/undocumented requests\n\nThis library is typed for convenient access to the documented API. If you need to access undocumented\nendpoints, params, or response properties, the library can still be used.\n\n#### Undocumented endpoints\n\nTo make requests to undocumented endpoints, you can use `client.Get`, `client.Post`, and other HTTP verbs.\n`RequestOptions` on the client, such as retries, will be respected when making these requests.\n\n```go\nvar (\n // params can be an io.Reader, a []byte, an encoding/json serializable object,\n // or a "…Params" struct defined in this library.\n params map[string]interface{}\n\n // result can be an []byte, *http.Response, a encoding/json deserializable object,\n // or a model defined in this library.\n result *http.Response\n)\nerr := client.Post(context.Background(), "/unspecified", params, &result)\nif err != nil {\n …\n}\n```\n\n#### Undocumented request params\n\nTo make requests using undocumented parameters, you may use either the `SDK_PackageOptionName.WithQuerySet()`\nor the `SDK_PackageOptionName.WithJSONSet()` methods.\n\n```go\nparams := FooNewParams{\n ID: SDK_PackageName.F("id_xxxx"),\n Data: SDK_PackageName.F(FooNewParamsData{\n FirstName: SDK_PackageName.F("John"),\n }),\n}\nclient.Foo.New(context.Background(), params, SDK_PackageOptionName.WithJSONSet("data.last_name", "Doe"))\n```\n\n#### Undocumented response properties\n\nTo access undocumented response properties, you may either access the raw JSON of the response as a string\nwith `result.JSON.RawJSON()`, or get the raw JSON of a particular field on the result with\n`result.JSON.Foo.Raw()`.\n\nAny fields that are not present on the response struct will be saved and can be accessed by `result.JSON.ExtraFields()` which returns the extra fields as a `map[string]Field`.\n\n### Middleware\n\nWe provide `SDK_PackageOptionName.WithMiddleware` which applies the given\nmiddleware to requests.\n\n```go\nfunc Logger(req *http.Request, next SDK_PackageOptionName.MiddlewareNext) (res *http.Response, err error) {\n\t// Before the request\n\tstart := time.Now()\n\tLogReq(req)\n\n\t// Forward the request to the next handler\n\tres, err = next(req)\n\n\t// Handle stuff after the request\n\tend := time.Now()\n\tLogRes(res, err, start - end)\n\n return res, err\n}\n\nclient := SDK_PackageName.SDK_ClientInitializerName(\n\tSDK_PackageOptionName.WithMiddleware(Logger),\n)\n```\n\nWhen multiple middlewares are provided as variadic arguments, the middlewares\nare applied left to right. If `SDK_PackageOptionName.WithMiddleware` is given\nmultiple times, for example first in the client then the method, the\nmiddleware in the client will run first and the middleware given in the method\nwill run next.\n\nYou may also replace the default `http.Client` with\n`SDK_PackageOptionName.WithHTTPClient(client)`. Only one http client is\naccepted (this overwrites any previous client) and receives requests after any\nmiddleware has been applied.\n\n## Semantic versioning\n\nThis package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:\n\n1. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_\n2. Changes that we do not expect to impact the vast majority of users in practice.\n\nWe take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.\n\nWe are keen for your feedback; please open an [issue](https://www.github.com/context-dot-dev/context-go-sdk/issues) with questions, bugs, or suggestions.\n\n## Contributing\n\nSee [the contributing documentation](./CONTRIBUTING.md).\n', + '# Context Dev Go API Library\n\nGo Reference\n\nThe Context Dev Go library provides convenient access to the [Context Dev REST API](https://docs.context.dev/)\nfrom applications written in Go.\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n## MCP Server\n\nUse the Context Dev MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0)\n[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D)\n\n> Note: You may need to set environment variables in your MCP client.\n\n## Installation\n\n\n\n```go\nimport (\n\t"github.com/context-dot-dev/context-go-sdk/v2" // imported as SDK_PackageName\n)\n```\n\n\n\nOr to pin the version:\n\n\n\n```sh\ngo get -u \'github.com/context-dot-dev/context-go-sdk/v2@v2.13.0\'\n```\n\n\n\n## Requirements\n\nThis library requires Go 1.22+.\n\n## Usage\n\nThe full API of this library can be found in [api.md](api.md).\n\n```go\npackage main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"), // defaults to os.LookupEnv("CONTEXT_DEV_API_KEY")\n\t)\n\tbrand, err := client.Brand.Get(context.TODO(), contextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", brand.CacheMetadata)\n}\n\n```\n\n### Request fields\n\nAll request parameters are wrapped in a generic `Field` type,\nwhich we use to distinguish zero values from null or omitted fields.\n\nThis prevents accidentally sending a zero value if you forget a required parameter,\nand enables explicitly sending `null`, `false`, `\'\'`, or `0` on optional parameters.\nAny field not specified is not sent.\n\nTo construct fields with values, use the helpers `String()`, `Int()`, `Float()`, or most commonly, the generic `F[T]()`.\nTo send a null, use `Null[T]()`, and to send a nonconforming value, use `Raw[T](any)`. For example:\n\n```go\nparams := FooParams{\n\tName: SDK_PackageName.F("hello"),\n\n\t// Explicitly send `"description": null`\n\tDescription: SDK_PackageName.Null[string](),\n\n\tPoint: SDK_PackageName.F(SDK_PackageName.Point{\n\t\tX: SDK_PackageName.Int(0),\n\t\tY: SDK_PackageName.Int(1),\n\n\t\t// In cases where the API specifies a given type,\n\t\t// but you want to send something else, use `Raw`:\n\t\tZ: SDK_PackageName.Raw[int64](0.01), // sends a float\n\t}),\n}\n```\n\n### Response objects\n\nAll fields in response structs are value types (not pointers or wrappers).\n\nIf a given field is `null`, not present, or invalid, the corresponding field\nwill simply be its zero value.\n\nAll response structs also include a special `JSON` field, containing more detailed\ninformation about each property, which you can use like so:\n\n```go\nif res.Name == "" {\n\t// true if `"name"` is either not present or explicitly null\n\tres.JSON.Name.IsNull()\n\n\t// true if the `"name"` key was not present in the response JSON at all\n\tres.JSON.Name.IsMissing()\n\n\t// When the API returns data that cannot be coerced to the expected type:\n\tif res.JSON.Name.IsInvalid() {\n\t\traw := res.JSON.Name.Raw()\n\n\t\tlegacyName := struct{\n\t\t\tFirst string `json:"first"`\n\t\t\tLast string `json:"last"`\n\t\t}{}\n\t\tjson.Unmarshal([]byte(raw), &legacyName)\n\t\tname = legacyName.First + " " + legacyName.Last\n\t}\n}\n```\n\nThese `.JSON` structs also include an `Extras` map containing\nany properties in the json response that were not specified\nin the struct. This can be useful for API features not yet\npresent in the SDK.\n\n```go\nbody := res.JSON.ExtraFields["my_unexpected_field"].Raw()\n```\n\n### RequestOptions\n\nThis library uses the functional options pattern. Functions defined in the\n`SDK_PackageOptionName` package return a `RequestOption`, which is a closure that mutates a\n`RequestConfig`. These options can be supplied to the client or at individual\nrequests. For example:\n\n```go\nclient := SDK_PackageName.SDK_ClientInitializerName(\n\t// Adds a header to every request made by the client\n\tSDK_PackageOptionName.WithHeader("X-Some-Header", "custom_header_info"),\n)\n\nclient.Brand.Get(context.TODO(), ...,\n\t// Override the header\n\tSDK_PackageOptionName.WithHeader("X-Some-Header", "some_other_custom_header_info"),\n\t// Add an undocumented field to the request body, using sjson syntax\n\tSDK_PackageOptionName.WithJSONSet("some.json.path", map[string]string{"my": "object"}),\n)\n```\n\nSee the [full list of request options](https://pkg.go.dev/github.com/context-dot-dev/context-go-sdk/v2/SDK_PackageOptionName).\n\n### Pagination\n\nThis library provides some conveniences for working with paginated list endpoints.\n\nYou can use `.ListAutoPaging()` methods to iterate through items across all pages:\n\n\n\nOr you can use simple `.List()` methods to fetch a single page and receive a standard response object\nwith additional helper methods like `.GetNextPage()`, e.g.:\n\n\n\n### Errors\n\nWhen the API returns a non-success status code, we return an error with type\n`*SDK_PackageName.Error`. This contains the `StatusCode`, `*http.Request`, and\n`*http.Response` values of the request, as well as the JSON of the error body\n(much like other response objects in the SDK).\n\nTo handle errors, we recommend that you use the `errors.As` pattern:\n\n```go\n_, err := client.Brand.Get(context.TODO(), contextdev.BrandGetParams{\n\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\tDomain: "stripe.com",\n\t},\n})\nif err != nil {\n\tvar apierr *contextdev.Error\n\tif errors.As(err, &apierr) {\n\t\tprintln(string(apierr.DumpRequest(true))) // Prints the serialized HTTP request\n\t\tprintln(string(apierr.DumpResponse(true))) // Prints the serialized HTTP response\n\t}\n\tpanic(err.Error()) // GET "/brand/retrieve": 400 Bad Request { ... }\n}\n```\n\nWhen other errors occur, they are returned unwrapped; for example,\nif HTTP transport fails, you might receive `*url.Error` wrapping `*net.OpError`.\n\n### Timeouts\n\nRequests do not time out by default; use context to configure a timeout for a request lifecycle.\n\nNote that if a request is [retried](#retries), the context timeout does not start over.\nTo set a per-retry timeout, use `SDK_PackageOptionName.WithRequestTimeout()`.\n\n```go\n// This sets the timeout for the request, including all the retries.\nctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)\ndefer cancel()\nclient.Brand.Get(\n\tctx,\n\tcontextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t},\n\t// This sets the per-retry timeout\n\toption.WithRequestTimeout(20*time.Second),\n)\n```\n\n### File uploads\n\nRequest parameters that correspond to file uploads in multipart requests are typed as\n`param.Field[io.Reader]`. The contents of the `io.Reader` will by default be sent as a multipart form\npart with the file name of "anonymous_file" and content-type of "application/octet-stream".\n\nThe file name and content-type can be customized by implementing `Name() string` or `ContentType()\nstring` on the run-time type of `io.Reader`. Note that `os.File` implements `Name() string`, so a\nfile returned by `os.Open` will be sent with the file name on disk.\n\nWe also provide a helper `SDK_PackageName.FileParam(reader io.Reader, filename string, contentType string)`\nwhich can be used to wrap any `io.Reader` with the appropriate file name and content type.\n\n\n\n### Retries\n\nCertain errors will be automatically retried 2 times by default, with a short exponential backoff.\nWe retry by default all connection errors, 408 Request Timeout, 409 Conflict, 429 Rate Limit,\nand >=500 Internal errors.\n\nYou can use the `WithMaxRetries` option to configure or disable this:\n\n```go\n// Configure the default for all requests:\nclient := contextdev.NewClient(\n\toption.WithMaxRetries(0), // default is 2\n)\n\n// Override per-request:\nclient.Brand.Get(\n\tcontext.TODO(),\n\tcontextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t},\n\toption.WithMaxRetries(5),\n)\n```\n\n\n### Accessing raw response data (e.g. response headers)\n\nYou can access the raw HTTP response data by using the `option.WithResponseInto()` request option. This is useful when\nyou need to examine response headers, status codes, or other details.\n\n```go\n// Create a variable to store the HTTP response\nvar response *http.Response\nbrand, err := client.Brand.Get(\n\tcontext.TODO(),\n\tcontextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t},\n\toption.WithResponseInto(&response),\n)\nif err != nil {\n\t// handle error\n}\nfmt.Printf("%+v\\n", brand)\n\nfmt.Printf("Status Code: %d\\n", response.StatusCode)\nfmt.Printf("Headers: %+#v\\n", response.Header)\n```\n\n### Making custom/undocumented requests\n\nThis library is typed for convenient access to the documented API. If you need to access undocumented\nendpoints, params, or response properties, the library can still be used.\n\n#### Undocumented endpoints\n\nTo make requests to undocumented endpoints, you can use `client.Get`, `client.Post`, and other HTTP verbs.\n`RequestOptions` on the client, such as retries, will be respected when making these requests.\n\n```go\nvar (\n // params can be an io.Reader, a []byte, an encoding/json serializable object,\n // or a "…Params" struct defined in this library.\n params map[string]interface{}\n\n // result can be an []byte, *http.Response, a encoding/json deserializable object,\n // or a model defined in this library.\n result *http.Response\n)\nerr := client.Post(context.Background(), "/unspecified", params, &result)\nif err != nil {\n …\n}\n```\n\n#### Undocumented request params\n\nTo make requests using undocumented parameters, you may use either the `SDK_PackageOptionName.WithQuerySet()`\nor the `SDK_PackageOptionName.WithJSONSet()` methods.\n\n```go\nparams := FooNewParams{\n ID: SDK_PackageName.F("id_xxxx"),\n Data: SDK_PackageName.F(FooNewParamsData{\n FirstName: SDK_PackageName.F("John"),\n }),\n}\nclient.Foo.New(context.Background(), params, SDK_PackageOptionName.WithJSONSet("data.last_name", "Doe"))\n```\n\n#### Undocumented response properties\n\nTo access undocumented response properties, you may either access the raw JSON of the response as a string\nwith `result.JSON.RawJSON()`, or get the raw JSON of a particular field on the result with\n`result.JSON.Foo.Raw()`.\n\nAny fields that are not present on the response struct will be saved and can be accessed by `result.JSON.ExtraFields()` which returns the extra fields as a `map[string]Field`.\n\n### Middleware\n\nWe provide `SDK_PackageOptionName.WithMiddleware` which applies the given\nmiddleware to requests.\n\n```go\nfunc Logger(req *http.Request, next SDK_PackageOptionName.MiddlewareNext) (res *http.Response, err error) {\n\t// Before the request\n\tstart := time.Now()\n\tLogReq(req)\n\n\t// Forward the request to the next handler\n\tres, err = next(req)\n\n\t// Handle stuff after the request\n\tend := time.Now()\n\tLogRes(res, err, start - end)\n\n return res, err\n}\n\nclient := SDK_PackageName.SDK_ClientInitializerName(\n\tSDK_PackageOptionName.WithMiddleware(Logger),\n)\n```\n\nWhen multiple middlewares are provided as variadic arguments, the middlewares\nare applied left to right. If `SDK_PackageOptionName.WithMiddleware` is given\nmultiple times, for example first in the client then the method, the\nmiddleware in the client will run first and the middleware given in the method\nwill run next.\n\nYou may also replace the default `http.Client` with\n`SDK_PackageOptionName.WithHTTPClient(client)`. Only one http client is\naccepted (this overwrites any previous client) and receives requests after any\nmiddleware has been applied.\n\n## Semantic versioning\n\nThis package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:\n\n1. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_\n2. Changes that we do not expect to impact the vast majority of users in practice.\n\nWe take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.\n\nWe are keen for your feedback; please open an [issue](https://www.github.com/context-dot-dev/context-go-sdk/issues) with questions, bugs, or suggestions.\n\n## Contributing\n\nSee [the contributing documentation](./CONTRIBUTING.md).\n', }, { language: 'cli', @@ -2376,7 +2376,7 @@ const EMBEDDED_READMES: { language: string; content: string }[] = [ { language: 'ruby', content: - '# Context Dev Ruby API library\n\nThe Context Dev Ruby library provides convenient access to the Context Dev REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/context-dot-dev/context-ruby-sdk#Sorbet) for usage with Sorbet. The standard library\'s `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.\n\n\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n## MCP Server\n\nUse the Context Dev MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0)\n[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D)\n\n> Note: You may need to set environment variables in your MCP client.\n\n## Documentation\n\nDocumentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/context.dev).\n\nThe REST API documentation can be found on [docs.context.dev](https://docs.context.dev/).\n\n## Installation\n\nTo use this gem, install via Bundler by adding the following to your application\'s `Gemfile`:\n\n\n\n```ruby\ngem "context.dev", "~> 2.12.0"\n```\n\n\n\n## Usage\n\n```ruby\nrequire "bundler/setup"\nrequire "context_dev"\n\ncontext_dev = ContextDev::Client.new(\n api_key: ENV["CONTEXT_DEV_API_KEY"] # This is the default and can be omitted\n)\n\nbrand = context_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"})\n\nputs(brand.cache_metadata)\n```\n\n\n\n\n\n\n\n### Handling errors\n\nWhen the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `ContextDev::Errors::APIError` will be thrown:\n\n```ruby\nbegin\n brand = context_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"})\nrescue ContextDev::Errors::APIConnectionError => e\n puts("The server could not be reached")\n puts(e.cause) # an underlying Exception, likely raised within `net/http`\nrescue ContextDev::Errors::RateLimitError => e\n puts("A 429 status code was received; we should back off a bit.")\nrescue ContextDev::Errors::APIStatusError => e\n puts("Another non-200-range status code was received")\n puts(e.status)\nend\n```\n\nError codes are as follows:\n\n| Cause | Error Type |\n| ---------------- | -------------------------- |\n| HTTP 400 | `BadRequestError` |\n| HTTP 401 | `AuthenticationError` |\n| HTTP 403 | `PermissionDeniedError` |\n| HTTP 404 | `NotFoundError` |\n| HTTP 409 | `ConflictError` |\n| HTTP 422 | `UnprocessableEntityError` |\n| HTTP 429 | `RateLimitError` |\n| HTTP >= 500 | `InternalServerError` |\n| Other HTTP error | `APIStatusError` |\n| Timeout | `APITimeoutError` |\n| Network error | `APIConnectionError` |\n\n### Retries\n\nCertain errors will be automatically retried 2 times by default, with a short exponential backoff.\n\nConnection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.\n\nYou can use the `max_retries` option to configure or disable this:\n\n```ruby\n# Configure the default for all requests:\ncontext_dev = ContextDev::Client.new(\n max_retries: 0 # default is 2\n)\n\n# Or, configure per-request:\ncontext_dev.brand.retrieve(\n body: {domain: "stripe.com", type: "by_domain"},\n request_options: {max_retries: 5}\n)\n```\n\n### Timeouts\n\nBy default, requests will time out after 60 seconds. You can use the timeout option to configure or disable this:\n\n```ruby\n# Configure the default for all requests:\ncontext_dev = ContextDev::Client.new(\n timeout: nil # default is 60\n)\n\n# Or, configure per-request:\ncontext_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"}, request_options: {timeout: 5})\n```\n\nOn timeout, `ContextDev::Errors::APITimeoutError` is raised.\n\nNote that requests that time out are retried by default.\n\n## Advanced concepts\n\n### BaseModel\n\nAll parameter and response objects inherit from `ContextDev::Internal::Type::BaseModel`, which provides several conveniences, including:\n\n1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.\n\n2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.\n\n3. Both instances and the classes themselves can be pretty-printed.\n\n4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.\n\n### Making custom or undocumented requests\n\n#### Undocumented properties\n\nYou can send undocumented parameters to any endpoint, and read undocumented response properties, like so:\n\nNote: the `extra_` parameters of the same name overrides the documented parameters.\n\n```ruby\nbrand =\n context_dev.brand.retrieve(\n body: {domain: "stripe.com", type: "by_domain"},\n request_options: {\n extra_query: {my_query_parameter: value},\n extra_body: {my_body_parameter: value},\n extra_headers: {"my-header": value}\n }\n )\n\nputs(brand[:my_undocumented_property])\n```\n\n#### Undocumented request params\n\nIf you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request, as seen in the examples above.\n\n#### Undocumented endpoints\n\nTo make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using `client.request`, like so:\n\n```ruby\nresponse = client.request(\n method: :post,\n path: \'/undocumented/endpoint\',\n query: {"dog": "woof"},\n headers: {"useful-header": "interesting-value"},\n body: {"hello": "world"}\n)\n```\n\n### Concurrency & connection pooling\n\nThe `ContextDev::Client` instances are threadsafe, but are only are fork-safe when there are no in-flight HTTP requests.\n\nEach instance of `ContextDev::Client` has its own HTTP connection pool with a default size of 99. As such, we recommend instantiating the client once per application in most settings.\n\nWhen all available connections from the pool are checked out, requests wait for a new connection to become available, with queue time counting towards the request timeout.\n\nUnless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.\n\n## Sorbet\n\nThis library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.\n\nYou can provide typesafe request parameters like so:\n\n```ruby\ncontext_dev.brand.retrieve(\n body: ContextDev::BrandRetrieveParams::Body::ByDomain.new(domain: "stripe.com")\n)\n```\n\nOr, equivalently:\n\n```ruby\n# Hashes work, but are not typesafe:\ncontext_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"})\n\n# You can also splat a full Params class:\nparams = ContextDev::BrandRetrieveParams.new(\n body: ContextDev::BrandRetrieveParams::Body::ByDomain.new(domain: "stripe.com")\n)\ncontext_dev.brand.retrieve(**params)\n```\n\n### Enums\n\nSince this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:\n\n```ruby\n# :txt\nputs(ContextDev::ParseHandleParams::Extension::TXT)\n\n# Revealed type: `T.all(ContextDev::ParseHandleParams::Extension, Symbol)`\nT.reveal_type(ContextDev::ParseHandleParams::Extension::TXT)\n```\n\nEnum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:\n\n```ruby\n# Using the enum constants preserves the tagged type information:\ncontext_dev.parse.handle(\n extension: ContextDev::ParseHandleParams::Extension::TXT,\n # …\n)\n\n# Literal values are also permissible:\ncontext_dev.parse.handle(\n extension: :txt,\n # …\n)\n```\n\n## Versioning\n\nThis package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.\n\nThis package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.\n\n## Requirements\n\nRuby 3.2.0 or higher.\n\n## Contributing\n\nSee [the contributing documentation](https://github.com/context-dot-dev/context-ruby-sdk/tree/main/CONTRIBUTING.md).\n', + '# Context Dev Ruby API library\n\nThe Context Dev Ruby library provides convenient access to the Context Dev REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/context-dot-dev/context-ruby-sdk#Sorbet) for usage with Sorbet. The standard library\'s `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.\n\n\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n## MCP Server\n\nUse the Context Dev MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0)\n[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D)\n\n> Note: You may need to set environment variables in your MCP client.\n\n## Documentation\n\nDocumentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/context.dev).\n\nThe REST API documentation can be found on [docs.context.dev](https://docs.context.dev/).\n\n## Installation\n\nTo use this gem, install via Bundler by adding the following to your application\'s `Gemfile`:\n\n\n\n```ruby\ngem "context.dev", "~> 2.13.0"\n```\n\n\n\n## Usage\n\n```ruby\nrequire "bundler/setup"\nrequire "context_dev"\n\ncontext_dev = ContextDev::Client.new(\n api_key: ENV["CONTEXT_DEV_API_KEY"] # This is the default and can be omitted\n)\n\nbrand = context_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"})\n\nputs(brand.cache_metadata)\n```\n\n\n\n\n\n\n\n### Handling errors\n\nWhen the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `ContextDev::Errors::APIError` will be thrown:\n\n```ruby\nbegin\n brand = context_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"})\nrescue ContextDev::Errors::APIConnectionError => e\n puts("The server could not be reached")\n puts(e.cause) # an underlying Exception, likely raised within `net/http`\nrescue ContextDev::Errors::RateLimitError => e\n puts("A 429 status code was received; we should back off a bit.")\nrescue ContextDev::Errors::APIStatusError => e\n puts("Another non-200-range status code was received")\n puts(e.status)\nend\n```\n\nError codes are as follows:\n\n| Cause | Error Type |\n| ---------------- | -------------------------- |\n| HTTP 400 | `BadRequestError` |\n| HTTP 401 | `AuthenticationError` |\n| HTTP 403 | `PermissionDeniedError` |\n| HTTP 404 | `NotFoundError` |\n| HTTP 409 | `ConflictError` |\n| HTTP 422 | `UnprocessableEntityError` |\n| HTTP 429 | `RateLimitError` |\n| HTTP >= 500 | `InternalServerError` |\n| Other HTTP error | `APIStatusError` |\n| Timeout | `APITimeoutError` |\n| Network error | `APIConnectionError` |\n\n### Retries\n\nCertain errors will be automatically retried 2 times by default, with a short exponential backoff.\n\nConnection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.\n\nYou can use the `max_retries` option to configure or disable this:\n\n```ruby\n# Configure the default for all requests:\ncontext_dev = ContextDev::Client.new(\n max_retries: 0 # default is 2\n)\n\n# Or, configure per-request:\ncontext_dev.brand.retrieve(\n body: {domain: "stripe.com", type: "by_domain"},\n request_options: {max_retries: 5}\n)\n```\n\n### Timeouts\n\nBy default, requests will time out after 60 seconds. You can use the timeout option to configure or disable this:\n\n```ruby\n# Configure the default for all requests:\ncontext_dev = ContextDev::Client.new(\n timeout: nil # default is 60\n)\n\n# Or, configure per-request:\ncontext_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"}, request_options: {timeout: 5})\n```\n\nOn timeout, `ContextDev::Errors::APITimeoutError` is raised.\n\nNote that requests that time out are retried by default.\n\n## Advanced concepts\n\n### BaseModel\n\nAll parameter and response objects inherit from `ContextDev::Internal::Type::BaseModel`, which provides several conveniences, including:\n\n1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.\n\n2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.\n\n3. Both instances and the classes themselves can be pretty-printed.\n\n4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.\n\n### Making custom or undocumented requests\n\n#### Undocumented properties\n\nYou can send undocumented parameters to any endpoint, and read undocumented response properties, like so:\n\nNote: the `extra_` parameters of the same name overrides the documented parameters.\n\n```ruby\nbrand =\n context_dev.brand.retrieve(\n body: {domain: "stripe.com", type: "by_domain"},\n request_options: {\n extra_query: {my_query_parameter: value},\n extra_body: {my_body_parameter: value},\n extra_headers: {"my-header": value}\n }\n )\n\nputs(brand[:my_undocumented_property])\n```\n\n#### Undocumented request params\n\nIf you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request, as seen in the examples above.\n\n#### Undocumented endpoints\n\nTo make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using `client.request`, like so:\n\n```ruby\nresponse = client.request(\n method: :post,\n path: \'/undocumented/endpoint\',\n query: {"dog": "woof"},\n headers: {"useful-header": "interesting-value"},\n body: {"hello": "world"}\n)\n```\n\n### Concurrency & connection pooling\n\nThe `ContextDev::Client` instances are threadsafe, but are only are fork-safe when there are no in-flight HTTP requests.\n\nEach instance of `ContextDev::Client` has its own HTTP connection pool with a default size of 99. As such, we recommend instantiating the client once per application in most settings.\n\nWhen all available connections from the pool are checked out, requests wait for a new connection to become available, with queue time counting towards the request timeout.\n\nUnless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.\n\n## Sorbet\n\nThis library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.\n\nYou can provide typesafe request parameters like so:\n\n```ruby\ncontext_dev.brand.retrieve(\n body: ContextDev::BrandRetrieveParams::Body::ByDomain.new(domain: "stripe.com")\n)\n```\n\nOr, equivalently:\n\n```ruby\n# Hashes work, but are not typesafe:\ncontext_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"})\n\n# You can also splat a full Params class:\nparams = ContextDev::BrandRetrieveParams.new(\n body: ContextDev::BrandRetrieveParams::Body::ByDomain.new(domain: "stripe.com")\n)\ncontext_dev.brand.retrieve(**params)\n```\n\n### Enums\n\nSince this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:\n\n```ruby\n# :txt\nputs(ContextDev::ParseHandleParams::Extension::TXT)\n\n# Revealed type: `T.all(ContextDev::ParseHandleParams::Extension, Symbol)`\nT.reveal_type(ContextDev::ParseHandleParams::Extension::TXT)\n```\n\nEnum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:\n\n```ruby\n# Using the enum constants preserves the tagged type information:\ncontext_dev.parse.handle(\n extension: ContextDev::ParseHandleParams::Extension::TXT,\n # …\n)\n\n# Literal values are also permissible:\ncontext_dev.parse.handle(\n extension: :txt,\n # …\n)\n```\n\n## Versioning\n\nThis package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.\n\nThis package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.\n\n## Requirements\n\nRuby 3.2.0 or higher.\n\n## Contributing\n\nSee [the contributing documentation](https://github.com/context-dot-dev/context-ruby-sdk/tree/main/CONTRIBUTING.md).\n', }, { language: 'typescript', diff --git a/packages/mcp-server/src/server.ts b/packages/mcp-server/src/server.ts index 193f5ed0..31404104 100644 --- a/packages/mcp-server/src/server.ts +++ b/packages/mcp-server/src/server.ts @@ -28,7 +28,7 @@ export const newMcpServer = async ({ new McpServer( { name: 'context_dev_api', - version: '2.13.0', + version: '2.14.0', }, { instructions: await getInstructions({ stainlessApiKey, customInstructionsPath }), From e4d6af5fb79b51b93411ce22514036e63aac8ac7 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 27 Aug 2026 19:00:10 +0000 Subject: [PATCH 002/232] Build SDK Stainless-Generated-From: d0e73d9ee0371727d6842533ae84030da198bec7 --- .dockerignore | 59 - .gitignore | 2 - .prettierignore | 3 +- README.md | 9 - eslint.config.mjs | 2 +- packages/mcp-server/Dockerfile | 78 - packages/mcp-server/README.md | 101 - packages/mcp-server/build | 56 - packages/mcp-server/jest.config.ts | 17 - packages/mcp-server/manifest.json | 47 - packages/mcp-server/package.json | 96 - .../mcp-server/scripts/copy-bundle-files.cjs | 36 - .../scripts/postprocess-dist-package-json.cjs | 12 - packages/mcp-server/src/auth.ts | 42 - packages/mcp-server/src/code-tool-paths.cts | 5 - packages/mcp-server/src/code-tool-types.ts | 17 - packages/mcp-server/src/code-tool-worker.ts | 320 -- packages/mcp-server/src/code-tool.ts | 315 -- packages/mcp-server/src/docs-search-tool.ts | 79 - packages/mcp-server/src/http.ts | 227 - packages/mcp-server/src/index.ts | 67 - packages/mcp-server/src/instructions.ts | 57 - packages/mcp-server/src/local-docs-search.ts | 2661 ----------- packages/mcp-server/src/logger.ts | 28 - packages/mcp-server/src/methods.ts | 332 -- packages/mcp-server/src/options.ts | 185 - packages/mcp-server/src/server.ts | 208 - packages/mcp-server/src/stdio.ts | 17 - packages/mcp-server/src/types.ts | 126 - packages/mcp-server/src/util.ts | 25 - packages/mcp-server/tests/options.test.ts | 32 - packages/mcp-server/tsc-multi.json | 7 - packages/mcp-server/tsconfig.build.json | 18 - packages/mcp-server/tsconfig.dist-src.json | 11 - packages/mcp-server/tsconfig.json | 36 - packages/mcp-server/yarn.lock | 4169 ----------------- scripts/build | 6 - scripts/build-all | 5 - scripts/publish-packages.ts | 102 - scripts/utils/make-dist-package-json.cjs | 8 - 40 files changed, 2 insertions(+), 9621 deletions(-) delete mode 100644 .dockerignore delete mode 100644 packages/mcp-server/Dockerfile delete mode 100644 packages/mcp-server/README.md delete mode 100644 packages/mcp-server/build delete mode 100644 packages/mcp-server/jest.config.ts delete mode 100644 packages/mcp-server/manifest.json delete mode 100644 packages/mcp-server/package.json delete mode 100644 packages/mcp-server/scripts/copy-bundle-files.cjs delete mode 100644 packages/mcp-server/scripts/postprocess-dist-package-json.cjs delete mode 100644 packages/mcp-server/src/auth.ts delete mode 100644 packages/mcp-server/src/code-tool-paths.cts delete mode 100644 packages/mcp-server/src/code-tool-types.ts delete mode 100644 packages/mcp-server/src/code-tool-worker.ts delete mode 100644 packages/mcp-server/src/code-tool.ts delete mode 100644 packages/mcp-server/src/docs-search-tool.ts delete mode 100644 packages/mcp-server/src/http.ts delete mode 100644 packages/mcp-server/src/index.ts delete mode 100644 packages/mcp-server/src/instructions.ts delete mode 100644 packages/mcp-server/src/local-docs-search.ts delete mode 100644 packages/mcp-server/src/logger.ts delete mode 100644 packages/mcp-server/src/methods.ts delete mode 100644 packages/mcp-server/src/options.ts delete mode 100644 packages/mcp-server/src/server.ts delete mode 100644 packages/mcp-server/src/stdio.ts delete mode 100644 packages/mcp-server/src/types.ts delete mode 100644 packages/mcp-server/src/util.ts delete mode 100644 packages/mcp-server/tests/options.test.ts delete mode 100644 packages/mcp-server/tsc-multi.json delete mode 100644 packages/mcp-server/tsconfig.build.json delete mode 100644 packages/mcp-server/tsconfig.dist-src.json delete mode 100644 packages/mcp-server/tsconfig.json delete mode 100644 packages/mcp-server/yarn.lock delete mode 100755 scripts/build-all delete mode 100644 scripts/publish-packages.ts diff --git a/.dockerignore b/.dockerignore deleted file mode 100644 index 12ff1e64..00000000 --- a/.dockerignore +++ /dev/null @@ -1,59 +0,0 @@ -# Dependencies -node_modules/ -**/node_modules/ - -# Build outputs -dist/ -**/dist/ - -# Git -.git/ -.gitignore - -# CI/CD -.github/ -.gitlab-ci.yml -.travis.yml - -# IDE -.vscode/ -.idea/ -*.swp -*.swo -*~ - -# OS -.DS_Store -Thumbs.db - -# Testing -test/ -tests/ -__tests__/ -*.test.js -*.spec.js -coverage/ -.nyc_output/ - -# Logs -*.log -npm-debug.log* -yarn-debug.log* -yarn-error.log* - -# Environment -.env -.env.* - -# Temporary files -*.tmp -*.temp -.cache/ - -# Examples and scripts -examples/ -bin/ - -# Other packages (we only need mcp-server) -packages/*/ -!packages/mcp-server/ diff --git a/.gitignore b/.gitignore index ae4aa20e..9487e48a 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,4 @@ dist-deno /*.tgz .idea/ .eslintcache -dist-bundle -*.mcpb oidc diff --git a/.prettierignore b/.prettierignore index 36afd3b3..3548c5af 100644 --- a/.prettierignore +++ b/.prettierignore @@ -2,7 +2,6 @@ CHANGELOG.md /ecosystem-tests/*/** /node_modules /deno -/packages/mcp-server/manifest.json # don't format tsc output, will break source maps -dist +/dist diff --git a/README.md b/README.md index edfa7cc5..503becae 100644 --- a/README.md +++ b/README.md @@ -8,15 +8,6 @@ The REST API documentation can be found on [docs.context.dev](https://docs.conte It is generated with [Stainless](https://www.stainless.com/). -## MCP Server - -Use the Context Dev MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application. - -[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0) -[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D) - -> Note: You may need to set environment variables in your MCP client. - ## Installation ```sh diff --git a/eslint.config.mjs b/eslint.config.mjs index 18b8b5ae..2712a3e0 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -31,7 +31,7 @@ export default tseslint.config( }, }, { - files: ['tests/**', 'examples/**', 'packages/**'], + files: ['tests/**', 'examples/**'], rules: { 'no-restricted-imports': 'off', }, diff --git a/packages/mcp-server/Dockerfile b/packages/mcp-server/Dockerfile deleted file mode 100644 index a3140e2f..00000000 --- a/packages/mcp-server/Dockerfile +++ /dev/null @@ -1,78 +0,0 @@ -# Dockerfile for Context Dev MCP Server -# -# This Dockerfile builds a Docker image for the MCP Server. -# -# To build the image locally: -# docker build -f packages/mcp-server/Dockerfile -t context.dev-mcp:local . -# -# To run the image: -# docker run -i context.dev-mcp:local [OPTIONS] -# -# Common options: -# --tool= Include specific tools -# --resource= Include tools for specific resources -# --operation=read|write Filter by operation type -# --client= Set client compatibility (e.g., claude, cursor) -# --transport= Set transport type (stdio or http) -# -# For a full list of options: -# docker run -i context.dev-mcp:local --help -# -# Note: The MCP server uses stdio transport by default. Docker's -i flag -# enables interactive mode, allowing the container to communicate over stdin/stdout. - -# Build stage -FROM node:24-alpine AS builder - -# Install bash for build script -RUN apk add --no-cache bash openssl - -# Set working directory -WORKDIR /build - -# Copy entire repository -COPY . . - -# Install all dependencies and build everything -RUN yarn install --frozen-lockfile && \ - yarn build && \ - # Remove the symlink to the SDK so it doesn't interfere with the explicit COPY below - rm -Rf packages/mcp-server/node_modules/context.dev - -FROM denoland/deno:alpine-2.7.1 - -# Install node and npm -RUN apk add --no-cache nodejs npm - -ENV LD_LIBRARY_PATH=/usr/lib:/usr/local/lib - -# Add non-root user -RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001 - -# Set working directory -WORKDIR /app - -# Copy the built mcp-server dist directory -COPY --from=builder /build/packages/mcp-server/dist ./ - -# Copy node_modules from mcp-server (includes all production deps) -COPY --from=builder /build/packages/mcp-server/node_modules ./node_modules - -# Copy the built context.dev into node_modules -COPY --from=builder /build/dist ./node_modules/context.dev - -# Change ownership to nodejs user -RUN chown -R nodejs:nodejs /app -RUN chown -R nodejs:nodejs /deno-dir - -# Switch to non-root user -USER nodejs - -# The MCP server uses stdio transport by default -# No exposed ports needed for stdio communication - -# Set the entrypoint to the MCP server -ENTRYPOINT ["node", "index.js"] - -# Allow passing arguments to the MCP server -CMD [] diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.md deleted file mode 100644 index e1b2506f..00000000 --- a/packages/mcp-server/README.md +++ /dev/null @@ -1,101 +0,0 @@ -# Context Dev TypeScript MCP Server - -It is generated with [Stainless](https://www.stainless.com/). - -## Installation - -### Direct invocation - -You can run the MCP Server directly via `npx`: - -```sh -export CONTEXT_DEV_API_KEY="My API Key" -npx -y context.dev-mcp@latest -``` - -### Via MCP Client - -There is a partial list of existing clients at [modelcontextprotocol.io](https://modelcontextprotocol.io/clients). If you already -have a client, consult their documentation to install the MCP server. - -For clients with a configuration JSON, it might look something like this: - -```json -{ - "mcpServers": { - "context_dev_api": { - "command": "npx", - "args": ["-y", "context.dev-mcp"], - "env": { - "CONTEXT_DEV_API_KEY": "My API Key" - } - } - } -} -``` - -### Cursor - -If you use Cursor, you can install the MCP server by using the button below. You will need to set your environment variables -in Cursor's `mcp.json`, which can be found in Cursor Settings > Tools & MCP > New MCP Server. - -[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0) - -### VS Code - -If you use MCP, you can install the MCP server by clicking the link below. You will need to set your environment variables -in VS Code's `mcp.json`, which can be found via Command Palette > MCP: Open User Configuration. - -[Open VS Code](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D) - -### Claude Code - -If you use Claude Code, you can install the MCP server by running the command below in your terminal. You will need to set your -environment variables in Claude Code's `.claude.json`, which can be found in your home directory. - -``` -claude mcp add context.dev_mcp_api --env CONTEXT_DEV_API_KEY="My API Key" -- npx -y context.dev-mcp -``` - -## Code Mode - -This MCP server is built on the "Code Mode" tool scheme. In this MCP Server, -your agent will write code against the TypeScript SDK, which will then be executed in an -isolated sandbox. To accomplish this, the server will expose two tools to your agent: - -- The first tool is a docs search tool, which can be used to generically query for - documentation about your API/SDK. - -- The second tool is a code tool, where the agent can write code against the TypeScript SDK. - The code will be executed in a sandbox environment without web or filesystem access. Then, - anything the code returns or prints will be returned to the agent as the result of the - tool call. - -Using this scheme, agents are capable of performing very complex tasks deterministically -and repeatably. - -## Running remotely - -Launching the client with `--transport=http` launches the server as a remote server using Streamable HTTP transport. The `--port` setting can choose the port it will run on, and the `--socket` setting allows it to run on a Unix socket. - -Authorization can be provided via the `Authorization` header using the Bearer scheme. - -Additionally, authorization can be provided via the following headers: -| Header | Equivalent client option | Security scheme | -| ----------------------- | ------------------------ | --------------- | -| `x-context-dev-api-key` | `apiKey` | bearerAuth | - -A configuration JSON for this server might look like this, assuming the server is hosted at `http://localhost:3000`: - -```json -{ - "mcpServers": { - "context_dev_api": { - "url": "http://localhost:3000", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` diff --git a/packages/mcp-server/build b/packages/mcp-server/build deleted file mode 100644 index 7772183c..00000000 --- a/packages/mcp-server/build +++ /dev/null @@ -1,56 +0,0 @@ -#!/usr/bin/env bash -set -exuo pipefail - -rm -rf dist; mkdir dist - -# Copy src to dist/src and build from dist/src into dist, so that -# the source map for index.js.map will refer to ./src/index.ts etc -cp -rp src README.md dist - -for file in LICENSE; do - if [ -e "../../${file}" ]; then cp "../../${file}" dist; fi -done - -for file in CHANGELOG.md; do - if [ -e "${file}" ]; then cp "${file}" dist; fi -done - -# this converts the export map paths for the dist directory -# and does a few other minor things -PKG_JSON_PATH=../../packages/mcp-server/package.json node ../../scripts/utils/make-dist-package-json.cjs > dist/package.json - -# updates the `context.dev` dependency to point to NPM -node scripts/postprocess-dist-package-json.cjs - -# build to .js/.mjs/.d.ts files -./node_modules/.bin/tsc-multi - -cp tsconfig.dist-src.json dist/src/tsconfig.json - -chmod +x dist/index.js - -DIST_PATH=./dist PKG_IMPORT_PATH=context.dev-mcp/ node ../../scripts/utils/postprocess-files.cjs - -# mcp bundle -rm -rf dist-bundle context_dev_api.mcpb; mkdir dist-bundle - -# copy package.json -PKG_JSON_PATH=../../packages/mcp-server/package.json node ../../scripts/utils/make-dist-package-json.cjs > dist-bundle/package.json - -# copy files -node scripts/copy-bundle-files.cjs - -# install runtime deps -cd dist-bundle -npm install -cd .. - -# pack bundle -cp manifest.json dist-bundle - -npx mcpb pack dist-bundle context_dev_api.mcpb - -npx mcpb sign context_dev_api.mcpb --self-signed - -# clean up -rm -rf dist-bundle diff --git a/packages/mcp-server/jest.config.ts b/packages/mcp-server/jest.config.ts deleted file mode 100644 index 6935ead2..00000000 --- a/packages/mcp-server/jest.config.ts +++ /dev/null @@ -1,17 +0,0 @@ -import type { JestConfigWithTsJest } from 'ts-jest'; - -const config: JestConfigWithTsJest = { - preset: 'ts-jest/presets/default-esm', - testEnvironment: 'node', - transform: { - '^.+\\.(t|j)sx?$': ['@swc/jest', { sourceMaps: 'inline' }], - }, - moduleNameMapper: { - '^context.dev-mcp$': '/src/index.ts', - '^context.dev-mcp/(.*)$': '/src/$1', - }, - modulePathIgnorePatterns: ['/dist/'], - testPathIgnorePatterns: ['scripts'], -}; - -export default config; diff --git a/packages/mcp-server/manifest.json b/packages/mcp-server/manifest.json deleted file mode 100644 index a922fa45..00000000 --- a/packages/mcp-server/manifest.json +++ /dev/null @@ -1,47 +0,0 @@ -{ - "dxt_version": "0.2", - "name": "context.dev-mcp", - "version": "2.14.0", - "description": "The official MCP Server for the Context Dev API", - "author": { - "name": "Context Dev", - "email": "hello@context.dev" - }, - "repository": { - "type": "git", - "url": "git+https://github.com/context-dot-dev/context-typescript-sdk.git" - }, - "homepage": "https://github.com/context-dot-dev/context-typescript-sdk/tree/main/packages/mcp-server#readme", - "documentation": "https://docs.context.dev/", - "server": { - "type": "node", - "entry_point": "index.js", - "mcp_config": { - "command": "node", - "args": [ - "${__dirname}/index.js" - ], - "env": { - "CONTEXT_DEV_API_KEY": "${user_config.CONTEXT_DEV_API_KEY}" - } - } - }, - "user_config": { - "CONTEXT_DEV_API_KEY": { - "title": "api_key", - "description": "", - "required": true, - "type": "string" - } - }, - "tools": [], - "tools_generated": true, - "compatibility": { - "runtimes": { - "node": ">=18.0.0" - } - }, - "keywords": [ - "api" - ] -} diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json deleted file mode 100644 index 25a509b8..00000000 --- a/packages/mcp-server/package.json +++ /dev/null @@ -1,96 +0,0 @@ -{ - "name": "context.dev-mcp", - "version": "2.14.0", - "description": "The official MCP Server for the Context Dev API", - "author": "Context Dev ", - "types": "dist/index.d.ts", - "main": "dist/index.js", - "type": "commonjs", - "repository": { - "type": "git", - "url": "git+https://github.com/context-dot-dev/context-typescript-sdk.git", - "directory": "packages/mcp-server" - }, - "homepage": "https://github.com/context-dot-dev/context-typescript-sdk/tree/main/packages/mcp-server#readme", - "license": "Apache-2.0", - "packageManager": "yarn@1.22.22", - "private": false, - "publishConfig": { - "access": "public" - }, - "scripts": { - "test": "jest", - "build": "bash ./build", - "prepack": "echo 'to pack, run yarn build && (cd dist; yarn pack)' && exit 1", - "prepublishOnly": "echo 'to publish, run yarn build && (cd dist; yarn publish)' && exit 1", - "format": "prettier --write --cache --cache-strategy metadata . !dist", - "prepare": "npm run build", - "tsn": "ts-node -r tsconfig-paths/register", - "lint": "eslint .", - "fix": "eslint --fix ." - }, - "dependencies": { - "context.dev": "link:../../dist/", - "ajv": "^8.18.0", - "@cloudflare/cabidela": "^0.2.4", - "@hono/node-server": "^1.19.10", - "@modelcontextprotocol/sdk": "^1.27.1", - "hono": "^4.12.4", - "@valtown/deno-http-worker": "^0.0.21", - "cookie-parser": "^1.4.6", - "cors": "^2.8.5", - "express": "^5.1.0", - "fuse.js": "^7.1.0", - "minisearch": "^7.2.0", - "jq-web": "https://github.com/stainless-api/jq-web/releases/download/v0.8.8/jq-web.tar.gz", - "pino": "^10.3.1", - "pino-http": "^11.0.0", - "pino-pretty": "^13.1.3", - "qs": "^6.14.1", - "typescript": "5.8.3", - "yargs": "^17.7.2", - "zod": "^3.25.20", - "zod-to-json-schema": "^3.24.5", - "zod-validation-error": "^4.0.1" - }, - "bin": { - "mcp-server": "dist/index.js" - }, - "devDependencies": { - "@anthropic-ai/mcpb": "^2.1.2", - "@types/cookie-parser": "^1.4.10", - "@types/cors": "^2.8.19", - "@types/express": "^5.0.3", - "@types/jest": "^29.4.0", - "@types/qs": "^6.14.0", - "@types/yargs": "^17.0.8", - "@typescript-eslint/eslint-plugin": "8.31.1", - "@typescript-eslint/parser": "8.31.1", - "eslint": "^9.39.1", - "eslint-plugin-prettier": "^5.4.1", - "eslint-plugin-unused-imports": "^4.1.4", - "jest": "^29.4.0", - "prettier": "^3.0.0", - "ts-jest": "^29.1.0", - "ts-morph": "^19.0.0", - "ts-node": "^10.5.0", - "tsc-multi": "https://github.com/stainless-api/tsc-multi/releases/download/v1.1.11/tsc-multi.tgz", - "tsconfig-paths": "^4.0.0" - }, - "imports": { - "context.dev-mcp": ".", - "context.dev-mcp/*": "./src/*" - }, - "exports": { - ".": { - "require": "./dist/index.js", - "default": "./dist/index.mjs" - }, - "./*.mjs": "./dist/*.mjs", - "./*.js": "./dist/*.js", - "./*": { - "require": "./dist/*.js", - "default": "./dist/*.mjs" - } - } -} diff --git a/packages/mcp-server/scripts/copy-bundle-files.cjs b/packages/mcp-server/scripts/copy-bundle-files.cjs deleted file mode 100644 index 5681886c..00000000 --- a/packages/mcp-server/scripts/copy-bundle-files.cjs +++ /dev/null @@ -1,36 +0,0 @@ -const fs = require('fs'); -const path = require('path'); -const pkgJson = require('../dist-bundle/package.json'); - -const distDir = path.resolve(__dirname, '..', 'dist'); -const distBundleDir = path.resolve(__dirname, '..', 'dist-bundle'); -const distBundlePkgJson = path.join(distBundleDir, 'package.json'); - -async function* walk(dir) { - for await (const d of await fs.promises.opendir(dir)) { - const entry = path.join(dir, d.name); - if (d.isDirectory()) yield* walk(entry); - else if (d.isFile()) yield entry; - } -} - -async function copyFiles() { - // copy runtime files - for await (const file of walk(distDir)) { - if (!/[cm]?js$/.test(file)) continue; - const dest = path.join(distBundleDir, path.relative(distDir, file)); - await fs.promises.mkdir(path.dirname(dest), { recursive: true }); - await fs.promises.copyFile(file, dest); - } - - // replace package.json reference with local reference - for (const dep in pkgJson.dependencies) { - if (dep === 'context.dev') { - pkgJson.dependencies[dep] = 'file:../../../dist/'; - } - } - - await fs.promises.writeFile(distBundlePkgJson, JSON.stringify(pkgJson, null, 2)); -} - -copyFiles(); diff --git a/packages/mcp-server/scripts/postprocess-dist-package-json.cjs b/packages/mcp-server/scripts/postprocess-dist-package-json.cjs deleted file mode 100644 index da147f99..00000000 --- a/packages/mcp-server/scripts/postprocess-dist-package-json.cjs +++ /dev/null @@ -1,12 +0,0 @@ -const fs = require('fs'); -const pkgJson = require('../dist/package.json'); -const parentPkgJson = require('../../../package.json'); - -for (const dep in pkgJson.dependencies) { - // ensure we point to NPM instead of a local directory - if (dep === 'context.dev') { - pkgJson.dependencies[dep] = '^' + parentPkgJson.version; - } -} - -fs.writeFileSync('dist/package.json', JSON.stringify(pkgJson, null, 2)); diff --git a/packages/mcp-server/src/auth.ts b/packages/mcp-server/src/auth.ts deleted file mode 100644 index 935a1b16..00000000 --- a/packages/mcp-server/src/auth.ts +++ /dev/null @@ -1,42 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { IncomingMessage } from 'node:http'; -import { ClientOptions } from 'context.dev'; -import { McpOptions } from './options'; - -export const parseClientAuthHeaders = (req: IncomingMessage, required?: boolean): Partial => { - if (req.headers.authorization) { - const scheme = req.headers.authorization.split(' ')[0]!; - const value = req.headers.authorization.slice(scheme.length + 1); - switch (scheme) { - case 'Bearer': - return { apiKey: req.headers.authorization.slice('Bearer '.length) }; - default: - throw new Error( - 'Unsupported authorization scheme. Expected the "Authorization" header to be a supported scheme (Bearer).', - ); - } - } else if (required) { - throw new Error('Missing required Authorization header; see WWW-Authenticate header for details.'); - } - - const apiKey = - Array.isArray(req.headers['x-context-dev-api-key']) ? - req.headers['x-context-dev-api-key'][0] - : req.headers['x-context-dev-api-key']; - return { apiKey }; -}; - -export const getStainlessApiKey = (req: IncomingMessage, mcpOptions: McpOptions): string | undefined => { - // Try to get the key from the x-stainless-api-key header - const headerKey = - Array.isArray(req.headers['x-stainless-api-key']) ? - req.headers['x-stainless-api-key'][0] - : req.headers['x-stainless-api-key']; - if (headerKey && typeof headerKey === 'string') { - return headerKey; - } - - // Fall back to value set in the mcpOptions (e.g. from environment variable), if provided - return mcpOptions.stainlessApiKey; -}; diff --git a/packages/mcp-server/src/code-tool-paths.cts b/packages/mcp-server/src/code-tool-paths.cts deleted file mode 100644 index 78263e45..00000000 --- a/packages/mcp-server/src/code-tool-paths.cts +++ /dev/null @@ -1,5 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -export function getWorkerPath(): string { - return require.resolve('./code-tool-worker.mjs'); -} diff --git a/packages/mcp-server/src/code-tool-types.ts b/packages/mcp-server/src/code-tool-types.ts deleted file mode 100644 index 21108d89..00000000 --- a/packages/mcp-server/src/code-tool-types.ts +++ /dev/null @@ -1,17 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { ClientOptions } from 'context.dev'; - -export type WorkerInput = { - project_name: string; - code: string; - client_opts: ClientOptions; - intent?: string | undefined; -}; - -export type WorkerOutput = { - is_error: boolean; - result: unknown | null; - log_lines: string[]; - err_lines: string[]; -}; diff --git a/packages/mcp-server/src/code-tool-worker.ts b/packages/mcp-server/src/code-tool-worker.ts deleted file mode 100644 index c66589ea..00000000 --- a/packages/mcp-server/src/code-tool-worker.ts +++ /dev/null @@ -1,320 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import path from 'node:path'; -import util from 'node:util'; -import Fuse from 'fuse.js'; -import ts from 'typescript'; -import { WorkerOutput } from './code-tool-types'; -import { ContextDev, ClientOptions } from 'context.dev'; - -async function tseval(code: string) { - return import('data:application/typescript;charset=utf-8;base64,' + Buffer.from(code).toString('base64')); -} - -function getRunFunctionSource(code: string): { - type: 'declaration' | 'expression'; - client: string | undefined; - code: string; -} | null { - const sourceFile = ts.createSourceFile('code.ts', code, ts.ScriptTarget.Latest, true); - const printer = ts.createPrinter(); - - for (const statement of sourceFile.statements) { - // Check for top-level function declarations - if (ts.isFunctionDeclaration(statement)) { - if (statement.name?.text === 'run') { - return { - type: 'declaration', - client: statement.parameters[0]?.name.getText(), - code: printer.printNode(ts.EmitHint.Unspecified, statement.body!, sourceFile), - }; - } - } - - // Check for variable declarations: const run = () => {} or const run = function() {} - if (ts.isVariableStatement(statement)) { - for (const declaration of statement.declarationList.declarations) { - if ( - ts.isIdentifier(declaration.name) && - declaration.name.text === 'run' && - // Check if it's initialized with a function - declaration.initializer && - (ts.isFunctionExpression(declaration.initializer) || ts.isArrowFunction(declaration.initializer)) - ) { - return { - type: 'expression', - client: declaration.initializer.parameters[0]?.name.getText(), - code: printer.printNode(ts.EmitHint.Unspecified, declaration.initializer, sourceFile), - }; - } - } - } - } - - return null; -} - -function getTSDiagnostics(code: string): string[] { - const functionSource = getRunFunctionSource(code)!; - const codeWithImport = [ - 'import { ContextDev } from "context.dev";', - functionSource.type === 'declaration' ? - `async function run(${functionSource.client}: ContextDev)` - : `const run: (${functionSource.client}: ContextDev) => Promise =`, - functionSource.code, - ].join('\n'); - const sourcePath = path.resolve('code.ts'); - const ast = ts.createSourceFile(sourcePath, codeWithImport, ts.ScriptTarget.Latest, true); - const options = ts.getDefaultCompilerOptions(); - options.target = ts.ScriptTarget.Latest; - options.module = ts.ModuleKind.NodeNext; - options.moduleResolution = ts.ModuleResolutionKind.NodeNext; - const host = ts.createCompilerHost(options, true); - const newHost: typeof host = { - ...host, - getSourceFile: (...args) => { - if (path.resolve(args[0]) === sourcePath) { - return ast; - } - return host.getSourceFile(...args); - }, - readFile: (...args) => { - if (path.resolve(args[0]) === sourcePath) { - return codeWithImport; - } - return host.readFile(...args); - }, - fileExists: (...args) => { - if (path.resolve(args[0]) === sourcePath) { - return true; - } - return host.fileExists(...args); - }, - }; - const program = ts.createProgram({ - options, - rootNames: [sourcePath], - host: newHost, - }); - const diagnostics = ts.getPreEmitDiagnostics(program, ast); - return diagnostics.map((d) => { - const message = ts.flattenDiagnosticMessageText(d.messageText, '\n'); - if (!d.file || !d.start) return `- ${message}`; - const { line: lineNumber } = ts.getLineAndCharacterOfPosition(d.file, d.start); - const line = codeWithImport.split('\n').at(lineNumber)?.trim(); - return line ? `- ${message}\n ${line}` : `- ${message}`; - }); -} - -const fuse = new Fuse( - [ - 'client.parse.handle', - 'client.web.extract', - 'client.web.extractCompetitors', - 'client.web.extractFonts', - 'client.web.extractStyleguide', - 'client.web.screenshot', - 'client.web.search', - 'client.web.webCrawlMd', - 'client.web.webScrapeHTML', - 'client.web.webScrapeImages', - 'client.web.webScrapeMd', - 'client.web.webScrapeSitemap', - 'client.ai.extractProduct', - 'client.ai.extractProducts', - 'client.brand.retrieve', - 'client.brand.retrieveSimplified', - 'client.brand.search', - 'client.industry.retrieveNaics', - 'client.industry.retrieveSic', - 'client.utility.prefetch', - 'client.monitors.create', - 'client.monitors.delete', - 'client.monitors.getCreditUsage', - 'client.monitors.getLimits', - 'client.monitors.list', - 'client.monitors.listAccountChanges', - 'client.monitors.listAccountRuns', - 'client.monitors.listChanges', - 'client.monitors.listRuns', - 'client.monitors.retrieve', - 'client.monitors.retrieveChange', - 'client.monitors.run', - 'client.monitors.update', - 'client.batch.cancel', - 'client.batch.delete', - 'client.batch.getResults', - 'client.batch.list', - 'client.batch.retrieve', - 'client.batch.submit', - 'client.people.enrich', - 'client.news.search', - ], - { threshold: 1, shouldSort: true }, -); - -function getMethodSuggestions(fullyQualifiedMethodName: string): string[] { - return fuse - .search(fullyQualifiedMethodName) - .map(({ item }) => item) - .slice(0, 5); -} - -const proxyToObj = new WeakMap(); -const objToProxy = new WeakMap(); - -type ClientProxyConfig = { - path: string[]; - isBelievedBad?: boolean; -}; - -function makeSdkProxy(obj: T, { path, isBelievedBad = false }: ClientProxyConfig): T { - let proxy: T = objToProxy.get(obj); - - if (!proxy) { - proxy = new Proxy(obj, { - get(target, prop, receiver) { - const propPath = [...path, String(prop)]; - const value = Reflect.get(target, prop, receiver); - - if (isBelievedBad || (!(prop in target) && value === undefined)) { - // If we're accessing a path that doesn't exist, it will probably eventually error. - // Let's proxy it and mark it bad so that we can control the error message. - // We proxy an empty class so that an invocation or construction attempt is possible. - return makeSdkProxy(class {}, { path: propPath, isBelievedBad: true }); - } - - if (value !== null && (typeof value === 'object' || typeof value === 'function')) { - return makeSdkProxy(value, { path: propPath, isBelievedBad }); - } - - return value; - }, - - apply(target, thisArg, args) { - if (isBelievedBad || typeof target !== 'function') { - const fullyQualifiedMethodName = path.join('.'); - const suggestions = getMethodSuggestions(fullyQualifiedMethodName); - throw new Error( - `${fullyQualifiedMethodName} is not a function. Did you mean: ${suggestions.join(', ')}`, - ); - } - - return Reflect.apply(target, proxyToObj.get(thisArg) ?? thisArg, args); - }, - - construct(target, args, newTarget) { - if (isBelievedBad || typeof target !== 'function') { - const fullyQualifiedMethodName = path.join('.'); - const suggestions = getMethodSuggestions(fullyQualifiedMethodName); - throw new Error( - `${fullyQualifiedMethodName} is not a constructor. Did you mean: ${suggestions.join(', ')}`, - ); - } - - return Reflect.construct(target, args, newTarget); - }, - }); - - objToProxy.set(obj, proxy); - proxyToObj.set(proxy, obj); - } - - return proxy; -} - -function parseError(code: string, error: unknown): string | undefined { - if (!(error instanceof Error)) return; - const cause = error.cause instanceof Error ? `: ${error.cause.message}` : ''; - const message = error.name ? `${error.name}: ${error.message}${cause}` : `${error.message}${cause}`; - try { - // Deno uses V8; the first ":LINE:COLUMN" is the top of stack. - const lineNumber = error.stack?.match(/:([0-9]+):[0-9]+/)?.[1]; - // -1 for the zero-based indexing - const line = - lineNumber && - code - .split('\n') - .at(parseInt(lineNumber, 10) - 1) - ?.trim(); - return line ? `${message}\n at line ${lineNumber}\n ${line}` : message; - } catch { - return message; - } -} - -const fetch = async (req: Request): Promise => { - const { opts, code } = (await req.json()) as { opts: ClientOptions; code: string }; - - const runFunctionSource = code ? getRunFunctionSource(code) : null; - if (!runFunctionSource) { - const message = - code ? - 'The code is missing a top-level `run` function.' - : 'The code argument is missing. Provide one containing a top-level `run` function.'; - return Response.json( - { - is_error: true, - result: `${message} Write code within this template:\n\n\`\`\`\nasync function run(client) {\n // Fill this out\n}\n\`\`\``, - log_lines: [], - err_lines: [], - } satisfies WorkerOutput, - { status: 400, statusText: 'Code execution error' }, - ); - } - - const diagnostics = getTSDiagnostics(code); - if (diagnostics.length > 0) { - return Response.json( - { - is_error: true, - result: `The code contains TypeScript diagnostics:\n${diagnostics.join('\n')}`, - log_lines: [], - err_lines: [], - } satisfies WorkerOutput, - { status: 400, statusText: 'Code execution error' }, - ); - } - - const client = new ContextDev({ - ...opts, - }); - - const log_lines: string[] = []; - const err_lines: string[] = []; - const originalConsole = globalThis.console; - globalThis.console = { - ...originalConsole, - log: (...args: unknown[]) => { - log_lines.push(util.format(...args)); - }, - error: (...args: unknown[]) => { - err_lines.push(util.format(...args)); - }, - }; - try { - let run_ = async (client: any) => {}; - run_ = (await tseval(`${code}\nexport default run;`)).default; - const result = await run_(makeSdkProxy(client, { path: ['client'] })); - return Response.json({ - is_error: false, - result, - log_lines, - err_lines, - } satisfies WorkerOutput); - } catch (e) { - return Response.json( - { - is_error: true, - result: parseError(code, e), - log_lines, - err_lines, - } satisfies WorkerOutput, - { status: 400, statusText: 'Code execution error' }, - ); - } finally { - globalThis.console = originalConsole; - } -}; - -export default { fetch }; diff --git a/packages/mcp-server/src/code-tool.ts b/packages/mcp-server/src/code-tool.ts deleted file mode 100644 index d5cd7d59..00000000 --- a/packages/mcp-server/src/code-tool.ts +++ /dev/null @@ -1,315 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { ContentBlock, McpRequestContext, McpTool, Metadata, ToolCallResult, asErrorResult } from './types'; -import { Tool } from '@modelcontextprotocol/sdk/types.js'; -import { WorkerOutput } from './code-tool-types'; -import { getLogger } from './logger'; -import { SdkMethod } from './methods'; -import { McpCodeExecutionMode } from './options'; -import { ClientOptions } from 'context.dev'; - -const prompt = `Runs JavaScript code to interact with the Context Dev API. - -You are a skilled TypeScript programmer writing code to interface with the service. -Define an async function named "run" that takes a single parameter of an initialized SDK client and it will be run. -For example: - -\`\`\` -async function run(client) { - const brand = await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }); - - console.log(brand.cache_metadata); -} -\`\`\` - -You will be returned anything that your function returns, plus the results of any console.log statements. -Do not add try-catch blocks for single API calls. The tool will handle errors for you. -Do not add comments unless necessary for generating better code. -Code will run in a container, and cannot interact with the network outside of the given SDK client. -Variables will not persist between calls, so make sure to return or log any data you might need later. -Remember that you are writing TypeScript code, so you need to be careful with your types. -Always type dynamic key-value stores explicitly as Record instead of {}.`; - -/** - * A tool that runs code against a copy of the SDK. - * - * Instead of exposing every endpoint as its own tool, which uses up too many tokens for LLMs to use at once, - * we expose a single tool that can be used to search for endpoints by name, resource, operation, or tag, and then - * a generic endpoint that can be used to invoke any endpoint with the provided arguments. - * - * @param blockedMethods - The methods to block for code execution. Blocking is done by simple string - * matching, so it is not secure against obfuscation. For stronger security, block in the downstream API - * with limited API keys. - * @param codeExecutionMode - Whether to execute code in a local Deno environment or in a remote - * sandbox environment hosted by Stainless. - */ -export function codeTool({ - blockedMethods, - codeExecutionMode, -}: { - blockedMethods: SdkMethod[] | undefined; - codeExecutionMode: McpCodeExecutionMode; -}): McpTool { - const metadata: Metadata = { resource: 'all', operation: 'write', tags: [] }; - const tool: Tool = { - name: 'execute', - description: prompt, - inputSchema: { - type: 'object', - properties: { - code: { - type: 'string', - description: 'Code to execute.', - }, - intent: { - type: 'string', - description: 'Task you are trying to perform. Used for improving the service.', - }, - }, - required: ['code'], - }, - }; - - const logger = getLogger(); - - const handler = async ({ - reqContext, - args, - }: { - reqContext: McpRequestContext; - args: any; - }): Promise => { - const code = args.code as string; - // Do very basic blocking of code that includes forbidden method names. - // - // WARNING: This is not secure against obfuscation and other evasion methods. If - // stronger security blocks are required, then these should be enforced in the downstream - // API (e.g., by having users call the MCP server with API keys with limited permissions). - if (blockedMethods) { - const blockedMatches = blockedMethods.filter((method) => code.includes(method.fullyQualifiedName)); - if (blockedMatches.length > 0) { - return asErrorResult( - `The following methods have been blocked by the MCP server and cannot be used in code execution: ${blockedMatches - .map((m) => m.fullyQualifiedName) - .join(', ')}`, - ); - } - } - - let result: ToolCallResult; - const startTime = Date.now(); - - logger.debug('Executing code in local Deno environment'); - result = await localDenoHandler({ reqContext, args }); - - logger.info( - { - codeExecutionMode, - durationMs: Date.now() - startTime, - isError: result.isError, - contentRows: result.content?.length ?? 0, - }, - 'Got code tool execution result', - ); - return result; - }; - - return { metadata, tool, handler }; -} - -const localDenoHandler = async ({ - reqContext, - args, -}: { - reqContext: McpRequestContext; - args: unknown; -}): Promise => { - const fs = await import('node:fs'); - const path = await import('node:path'); - const url = await import('node:url'); - const { newDenoHTTPWorker } = await import('@valtown/deno-http-worker'); - const { getWorkerPath } = await import('./code-tool-paths.cjs'); - const workerPath = getWorkerPath(); - - const client = reqContext.client; - const baseURLHostname = new URL(client.baseURL).hostname; - const { code } = args as { code: string }; - - let denoPath: string; - - const packageRoot = path.resolve(path.dirname(workerPath), '..'); - const packageNodeModulesPath = path.resolve(packageRoot, 'node_modules'); - - // Check if deno is in PATH - const { execSync } = await import('node:child_process'); - try { - execSync('command -v deno', { stdio: 'ignore' }); - denoPath = 'deno'; - } catch { - try { - // Use deno binary in node_modules if it's found - const denoNodeModulesPath = path.resolve(packageNodeModulesPath, 'deno', 'bin.cjs'); - await fs.promises.access(denoNodeModulesPath, fs.constants.X_OK); - denoPath = denoNodeModulesPath; - } catch { - return asErrorResult( - 'Deno is required for code execution but was not found. ' + - 'Install it from https://deno.land or run: npm install deno', - ); - } - } - - const allowReadPaths = [ - 'code-tool-worker.mjs', - `${workerPath.replace(/([\/\\]node_modules)[\/\\].+$/, '$1')}/`, - packageRoot, - ]; - - // Follow symlinks in node_modules to allow read access to workspace-linked packages - try { - const sdkPkgName = 'context.dev'; - const sdkDir = path.resolve(packageNodeModulesPath, sdkPkgName); - const realSdkDir = fs.realpathSync(sdkDir); - if (realSdkDir !== sdkDir) { - allowReadPaths.push(realSdkDir); - } - } catch { - // Ignore if symlink resolution fails - } - - const allowRead = allowReadPaths.join(','); - - const worker = await newDenoHTTPWorker(url.pathToFileURL(workerPath), { - denoExecutable: denoPath, - runFlags: [ - `--node-modules-dir=manual`, - `--allow-read=${allowRead}`, - `--allow-net=${baseURLHostname}`, - // Allow environment variables because instantiating the client will try to read from them, - // even though they are not set. - '--allow-env', - ], - printOutput: true, - spawnOptions: { - cwd: path.dirname(workerPath), - // Merge any upstream client envs into the Deno subprocess environment, - // with the upstream env vars taking precedence. - env: { ...process.env, ...reqContext.upstreamClientEnvs }, - }, - }); - - try { - const resp = await new Promise((resolve, reject) => { - worker.addEventListener('exit', (exitCode) => { - reject(new Error(`Worker exited with code ${exitCode}`)); - }); - - // Strip null/undefined values so that the worker SDK client can fall back to - // reading from environment variables (including any upstreamClientEnvs). - const opts = { - ...(client.baseURL != null ? { baseURL: client.baseURL } : undefined), - ...(client.apiKey != null ? { apiKey: client.apiKey } : undefined), - defaultHeaders: { - 'X-Stainless-MCP': 'true', - }, - } satisfies Partial as ClientOptions; - - const req = worker.request( - 'http://localhost', - { - headers: { - 'content-type': 'application/json', - }, - method: 'POST', - }, - (resp) => { - const body: Uint8Array[] = []; - resp.on('error', (err) => { - reject(err); - }); - resp.on('data', (chunk) => { - body.push(chunk); - }); - resp.on('end', () => { - resolve( - new Response(Buffer.concat(body).toString(), { - status: resp.statusCode ?? 200, - headers: resp.headers as any, - }), - ); - }); - }, - ); - - const body = JSON.stringify({ - opts, - code, - }); - - req.write(body, (err) => { - if (err != null) { - reject(err); - } - }); - - req.end(); - }); - - if (resp.status === 200) { - const { result, log_lines, err_lines } = (await resp.json()) as WorkerOutput; - const returnOutput: ContentBlock | null = - result == null ? null : ( - { - type: 'text', - text: typeof result === 'string' ? result : JSON.stringify(result), - } - ); - const logOutput: ContentBlock | null = - log_lines.length === 0 ? - null - : { - type: 'text', - text: log_lines.join('\n'), - }; - const errOutput: ContentBlock | null = - err_lines.length === 0 ? - null - : { - type: 'text', - text: 'Error output:\n' + err_lines.join('\n'), - }; - return { - content: [returnOutput, logOutput, errOutput].filter((block) => block !== null), - }; - } else { - const { result, log_lines, err_lines } = (await resp.json()) as WorkerOutput; - const messageOutput: ContentBlock | null = - result == null ? null : ( - { - type: 'text', - text: typeof result === 'string' ? result : JSON.stringify(result), - } - ); - const logOutput: ContentBlock | null = - log_lines.length === 0 ? - null - : { - type: 'text', - text: log_lines.join('\n'), - }; - const errOutput: ContentBlock | null = - err_lines.length === 0 ? - null - : { - type: 'text', - text: 'Error output:\n' + err_lines.join('\n'), - }; - return { - content: [messageOutput, logOutput, errOutput].filter((block) => block !== null), - isError: true, - }; - } - } finally { - worker.terminate(); - } -}; diff --git a/packages/mcp-server/src/docs-search-tool.ts b/packages/mcp-server/src/docs-search-tool.ts deleted file mode 100644 index eafcd871..00000000 --- a/packages/mcp-server/src/docs-search-tool.ts +++ /dev/null @@ -1,79 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { Tool } from '@modelcontextprotocol/sdk/types.js'; -import { Metadata, McpRequestContext, asTextContentResult } from './types'; - -import type { LocalDocsSearch } from './local-docs-search'; - -export const metadata: Metadata = { - resource: 'all', - operation: 'read', - tags: [], - httpMethod: 'get', -}; - -export const tool: Tool = { - name: 'search_docs', - description: - 'Search SDK documentation to find methods, parameters, and usage examples for interacting with the API. Use this before writing code when you need to discover the right approach.', - inputSchema: { - type: 'object', - properties: { - query: { - type: 'string', - description: 'The query to search for.', - }, - language: { - type: 'string', - description: 'The language for the SDK to search for.', - enum: ['http', 'python', 'go', 'typescript', 'javascript', 'terraform', 'ruby', 'java', 'kotlin'], - }, - detail: { - type: 'string', - description: 'The amount of detail to return.', - enum: ['default', 'verbose'], - }, - }, - required: ['query', 'language'], - }, - annotations: { - readOnlyHint: true, - }, -}; - -let _localSearch: LocalDocsSearch | undefined; - -export function setLocalSearch(search: LocalDocsSearch): void { - _localSearch = search; -} - -async function searchLocal(args: Record): Promise { - if (!_localSearch) { - throw new Error('Local search not initialized'); - } - - const query = (args['query'] as string) ?? ''; - const language = (args['language'] as string) ?? 'typescript'; - const detail = (args['detail'] as string) ?? 'default'; - - return _localSearch.search({ - query, - language, - detail, - maxResults: 10, - }).results; -} - -export const handler = async ({ - reqContext, - args, -}: { - reqContext: McpRequestContext; - args: Record | undefined; -}) => { - const body = args ?? {}; - - return asTextContentResult(await searchLocal(body)); -}; - -export default { metadata, tool, handler }; diff --git a/packages/mcp-server/src/http.ts b/packages/mcp-server/src/http.ts deleted file mode 100644 index a8dfd8a9..00000000 --- a/packages/mcp-server/src/http.ts +++ /dev/null @@ -1,227 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp'; -import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; -import { ClientOptions } from 'context.dev'; -import express from 'express'; -import pino from 'pino'; -import pinoHttp from 'pino-http'; -import { getStainlessApiKey, parseClientAuthHeaders } from './auth'; -import { getLogger } from './logger'; -import { McpOptions } from './options'; -import { initMcpServer, newMcpServer } from './server'; - -const newServer = async ({ - clientOptions, - mcpOptions, - req, - res, -}: { - clientOptions: ClientOptions; - mcpOptions: McpOptions; - req: express.Request; - res: express.Response; -}): Promise => { - const stainlessApiKey = getStainlessApiKey(req, mcpOptions); - const customInstructionsPath = mcpOptions.customInstructionsPath; - const server = await newMcpServer({ stainlessApiKey, customInstructionsPath }); - - const authOptions = parseClientAuthHeaders(req, false); - - let upstreamClientEnvs: Record | undefined; - const clientEnvsHeader = req.headers['x-stainless-mcp-client-envs']; - if (typeof clientEnvsHeader === 'string') { - try { - const parsed = JSON.parse(clientEnvsHeader); - if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) { - upstreamClientEnvs = parsed; - } - } catch { - // Ignore malformed header - } - } - - // Parse x-stainless-mcp-client-permissions header to override permission options - // - // Note: Permissions are best-effort and intended to prevent clients from doing unexpected things; - // they're not a hard security boundary, so we allow arbitrary, client-driven overrides. - // - // See the Stainless MCP documentation for more details. - let effectiveMcpOptions = mcpOptions; - const clientPermissionsHeader = req.headers['x-stainless-mcp-client-permissions']; - if (typeof clientPermissionsHeader === 'string') { - try { - const parsed = JSON.parse(clientPermissionsHeader); - if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) { - effectiveMcpOptions = { - ...mcpOptions, - ...(typeof parsed.allow_http_gets === 'boolean' && { codeAllowHttpGets: parsed.allow_http_gets }), - ...(Array.isArray(parsed.allowed_methods) && { codeAllowedMethods: parsed.allowed_methods }), - ...(Array.isArray(parsed.blocked_methods) && { codeBlockedMethods: parsed.blocked_methods }), - }; - getLogger().info( - { clientPermissions: parsed }, - 'Overriding code execution permissions from x-stainless-mcp-client-permissions header', - ); - } - } catch (error) { - getLogger().warn({ error }, 'Failed to parse x-stainless-mcp-client-permissions header'); - } - } - - const mcpClientInfo = - typeof req.body?.params?.clientInfo?.name === 'string' ? - { name: req.body.params.clientInfo.name, version: String(req.body.params.clientInfo.version ?? '') } - : undefined; - - await initMcpServer({ - server: server, - mcpOptions: effectiveMcpOptions, - clientOptions: { - ...clientOptions, - ...authOptions, - }, - stainlessApiKey: stainlessApiKey, - upstreamClientEnvs, - mcpSessionId: (req as any).mcpSessionId, - mcpClientInfo, - }); - - if (mcpClientInfo) { - getLogger().info({ mcpSessionId: (req as any).mcpSessionId, mcpClientInfo }, 'MCP client connected'); - } - - return server; -}; - -const post = - (options: { clientOptions: ClientOptions; mcpOptions: McpOptions }) => - async (req: express.Request, res: express.Response) => { - const server = await newServer({ ...options, req, res }); - // If we return null, we already set the authorization error. - if (server === null) return; - const transport = new StreamableHTTPServerTransport(); - await server.connect(transport as any); - await transport.handleRequest(req, res, req.body); - }; - -const get = async (req: express.Request, res: express.Response) => { - res.status(405).json({ - jsonrpc: '2.0', - error: { - code: -32000, - message: 'Method not supported', - }, - }); -}; - -const del = async (req: express.Request, res: express.Response) => { - res.status(405).json({ - jsonrpc: '2.0', - error: { - code: -32000, - message: 'Method not supported', - }, - }); -}; - -const redactHeaders = (headers: Record) => { - const hiddenHeaders = /auth|cookie|key|token|x-stainless-mcp-client-envs/i; - const filtered = { ...headers }; - Object.keys(filtered).forEach((key) => { - if (hiddenHeaders.test(key)) { - filtered[key] = '[REDACTED]'; - } - }); - return filtered; -}; - -export const streamableHTTPApp = ({ - clientOptions = {}, - mcpOptions, -}: { - clientOptions?: ClientOptions; - mcpOptions: McpOptions; -}): express.Express => { - const app = express(); - app.set('query parser', 'extended'); - app.use(express.json()); - app.use((req: express.Request, res: express.Response, next: express.NextFunction) => { - const existing = req.headers['mcp-session-id']; - const sessionId = (Array.isArray(existing) ? existing[0] : existing) || crypto.randomUUID(); - (req as any).mcpSessionId = sessionId; - const origWriteHead = res.writeHead.bind(res); - res.writeHead = function (statusCode: number, ...rest: any[]) { - res.setHeader('mcp-session-id', sessionId); - return origWriteHead(statusCode, ...rest); - } as typeof res.writeHead; - next(); - }); - app.use( - pinoHttp({ - logger: getLogger(), - customProps: (req) => ({ - mcpSessionId: (req as any).mcpSessionId, - }), - customLogLevel: (req, res) => { - if (res.statusCode >= 500) { - return 'error'; - } else if (res.statusCode >= 400) { - return 'warn'; - } - return 'info'; - }, - customSuccessMessage: function (req, res) { - return `Request ${req.method} to ${req.url} completed with status ${res.statusCode}`; - }, - customErrorMessage: function (req, res, err) { - return `Request ${req.method} to ${req.url} errored with status ${res.statusCode}`; - }, - serializers: { - req: pino.stdSerializers.wrapRequestSerializer((req) => { - return { - ...req, - headers: redactHeaders(req.raw.headers), - }; - }), - res: pino.stdSerializers.wrapResponseSerializer((res) => { - return { - ...res, - headers: redactHeaders(res.headers), - }; - }), - }, - }), - ); - - app.get('/health', async (req: express.Request, res: express.Response) => { - res.status(200).send('OK'); - }); - app.get('/', get); - app.post('/', post({ clientOptions, mcpOptions })); - app.delete('/', del); - - return app; -}; - -export const launchStreamableHTTPServer = async ({ - mcpOptions, - port, -}: { - mcpOptions: McpOptions; - port: number | string | undefined; -}) => { - const app = streamableHTTPApp({ mcpOptions }); - const server = app.listen(port); - const address = server.address(); - - const logger = getLogger(); - - if (typeof address === 'string') { - logger.info(`MCP Server running on streamable HTTP at ${address}`); - } else if (address !== null) { - logger.info(`MCP Server running on streamable HTTP on port ${address.port}`); - } else { - logger.info(`MCP Server running on streamable HTTP on port ${port}`); - } -}; diff --git a/packages/mcp-server/src/index.ts b/packages/mcp-server/src/index.ts deleted file mode 100644 index 5bca4a60..00000000 --- a/packages/mcp-server/src/index.ts +++ /dev/null @@ -1,67 +0,0 @@ -#!/usr/bin/env node - -import { selectTools } from './server'; -import { McpOptions, parseCLIOptions } from './options'; -import { launchStdioServer } from './stdio'; -import { launchStreamableHTTPServer } from './http'; -import type { McpTool } from './types'; -import { configureLogger, getLogger } from './logger'; - -async function main() { - const options = parseOptionsOrError(); - configureLogger({ - level: options.debug ? 'debug' : 'info', - pretty: options.logFormat === 'pretty', - }); - - const selectedTools = await selectToolsOrError(options); - - getLogger().info( - { tools: selectedTools.map((e) => e.tool.name) }, - `MCP Server starting with ${selectedTools.length} tools`, - ); - - switch (options.transport) { - case 'stdio': - await launchStdioServer(options); - break; - case 'http': - await launchStreamableHTTPServer({ - mcpOptions: options, - port: options.socket ?? options.port, - }); - break; - } -} - -if (require.main === module) { - main().catch((error) => { - // Logger might not be initialized yet - console.error('Fatal error in main()', error); - process.exit(1); - }); -} - -function parseOptionsOrError() { - try { - return parseCLIOptions(); - } catch (error) { - // Logger is initialized after options, so use console.error here - console.error('Error parsing options', error); - process.exit(1); - } -} - -async function selectToolsOrError(options: McpOptions): Promise { - try { - const includedTools = selectTools(options); - if (includedTools.length === 0) { - getLogger().error('No tools match the provided filters'); - process.exit(1); - } - return includedTools; - } catch (error) { - getLogger().error({ error }, 'Error filtering tools'); - process.exit(1); - } -} diff --git a/packages/mcp-server/src/instructions.ts b/packages/mcp-server/src/instructions.ts deleted file mode 100644 index f3d6fdd8..00000000 --- a/packages/mcp-server/src/instructions.ts +++ /dev/null @@ -1,57 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import fs from 'fs/promises'; -import { getLogger } from './logger'; - -const INSTRUCTIONS_CACHE_TTL_MS = 15 * 60 * 1000; // 15 minutes - -interface InstructionsCacheEntry { - fetchedInstructions: string; - fetchedAt: number; -} - -const instructionsCache = new Map(); - -export async function getInstructions({ - stainlessApiKey, - customInstructionsPath, -}: { - stainlessApiKey?: string | undefined; - customInstructionsPath?: string | undefined; -}): Promise { - const now = Date.now(); - const cacheKey = customInstructionsPath ?? stainlessApiKey ?? ''; - const cached = instructionsCache.get(cacheKey); - - if (cached && now - cached.fetchedAt <= INSTRUCTIONS_CACHE_TTL_MS) { - return cached.fetchedInstructions; - } - - // Evict stale entries so the cache doesn't grow unboundedly. - for (const [key, entry] of instructionsCache) { - if (now - entry.fetchedAt > INSTRUCTIONS_CACHE_TTL_MS) { - instructionsCache.delete(key); - } - } - - let fetchedInstructions: string; - - if (customInstructionsPath) { - fetchedInstructions = await fetchLatestInstructionsFromFile(customInstructionsPath); - } else { - fetchedInstructions = - '\n This is the context.dev MCP server.\n\n Available tools:\n - search_docs: Search SDK documentation to find the right methods and parameters.\n - execute: Run TypeScript code against a pre-authenticated SDK client. Define an async run(client) function.\n\n Workflow:\n - If unsure about the API, call search_docs first.\n - Write complete solutions in a single execute call when possible. For large datasets, use API filters to narrow results or paginate within a single execute block.\n - If execute returns an error, read the error and fix your code rather than retrying the same approach.\n - Variables do not persist between execute calls. Return or log all data you need.\n - Individual HTTP requests to the API have a 30-second timeout. If a request times out, try a smaller query or add filters.\n - Code execution has a total timeout of approximately 5 minutes. If your code times out, simplify it or break it into smaller steps.\n '; - } - - instructionsCache.set(cacheKey, { fetchedInstructions, fetchedAt: now }); - return fetchedInstructions; -} - -async function fetchLatestInstructionsFromFile(path: string): Promise { - try { - return await fs.readFile(path, 'utf-8'); - } catch (error) { - getLogger().error({ error, path }, 'Error fetching instructions from file'); - throw error; - } -} diff --git a/packages/mcp-server/src/local-docs-search.ts b/packages/mcp-server/src/local-docs-search.ts deleted file mode 100644 index 8709272a..00000000 --- a/packages/mcp-server/src/local-docs-search.ts +++ /dev/null @@ -1,2661 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import MiniSearch from 'minisearch'; -import * as fs from 'node:fs/promises'; -import * as path from 'node:path'; -import { getLogger } from './logger'; - -type PerLanguageData = { - method?: string; - example?: string; -}; - -type MethodEntry = { - name: string; - endpoint: string; - httpMethod: string; - summary: string; - description: string; - stainlessPath: string; - qualified: string; - params?: string[]; - response?: string; - markdown?: string; - perLanguage?: Record; -}; - -type ProseChunk = { - content: string; - tag: string; - sectionContext?: string; - source?: string; -}; - -type MiniSearchDocument = { - id: string; - kind: 'http_method' | 'prose'; - name?: string; - endpoint?: string; - summary?: string; - description?: string; - qualified?: string; - stainlessPath?: string; - content?: string; - sectionContext?: string; - _original: Record; -}; - -type SearchResult = { - results: (string | Record)[]; -}; - -const EMBEDDED_METHODS: MethodEntry[] = [ - { - name: 'handle', - endpoint: '/parse', - httpMethod: 'post', - summary: 'Parse Bytes', - description: - 'Converts raw text, source code, web/data, PDF, Microsoft Office, and image bytes into LLM-usable Markdown.', - stainlessPath: '(resource) parse > (method) handle', - qualified: 'client.parse.handle', - params: [ - 'body: string;', - 'client?: string;', - 'extension?: string;', - 'includeImages?: boolean;', - 'includeLinks?: boolean;', - 'ocr?: boolean;', - 'pdf?: { end?: number; start?: number; };', - 'shortenBase64Images?: boolean;', - 'tags?: string[];', - 'useMainContentOnly?: boolean;', - "zdr?: 'enabled' | 'disabled';", - ], - response: - '{ markdown: string; success: true; type: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }', - markdown: - "## handle\n\n`client.parse.handle(body: string, client?: string, extension?: string, includeImages?: boolean, includeLinks?: boolean, ocr?: boolean, pdf?: { end?: number; start?: number; }, shortenBase64Images?: boolean, tags?: string[], useMainContentOnly?: boolean, zdr?: 'enabled' | 'disabled'): { markdown: string; success: true; type: string; key_metadata?: object; }`\n\n**post** `/parse`\n\nConverts raw text, source code, web/data, PDF, Microsoft Office, and image bytes into LLM-usable Markdown.\n\n### Parameters\n\n- `body: string`\n\n- `client?: string`\n Optional client identifier used for usage attribution.\n\n- `extension?: string`\n Optional file extension hint, such as pdf, docx, xlsx, pptx, html, json, csv, md, py, rtf, jpg, png, or txt.\n\n- `includeImages?: boolean`\n Include image references in Markdown output\n\n- `includeLinks?: boolean`\n Preserve hyperlinks in Markdown output\n\n- `ocr?: boolean`\n When true for PDF inputs, OCR the selected pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. pdf.start/pdf.end limit the inclusive page range. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs.\n\n- `pdf?: { end?: number; start?: number; }`\n PDF page-range options as a JSON object, e.g. {\"start\": 2, \"end\": 5}.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `shortenBase64Images?: boolean`\n Shorten base64-encoded image data in the Markdown output\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `useMainContentOnly?: boolean`\n Extract only the main content from HTML-like inputs\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ markdown: string; success: true; type: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `markdown: string`\n - `success: true`\n - `type: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.parse.handle(fs.createReadStream('path/to/file'));\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'parse->handle', - example: - "parse->handle(\n FileParam::fromString('Example data', filename: uniqid('file-upload-', true))\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Parse.Handle', - example: - 'package main\n\nimport (\n\t"bytes"\n\t"context"\n\t"fmt"\n\t"io"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Parse.Handle(\n\t\tcontext.TODO(),\n\t\tio.Reader(bytes.NewBuffer([]byte("Example data"))),\n\t\tcontextdev.ParseHandleParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Markdown)\n}\n', - }, - cli: { - method: 'parse handle', - example: "context-dev parse handle \\\n --api-key 'My API Key' \\\n --body 'Example data'", - }, - python: { - method: 'parse.handle', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.parse.handle(\n body=b"Example data",\n)\nprint(response.markdown)', - }, - ruby: { - method: 'parse.handle', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.parse.handle(body: StringIO.new("Example data"))\n\nputs(response)', - }, - typescript: { - method: 'client.parse.handle', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.parse.handle(fs.createReadStream('path/to/file'));\n\nconsole.log(response.markdown);", - }, - http: { - example: - "curl https://api.context.dev/v1/parse \\\n -H 'Content-Type: application/octet-stream' \\\n -H \"Authorization: Bearer $CONTEXT_DEV_API_KEY\" \\\n -F 'body=@/path/to/body'", - }, - }, - }, - { - name: 'web_scrape_html', - endpoint: '/web/scrape/html', - httpMethod: 'get', - summary: 'Scrape HTML', - description: - 'Scrapes the given URL and returns the raw HTML content of the page. The base request costs 1 credit; requests with browser actions cost 2 credits.', - stainlessPath: '(resource) web > (method) web_scrape_html', - qualified: 'client.web.webScrapeHTML', - params: [ - 'url: string;', - "actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[];", - 'country?: string;', - 'excludeSelectors?: string[];', - 'headers?: object;', - 'includeFrames?: boolean;', - 'includeSelectors?: string[];', - 'maxAgeMs?: number;', - 'pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; };', - 'settleAnimations?: boolean;', - 'tags?: string[];', - 'timeoutMS?: number;', - 'useMainContentOnly?: boolean;', - 'waitForMs?: number;', - "zdr?: 'enabled' | 'disabled';", - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; html: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; type: string; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## web_scrape_html\n\n`client.web.webScrapeHTML(url: string, actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[], country?: string, excludeSelectors?: string[], headers?: object, includeFrames?: boolean, includeSelectors?: string[], maxAgeMs?: number, pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }, settleAnimations?: boolean, tags?: string[], timeoutMS?: number, useMainContentOnly?: boolean, waitForMs?: number, zdr?: 'enabled' | 'disabled'): { cache_metadata: object; html: string; metadata: object; success: true; type: string; url: string; actionsApplied?: object[]; actionsHtmlStale?: boolean; key_metadata?: object; }`\n\n**get** `/web/scrape/html`\n\nScrapes the given URL and returns the raw HTML content of the page. The base request costs 1 credit; requests with browser actions cost 2 credits.\n\n### Parameters\n\n- `url: string`\n Full URL to scrape (must include http:// or https:// protocol)\n\n- `actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[]`\n Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `excludeSelectors?: string[]`\n CSS selectors to remove from the result. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\".\n\n- `headers?: object`\n Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.\n\n- `includeFrames?: boolean`\n When true, iframes are rendered inline into the returned HTML.\n\n- `includeSelectors?: string[]`\n CSS selectors. When provided, only matching subtrees (and their descendants) are kept and everything else is dropped. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\".\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }`\n PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `ocr?: boolean`\n When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs.\n - `shouldParse?: boolean`\n When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned.\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `settleAnimations?: boolean`\n When true, waits briefly for CSS and transition animations to settle before extracting HTML. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `useMainContentOnly?: boolean`\n When true, return only the page's main content in the HTML response, excluding headers, footers, sidebars, and navigation when detectable.\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load. Min: 0. Max: 30000 (30 seconds).\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; html: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; type: string; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `html: string`\n - `metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }`\n - `success: true`\n - `type: string`\n - `url: string`\n - `actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]`\n - `actionsHtmlStale?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webScrapeHTML({ url: 'https://example.com' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->webScrapeHTML', - example: - "web->webScrapeHTML(\n url: 'https://example.com',\n actions: [['do' => 'wait', 'timeMs' => 0]],\n country: 'de',\n excludeSelectors: ['x'],\n headers: ['foo' => 'J!'],\n includeFrames: true,\n includeSelectors: ['x'],\n maxAgeMs: 0,\n pdf: ['end' => 1, 'ocr' => true, 'shouldParse' => true, 'start' => 1],\n settleAnimations: true,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1,\n useMainContentOnly: true,\n waitForMs: 0,\n zdr: 'enabled',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.WebScrapeHTML', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.WebScrapeHTML(context.TODO(), contextdev.WebWebScrapeHTMLParams{\n\t\tURL: "https://example.com",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'web web_scrape_html', - example: - "context-dev web web-scrape-html \\\n --api-key 'My API Key' \\\n --url https://example.com", - }, - python: { - method: 'web.web_scrape_html', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.web_scrape_html(\n url="https://example.com",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'web.web_scrape_html', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.web_scrape_html(url: "https://example.com")\n\nputs(response)', - }, - typescript: { - method: 'client.web.webScrapeHTML', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.webScrapeHTML({ url: 'https://example.com' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/scrape/html \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'web_scrape_md', - endpoint: '/web/scrape/markdown', - httpMethod: 'get', - summary: 'Scrape Markdown', - description: - 'Scrapes the given URL into LLM usable Markdown. Inspect key_metadata on JSON responses from a recognized API key; use error_code to distinguish stable failure categories.\n\n### YouTube\n\nYouTube URLs return the video or channel itself rather than the surrounding player and navigation chrome. A URL addressing a single video (`/watch`, `youtu.be`, `/shorts`, `/embed`, `/live`) returns its title, channel, duration, view count, keywords, full description, and the transcript when the video has captions that can be retrieved; videos without captions return everything except the transcript. A channel URL (`/channel/UC…`, `/@handle`, `/c/…`, `/user/…`) returns its name, handle, subscriber count, video count, and full description. When `includeImages=true`, video responses also include the thumbnail and channel responses include the avatar. Costs the same as any other scrape.\n\n### Billing & errors\n\n| HTTP status | Billed? | Meaning |\n| --- | --- | --- |\n| 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing |\n| 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds |\n| 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code |\n| 404 | No | Target page returned or fingerprinted as not found |\n| 408 | No | Request timed out |\n| 413 | No | Target content exceeds the maximum supported size (20 MB) |\n| 415 | No | Unsupported content type |\n| 429 | No | Per-minute rate limit exceeded; honor Retry-After |\n| 500 | No | Internal error |', - stainlessPath: '(resource) web > (method) web_scrape_md', - qualified: 'client.web.webScrapeMd', - params: [ - 'url: string;', - "actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[];", - 'country?: string;', - 'excludeSelectors?: string[];', - 'headers?: object;', - 'includeFrames?: boolean;', - 'includeHTML?: boolean;', - 'includeImages?: boolean;', - 'includeLinks?: boolean;', - 'includeSelectors?: string[];', - 'maxAgeMs?: number;', - 'pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; };', - 'settleAnimations?: boolean;', - 'shortenBase64Images?: boolean;', - 'tags?: string[];', - 'timeoutMS?: number;', - 'useMainContentOnly?: boolean;', - 'waitForMs?: number;', - "zdr?: 'enabled' | 'disabled';", - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; contentLength: number; markdown: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; html?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## web_scrape_md\n\n`client.web.webScrapeMd(url: string, actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[], country?: string, excludeSelectors?: string[], headers?: object, includeFrames?: boolean, includeHTML?: boolean, includeImages?: boolean, includeLinks?: boolean, includeSelectors?: string[], maxAgeMs?: number, pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }, settleAnimations?: boolean, shortenBase64Images?: boolean, tags?: string[], timeoutMS?: number, useMainContentOnly?: boolean, waitForMs?: number, zdr?: 'enabled' | 'disabled'): { cache_metadata: object; contentLength: number; markdown: string; metadata: object; success: true; url: string; actionsApplied?: object[]; actionsHtmlStale?: boolean; html?: string; key_metadata?: object; }`\n\n**get** `/web/scrape/markdown`\n\nScrapes the given URL into LLM usable Markdown. Inspect key_metadata on JSON responses from a recognized API key; use error_code to distinguish stable failure categories.\n\n### YouTube\n\nYouTube URLs return the video or channel itself rather than the surrounding player and navigation chrome. A URL addressing a single video (`/watch`, `youtu.be`, `/shorts`, `/embed`, `/live`) returns its title, channel, duration, view count, keywords, full description, and the transcript when the video has captions that can be retrieved; videos without captions return everything except the transcript. A channel URL (`/channel/UC…`, `/@handle`, `/c/…`, `/user/…`) returns its name, handle, subscriber count, video count, and full description. When `includeImages=true`, video responses also include the thumbnail and channel responses include the avatar. Costs the same as any other scrape.\n\n### Billing & errors\n\n| HTTP status | Billed? | Meaning |\n| --- | --- | --- |\n| 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing |\n| 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds |\n| 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code |\n| 404 | No | Target page returned or fingerprinted as not found |\n| 408 | No | Request timed out |\n| 413 | No | Target content exceeds the maximum supported size (20 MB) |\n| 415 | No | Unsupported content type |\n| 429 | No | Per-minute rate limit exceeded; honor Retry-After |\n| 500 | No | Internal error |\n\n### Parameters\n\n- `url: string`\n Full URL to scrape into LLM usable Markdown (must include http:// or https:// protocol)\n\n- `actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[]`\n Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `excludeSelectors?: string[]`\n CSS selectors to remove before conversion to Markdown. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\".\n\n- `headers?: object`\n Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.\n\n- `includeFrames?: boolean`\n When true, the contents of iframes are rendered to Markdown.\n\n- `includeHTML?: boolean`\n When true, the response also includes an `html` field with the page HTML the Markdown was converted from — the same body the Scrape HTML endpoint returns for the equivalent request.\n\n- `includeImages?: boolean`\n Include image references in Markdown output\n\n- `includeLinks?: boolean`\n Preserve hyperlinks in Markdown output\n\n- `includeSelectors?: string[]`\n CSS selectors. When provided, only matching HTML subtrees (and their descendants) are kept before conversion to Markdown. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\".\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }`\n PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `ocr?: boolean`\n When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs.\n - `shouldParse?: boolean`\n When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned.\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `settleAnimations?: boolean`\n When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `shortenBase64Images?: boolean`\n Shorten base64-encoded image data in the Markdown output\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `useMainContentOnly?: boolean`\n Extract only the main content of the page, excluding headers, footers, sidebars, and navigation\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds).\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; contentLength: number; markdown: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; html?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `contentLength: number`\n - `markdown: string`\n - `metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }`\n - `success: true`\n - `url: string`\n - `actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]`\n - `actionsHtmlStale?: boolean`\n - `html?: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webScrapeMd({ url: 'https://example.com' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->webScrapeMd', - example: - "web->webScrapeMd(\n url: 'https://example.com',\n actions: [['do' => 'wait', 'timeMs' => 0]],\n country: 'de',\n excludeSelectors: ['x'],\n headers: ['foo' => 'J!'],\n includeFrames: true,\n includeHTML: true,\n includeImages: true,\n includeLinks: true,\n includeSelectors: ['x'],\n maxAgeMs: 0,\n pdf: ['end' => 1, 'ocr' => true, 'shouldParse' => true, 'start' => 1],\n settleAnimations: true,\n shortenBase64Images: true,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1,\n useMainContentOnly: true,\n waitForMs: 0,\n zdr: 'enabled',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.WebScrapeMd', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.WebScrapeMd(context.TODO(), contextdev.WebWebScrapeMdParams{\n\t\tURL: "https://example.com",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'web web_scrape_md', - example: "context-dev web web-scrape-md \\\n --api-key 'My API Key' \\\n --url https://example.com", - }, - python: { - method: 'web.web_scrape_md', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.web_scrape_md(\n url="https://example.com",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'web.web_scrape_md', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.web_scrape_md(url: "https://example.com")\n\nputs(response)', - }, - typescript: { - method: 'client.web.webScrapeMd', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.webScrapeMd({ url: 'https://example.com' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/scrape/markdown \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'web_scrape_images', - endpoint: '/web/scrape/images', - httpMethod: 'get', - summary: 'Scrape Images', - description: - 'Extract image assets from a web page, including standard URLs, inline SVGs, data URIs, responsive image sources, metadata, CSS backgrounds, video posters, and embeds. The base request costs 1 credit, or 2 credits with browser actions. When enrichment is enabled, the entire call costs 5 credits, including requests that also use actions.', - stainlessPath: '(resource) web > (method) web_scrape_images', - qualified: 'client.web.webScrapeImages', - params: [ - 'url: string;', - "actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[];", - 'dedupe?: boolean;', - 'enrichment?: { classification?: boolean; hostedUrl?: boolean; maxTimePerMs?: number; resolution?: boolean; };', - 'headers?: object;', - 'maxAgeMs?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - 'waitForMs?: number;', - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; images: { alt: string; element: 'img' | 'svg' | 'link' | 'source' | 'video' | 'css' | 'object' | 'meta' | 'background'; src: string; type: 'url' | 'html' | 'base64'; enrichment?: { height?: number; mimetype?: string; type?: 'photography' | 'illustration' | 'logo' | 'wordmark' | 'icon' | 'pattern' | 'graphic' | 'other'; url?: string; width?: number; }; }[]; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## web_scrape_images\n\n`client.web.webScrapeImages(url: string, actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[], dedupe?: boolean, enrichment?: { classification?: boolean; hostedUrl?: boolean; maxTimePerMs?: number; resolution?: boolean; }, headers?: object, maxAgeMs?: number, tags?: string[], timeoutMS?: number, waitForMs?: number): { cache_metadata: object; images: object[]; success: true; url: string; actionsApplied?: object[]; key_metadata?: object; }`\n\n**get** `/web/scrape/images`\n\nExtract image assets from a web page, including standard URLs, inline SVGs, data URIs, responsive image sources, metadata, CSS backgrounds, video posters, and embeds. The base request costs 1 credit, or 2 credits with browser actions. When enrichment is enabled, the entire call costs 5 credits, including requests that also use actions.\n\n### Parameters\n\n- `url: string`\n Page URL to inspect. Must include http:// or https://.\n\n- `actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[]`\n Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.\n\n- `dedupe?: boolean`\n When true, visually duplicate images are removed: every image is loaded and perceptually hashed, and only the highest-resolution copy of each duplicate group is kept. Images that cannot be downloaded or hashed are kept. Default: false.\n\n- `enrichment?: { classification?: boolean; hostedUrl?: boolean; maxTimePerMs?: number; resolution?: boolean; }`\n Optional per-image processing, sent as deep-object query params such as enrichment[resolution]=true.\n - `classification?: boolean`\n Classify each image by visual asset type.\n - `hostedUrl?: boolean`\n Host materializable images on the Brand.dev CDN and return their URL and MIME type.\n - `maxTimePerMs?: number`\n Per-image enrichment timeout in milliseconds. Default: 30000. Maximum: 60000.\n - `resolution?: boolean`\n Measure image width and height when possible.\n\n- `headers?: object`\n Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.\n\n- `maxAgeMs?: number`\n Reuse a cached result this many milliseconds old or newer. Default: 86400000 (1 day). Set to 0 to bypass cache. Maximum: 2592000000 (30 days).\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load before collecting images. Min: 0. Max: 30000 (30 seconds).\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; images: { alt: string; element: 'img' | 'svg' | 'link' | 'source' | 'video' | 'css' | 'object' | 'meta' | 'background'; src: string; type: 'url' | 'html' | 'base64'; enrichment?: { height?: number; mimetype?: string; type?: 'photography' | 'illustration' | 'logo' | 'wordmark' | 'icon' | 'pattern' | 'graphic' | 'other'; url?: string; width?: number; }; }[]; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `images: { alt: string; element: 'img' | 'svg' | 'link' | 'source' | 'video' | 'css' | 'object' | 'meta' | 'background'; src: string; type: 'url' | 'html' | 'base64'; enrichment?: { height?: number; mimetype?: string; type?: 'photography' | 'illustration' | 'logo' | 'wordmark' | 'icon' | 'pattern' | 'graphic' | 'other'; url?: string; width?: number; }; }[]`\n - `success: true`\n - `url: string`\n - `actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webScrapeImages({ url: 'https://example.com' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->webScrapeImages', - example: - "web->webScrapeImages(\n url: 'https://example.com',\n actions: [['do' => 'wait', 'timeMs' => 0]],\n dedupe: true,\n enrichment: [\n 'classification' => true,\n 'hostedURL' => true,\n 'maxTimePerMs' => 1,\n 'resolution' => true,\n ],\n headers: ['foo' => 'J!'],\n maxAgeMs: 0,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1,\n waitForMs: 0,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.WebScrapeImages', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.WebScrapeImages(context.TODO(), contextdev.WebWebScrapeImagesParams{\n\t\tURL: "https://example.com",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'web web_scrape_images', - example: - "context-dev web web-scrape-images \\\n --api-key 'My API Key' \\\n --url https://example.com", - }, - python: { - method: 'web.web_scrape_images', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.web_scrape_images(\n url="https://example.com",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'web.web_scrape_images', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.web_scrape_images(url: "https://example.com")\n\nputs(response)', - }, - typescript: { - method: 'client.web.webScrapeImages', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.webScrapeImages({ url: 'https://example.com' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/scrape/images \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'web_scrape_sitemap', - endpoint: '/web/scrape/sitemap', - httpMethod: 'get', - summary: 'Crawl Sitemap', - description: - "Crawl an entire website's sitemap and return all discovered page URLs. Pass `search` to have the crawled sitemap filtered down to the pages about a phrase (for example `pricing and plans` or `api authentication docs`), most relevant first — a searched crawl scans the whole sitemap and costs 2 credits instead of 1.", - stainlessPath: '(resource) web > (method) web_scrape_sitemap', - qualified: 'client.web.webScrapeSitemap', - params: [ - 'domain: string;', - 'headers?: object;', - 'maxLinks?: number;', - 'search?: string;', - 'sitemapUrl?: string;', - 'tags?: string[];', - 'timeoutMS?: number;', - 'urlRegex?: string;', - "zdr?: 'enabled' | 'disabled';", - ], - response: - '{ domain: string; meta: { errors: number; sitemapsDiscovered: number; sitemapsFetched: number; sitemapsSkipped: number; }; success: true; urls: string[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }', - markdown: - "## web_scrape_sitemap\n\n`client.web.webScrapeSitemap(domain: string, headers?: object, maxLinks?: number, search?: string, sitemapUrl?: string, tags?: string[], timeoutMS?: number, urlRegex?: string, zdr?: 'enabled' | 'disabled'): { domain: string; meta: object; success: true; urls: string[]; key_metadata?: object; }`\n\n**get** `/web/scrape/sitemap`\n\nCrawl an entire website's sitemap and return all discovered page URLs. Pass `search` to have the crawled sitemap filtered down to the pages about a phrase (for example `pricing and plans` or `api authentication docs`), most relevant first — a searched crawl scans the whole sitemap and costs 2 credits instead of 1.\n\n### Parameters\n\n- `domain: string`\n Domain to build a sitemap for\n\n- `headers?: object`\n Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.\n\n- `maxLinks?: number`\n Maximum number of links to return from the sitemap crawl. Defaults to 10,000. Minimum is 1, maximum is 100,000.\n\n- `search?: string`\n Optional search phrase. When provided, the crawled sitemap is filtered to the pages whose URLs are about that phrase, most relevant first, and the request costs 2 credits instead of 1.\n\n- `sitemapUrl?: string`\n Optional explicit sitemap URL. When provided, exactly this sitemap is crawled instead of discovering the domain's sitemaps.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `urlRegex?: string`\n Optional RE2-compatible regex pattern. Only URLs matching this pattern are returned and counted against maxLinks.\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ domain: string; meta: { errors: number; sitemapsDiscovered: number; sitemapsFetched: number; sitemapsSkipped: number; }; success: true; urls: string[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `domain: string`\n - `meta: { errors: number; sitemapsDiscovered: number; sitemapsFetched: number; sitemapsSkipped: number; }`\n - `success: true`\n - `urls: string[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webScrapeSitemap({ domain: 'xxx' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->webScrapeSitemap', - example: - "web->webScrapeSitemap(\n domain: 'xxx',\n headers: ['foo' => 'J!'],\n maxLinks: 1,\n search: 'help center and troubleshooting articles',\n sitemapURL: 'https://example.com',\n tags: ['production', 'team-alpha'],\n timeoutMs: 1,\n urlRegex: '^https?://[^/]+/blog/',\n zdr: 'enabled',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.WebScrapeSitemap', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.WebScrapeSitemap(context.TODO(), contextdev.WebWebScrapeSitemapParams{\n\t\tDomain: "xxx",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Domain)\n}\n', - }, - cli: { - method: 'web web_scrape_sitemap', - example: "context-dev web web-scrape-sitemap \\\n --api-key 'My API Key' \\\n --domain xxx", - }, - python: { - method: 'web.web_scrape_sitemap', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.web_scrape_sitemap(\n domain="xxx",\n)\nprint(response.domain)', - }, - ruby: { - method: 'web.web_scrape_sitemap', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.web_scrape_sitemap(domain: "xxx")\n\nputs(response)', - }, - typescript: { - method: 'client.web.webScrapeSitemap', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.webScrapeSitemap({ domain: 'xxx' });\n\nconsole.log(response.domain);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/scrape/sitemap \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'screenshot', - endpoint: '/web/screenshot', - httpMethod: 'get', - summary: 'Scrape Screenshot', - description: 'Capture a screenshot of a website.', - stainlessPath: '(resource) web > (method) screenshot', - qualified: 'client.web.screenshot', - params: [ - 'clearPopups?: boolean;', - "colorScheme?: 'light' | 'dark';", - 'country?: string;', - 'directUrl?: string;', - 'domain?: string;', - "fullScreenshot?: 'true' | 'false';", - 'handleCookiePopup?: boolean;', - 'maxAgeMs?: number;', - "page?: 'login' | 'signup' | 'blog' | 'careers' | 'pricing' | 'terms' | 'privacy' | 'contact';", - 'scrollOffset?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - 'viewport?: { height?: number; width?: number; };', - 'waitForMs?: number;', - "zdr?: 'enabled' | 'disabled';", - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; code?: number; domain?: string; height?: number; key_metadata?: { credits_consumed: number; credits_remaining: number; }; screenshot?: string; screenshotType?: 'viewport' | 'fullPage'; status?: string; width?: number; }", - markdown: - "## screenshot\n\n`client.web.screenshot(clearPopups?: boolean, colorScheme?: 'light' | 'dark', country?: string, directUrl?: string, domain?: string, fullScreenshot?: 'true' | 'false', handleCookiePopup?: boolean, maxAgeMs?: number, page?: 'login' | 'signup' | 'blog' | 'careers' | 'pricing' | 'terms' | 'privacy' | 'contact', scrollOffset?: number, tags?: string[], timeoutMS?: number, viewport?: { height?: number; width?: number; }, waitForMs?: number, zdr?: 'enabled' | 'disabled'): { cache_metadata: object; code?: number; domain?: string; height?: number; key_metadata?: object; screenshot?: string; screenshotType?: 'viewport' | 'fullPage'; status?: string; width?: number; }`\n\n**get** `/web/screenshot`\n\nCapture a screenshot of a website.\n\n### Parameters\n\n- `clearPopups?: boolean`\n Optional parameter for comprehensive popup cleanup. If 'true', the browser dismisses detected cookie/consent UI and clears other detected obstructive popups and overlays before capture. If 'false' or not provided, this parameter requests no cleanup; handleCookiePopup can still request cookie/consent handling independently.\n\n- `colorScheme?: 'light' | 'dark'`\n Optional parameter to choose the site's visual theme in the screenshot. Use 'light' or 'dark' when the site offers both appearances.\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `directUrl?: string`\n A specific URL to screenshot directly, bypassing domain resolution (e.g., 'https://example.com/pricing'). When provided, the screenshot is taken of this exact URL. You must provide either 'domain' or 'directUrl', but not both.\n\n- `domain?: string`\n Domain name to take screenshot of (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both.\n\n- `fullScreenshot?: 'true' | 'false'`\n Optional parameter to determine screenshot type. If 'true', takes a full page screenshot capturing all content. If 'false' or not provided, takes a viewport screenshot (standard browser view).\n\n- `handleCookiePopup?: boolean`\n Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step.\n\n- `maxAgeMs?: number`\n Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh.\n\n- `page?: 'login' | 'signup' | 'blog' | 'careers' | 'pricing' | 'terms' | 'privacy' | 'contact'`\n Optional parameter to specify which page type to screenshot. If provided, the system will scrape the domain's links and use heuristics to find the most appropriate URL for the specified page type (30 supported languages). If not provided, screenshots the main domain landing page. Only applicable when using 'domain', not 'directUrl'.\n\n- `scrollOffset?: number`\n Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `viewport?: { height?: number; width?: number; }`\n Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080.\n - `height?: number`\n Viewport height in pixels.\n - `width?: number`\n Viewport width in pixels.\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted.\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; code?: number; domain?: string; height?: number; key_metadata?: { credits_consumed: number; credits_remaining: number; }; screenshot?: string; screenshotType?: 'viewport' | 'fullPage'; status?: string; width?: number; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `code?: number`\n - `domain?: string`\n - `height?: number`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `screenshot?: string`\n - `screenshotType?: 'viewport' | 'fullPage'`\n - `status?: string`\n - `width?: number`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.screenshot();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->screenshot', - example: - "web->screenshot(\n clearPopups: true,\n colorScheme: 'light',\n country: 'de',\n directURL: 'https://example.com',\n domain: 'xxx',\n fullScreenshot: 'true',\n handleCookiePopup: true,\n maxAgeMs: 0,\n page: 'login',\n scrollOffset: 0,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1,\n viewport: ['height' => 240, 'width' => 240],\n waitForMs: 0,\n zdr: 'enabled',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.Screenshot', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.Screenshot(context.TODO(), contextdev.WebScreenshotParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Width)\n}\n', - }, - cli: { - method: 'web screenshot', - example: "context-dev web screenshot \\\n --api-key 'My API Key'", - }, - python: { - method: 'web.screenshot', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.screenshot()\nprint(response.width)', - }, - ruby: { - method: 'web.screenshot', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.screenshot\n\nputs(response)', - }, - typescript: { - method: 'client.web.screenshot', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.screenshot();\n\nconsole.log(response.width);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/screenshot \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'web_crawl_md', - endpoint: '/web/crawl', - httpMethod: 'post', - summary: 'Crawl Website & Scrape Markdown', - description: - 'Performs a crawl starting from a given URL, extracts page content as Markdown, and returns results for all crawled pages.', - stainlessPath: '(resource) web > (method) web_crawl_md', - qualified: 'client.web.webCrawlMd', - params: [ - 'url: string;', - 'country?: string;', - 'excludeSelectors?: string[];', - 'followSubdomains?: boolean;', - 'includeFrames?: boolean;', - 'includeImages?: boolean;', - 'includeLinks?: boolean;', - 'includeSelectors?: string[];', - 'maxAgeMs?: number;', - 'maxDepth?: number;', - 'maxPages?: number;', - 'pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; };', - 'settleAnimations?: boolean;', - 'shortenBase64Images?: boolean;', - 'stopAfterMs?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - 'urlRegex?: string;', - 'useMainContentOnly?: boolean;', - 'waitForMs?: number;', - "zdr?: 'enabled' | 'disabled';", - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; metadata: { maxCrawlDepth: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; }; results: { markdown: string; metadata: { crawlDepth: number; finalUrl: string; sourceUrl: string; statusCode: number; success: boolean; title: string; url: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: object[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; twitter?: object; }; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## web_crawl_md\n\n`client.web.webCrawlMd(url: string, country?: string, excludeSelectors?: string[], followSubdomains?: boolean, includeFrames?: boolean, includeImages?: boolean, includeLinks?: boolean, includeSelectors?: string[], maxAgeMs?: number, maxDepth?: number, maxPages?: number, pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }, settleAnimations?: boolean, shortenBase64Images?: boolean, stopAfterMs?: number, tags?: string[], timeoutMS?: number, urlRegex?: string, useMainContentOnly?: boolean, waitForMs?: number, zdr?: 'enabled' | 'disabled'): { cache_metadata: object; metadata: object; results: object[]; key_metadata?: object; }`\n\n**post** `/web/crawl`\n\nPerforms a crawl starting from a given URL, extracts page content as Markdown, and returns results for all crawled pages.\n\n### Parameters\n\n- `url: string`\n The starting URL for the crawl (must include http:// or https:// protocol)\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `excludeSelectors?: string[]`\n CSS selectors to remove before each crawled page is converted to Markdown. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\".\n\n- `followSubdomains?: boolean`\n When true, follow links on subdomains of the starting URL's domain (e.g. docs.example.com when starting from example.com). www and apex are always treated as equivalent.\n\n- `includeFrames?: boolean`\n When true, the contents of iframes are rendered to Markdown for each crawled page.\n\n- `includeImages?: boolean`\n Include image references in the Markdown output\n\n- `includeLinks?: boolean`\n Preserve hyperlinks in the Markdown output\n\n- `includeSelectors?: string[]`\n CSS selectors. When provided, only matching HTML subtrees (and their descendants) are kept before each crawled page is converted to Markdown. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\".\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `maxDepth?: number`\n Maximum link depth from the starting URL (0 = only the starting page)\n\n- `maxPages?: number`\n Maximum number of pages to crawl. Hard cap: 500.\n\n- `pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }`\n PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `ocr?: boolean`\n When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost.\n - `shouldParse?: boolean`\n When true, PDF pages are fetched and parsed. When false, PDF pages are skipped entirely (not included in results and not counted as failures).\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `settleAnimations?: boolean`\n When true, waits briefly for CSS and transition animations to settle before extracting each crawled page. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `shortenBase64Images?: boolean`\n Truncate base64-encoded image data in the Markdown output\n\n- `stopAfterMs?: number`\n Soft time budget for the crawl in milliseconds. After each scrape, the crawler checks the elapsed time and, if exceeded, returns the pages collected so far instead of continuing. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 (80s).\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `urlRegex?: string`\n Regex pattern. Only URLs matching this pattern will be followed and scraped. An automatic prefix scope in the form ^ follows a redirect of the starting page.\n\n- `useMainContentOnly?: boolean`\n Extract only the main content, stripping headers, footers, sidebars, and navigation\n\n- `waitForMs?: number`\n Browser wait time in milliseconds after initial page load for each crawled page. Defaults to 3500 (3.5 seconds). Min: 0. Max: 30000 (30 seconds).\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; metadata: { maxCrawlDepth: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; }; results: { markdown: string; metadata: { crawlDepth: number; finalUrl: string; sourceUrl: string; statusCode: number; success: boolean; title: string; url: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: object[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; twitter?: object; }; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `metadata: { maxCrawlDepth: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; }`\n - `results: { markdown: string; metadata: { crawlDepth: number; finalUrl: string; sourceUrl: string; statusCode: number; success: boolean; title: string; url: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; twitter?: object; }; }[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webCrawlMd({ url: 'https://example.com' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->webCrawlMd', - example: - "web->webCrawlMd(\n url: 'https://example.com',\n country: 'de',\n excludeSelectors: ['string'],\n followSubdomains: true,\n includeFrames: true,\n includeImages: true,\n includeLinks: true,\n includeSelectors: ['string'],\n maxAgeMs: 0,\n maxDepth: 0,\n maxPages: 1,\n pdf: ['end' => 1, 'ocr' => true, 'shouldParse' => true, 'start' => 1],\n settleAnimations: true,\n shortenBase64Images: true,\n stopAfterMs: 10000,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n urlRegex: '^https?://[^/]+/blog/',\n useMainContentOnly: true,\n waitForMs: 0,\n zdr: 'enabled',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.WebCrawlMd', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.WebCrawlMd(context.TODO(), contextdev.WebWebCrawlMdParams{\n\t\tURL: "https://example.com",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'web web_crawl_md', - example: "context-dev web web-crawl-md \\\n --api-key 'My API Key' \\\n --url https://example.com", - }, - python: { - method: 'web.web_crawl_md', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.web_crawl_md(\n url="https://example.com",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'web.web_crawl_md', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.web_crawl_md(url: "https://example.com")\n\nputs(response)', - }, - typescript: { - method: 'client.web.webCrawlMd', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.webCrawlMd({ url: 'https://example.com' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/crawl \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "url": "https://example.com",\n "country": "de",\n "tags": [\n "production",\n "team-alpha"\n ],\n "urlRegex": "^https?://[^/]+/blog/"\n }\'', - }, - }, - }, - { - name: 'extract_fonts', - endpoint: '/web/fonts', - httpMethod: 'get', - summary: 'Scrape Fonts', - description: - 'Scrape font information from a website including font families, usage statistics, fallbacks, and element/word counts.', - stainlessPath: '(resource) web > (method) extract_fonts', - qualified: 'client.web.extractFonts', - params: [ - 'directUrl?: string;', - 'domain?: string;', - 'maxAgeMs?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; code: number; domain: string; fonts: { fallbacks: string[]; font: string; num_elements: number; num_words: number; percent_elements: number; percent_words: number; uses: string[]; }[]; status: string; fontLinks?: object; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## extract_fonts\n\n`client.web.extractFonts(directUrl?: string, domain?: string, maxAgeMs?: number, tags?: string[], timeoutMS?: number): { cache_metadata: object; code: number; domain: string; fonts: object[]; status: string; fontLinks?: object; key_metadata?: object; }`\n\n**get** `/web/fonts`\n\nScrape font information from a website including font families, usage statistics, fallbacks, and element/word counts.\n\n### Parameters\n\n- `directUrl?: string`\n A specific URL to fetch fonts from directly, bypassing domain resolution (e.g., 'https://example.com/design-system'). When provided, fonts are extracted from this exact URL. You must provide either 'domain' or 'directUrl', but not both.\n\n- `domain?: string`\n Domain name to extract fonts from (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both.\n\n- `maxAgeMs?: number`\n Maximum age in milliseconds for cached brand data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 year.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; code: number; domain: string; fonts: { fallbacks: string[]; font: string; num_elements: number; num_words: number; percent_elements: number; percent_words: number; uses: string[]; }[]; status: string; fontLinks?: object; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `code: number`\n - `domain: string`\n - `fonts: { fallbacks: string[]; font: string; num_elements: number; num_words: number; percent_elements: number; percent_words: number; uses: string[]; }[]`\n - `status: string`\n - `fontLinks?: object`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.extractFonts();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->extractFonts', - example: - "web->extractFonts(\n directURL: 'https://example.com',\n domain: 'xxx',\n maxAgeMs: 0,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.ExtractFonts', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.ExtractFonts(context.TODO(), contextdev.WebExtractFontsParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'web extract_fonts', - example: "context-dev web extract-fonts \\\n --api-key 'My API Key'", - }, - python: { - method: 'web.extract_fonts', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.extract_fonts()\nprint(response.cache_metadata)', - }, - ruby: { - method: 'web.extract_fonts', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.extract_fonts\n\nputs(response)', - }, - typescript: { - method: 'client.web.extractFonts', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.extractFonts();\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/fonts \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'extract_styleguide', - endpoint: '/web/styleguide', - httpMethod: 'get', - summary: 'Scrape Styleguide', - description: - 'Extract a comprehensive design system from a website including colors, typography, spacing, shadows, and UI components.', - stainlessPath: '(resource) web > (method) extract_styleguide', - qualified: 'client.web.extractStyleguide', - params: [ - "colorScheme?: 'light' | 'dark';", - 'directUrl?: string;', - 'domain?: string;', - 'maxAgeMs?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; code?: number; domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; styleguide?: { colors: { accent: string; background: string; text: string; }; components: { button: object; card?: object; }; elementSpacing: { lg: string; md: string; sm: string; xl: string; xs: string; }; fontLinks: object; mode: 'light' | 'dark'; shadows: { inner: string; lg: string; md: string; sm: string; xl: string; }; typography: { headings: object; p?: object; }; }; }", - markdown: - "## extract_styleguide\n\n`client.web.extractStyleguide(colorScheme?: 'light' | 'dark', directUrl?: string, domain?: string, maxAgeMs?: number, tags?: string[], timeoutMS?: number): { cache_metadata: object; code?: number; domain?: string; key_metadata?: object; status?: string; styleguide?: object; }`\n\n**get** `/web/styleguide`\n\nExtract a comprehensive design system from a website including colors, typography, spacing, shadows, and UI components.\n\n### Parameters\n\n- `colorScheme?: 'light' | 'dark'`\n Optional browser color scheme to emulate for websites that respond to prefers-color-scheme. This value is part of the styleguide cache key.\n\n- `directUrl?: string`\n A specific URL to fetch the styleguide from directly, bypassing domain resolution (e.g., 'https://example.com/design-system'). When provided, the styleguide is extracted from this exact URL. You must provide either 'domain' or 'directUrl', but not both.\n\n- `domain?: string`\n Domain name to extract styleguide from (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both.\n\n- `maxAgeMs?: number`\n Maximum age in milliseconds for cached brand data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 year.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; code?: number; domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; styleguide?: { colors: { accent: string; background: string; text: string; }; components: { button: object; card?: object; }; elementSpacing: { lg: string; md: string; sm: string; xl: string; xs: string; }; fontLinks: object; mode: 'light' | 'dark'; shadows: { inner: string; lg: string; md: string; sm: string; xl: string; }; typography: { headings: object; p?: object; }; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `code?: number`\n - `domain?: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `status?: string`\n - `styleguide?: { colors: { accent: string; background: string; text: string; }; components: { button: { link?: { backgroundColor: string; borderColor: string; borderRadius: string; borderStyle: string; borderWidth: string; boxShadow: string; color: string; css: string; fontSize: string; fontWeight: number; minHeight: string; minWidth: string; padding: string; textDecoration: string; fontFallbacks?: string[]; fontFamily?: string; textDecorationColor?: string; }; primary?: { backgroundColor: string; borderColor: string; borderRadius: string; borderStyle: string; borderWidth: string; boxShadow: string; color: string; css: string; fontSize: string; fontWeight: number; minHeight: string; minWidth: string; padding: string; textDecoration: string; fontFallbacks?: string[]; fontFamily?: string; textDecorationColor?: string; }; secondary?: { backgroundColor: string; borderColor: string; borderRadius: string; borderStyle: string; borderWidth: string; boxShadow: string; color: string; css: string; fontSize: string; fontWeight: number; minHeight: string; minWidth: string; padding: string; textDecoration: string; fontFallbacks?: string[]; fontFamily?: string; textDecorationColor?: string; }; }; card?: { backgroundColor: string; borderColor: string; borderRadius: string; borderStyle: string; borderWidth: string; boxShadow: string; css: string; padding: string; textColor: string; }; }; elementSpacing: { lg: string; md: string; sm: string; xl: string; xs: string; }; fontLinks: object; mode: 'light' | 'dark'; shadows: { inner: string; lg: string; md: string; sm: string; xl: string; }; typography: { headings: { h1?: { fontFallbacks: string[]; fontFamily: string; fontSize: string; fontWeight: number; letterSpacing: string; lineHeight: string; }; h2?: { fontFallbacks: string[]; fontFamily: string; fontSize: string; fontWeight: number; letterSpacing: string; lineHeight: string; }; h3?: { fontFallbacks: string[]; fontFamily: string; fontSize: string; fontWeight: number; letterSpacing: string; lineHeight: string; }; h4?: { fontFallbacks: string[]; fontFamily: string; fontSize: string; fontWeight: number; letterSpacing: string; lineHeight: string; }; }; p?: { fontFallbacks: string[]; fontFamily: string; fontSize: string; fontWeight: number; letterSpacing: string; lineHeight: string; }; }; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.extractStyleguide();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->extractStyleguide', - example: - "web->extractStyleguide(\n colorScheme: 'light',\n directURL: 'https://example.com',\n domain: 'xxx',\n maxAgeMs: 0,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.ExtractStyleguide', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.ExtractStyleguide(context.TODO(), contextdev.WebExtractStyleguideParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Styleguide)\n}\n', - }, - cli: { - method: 'web extract_styleguide', - example: "context-dev web extract-styleguide \\\n --api-key 'My API Key'", - }, - python: { - method: 'web.extract_styleguide', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.extract_styleguide()\nprint(response.styleguide)', - }, - ruby: { - method: 'web.extract_styleguide', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.extract_styleguide\n\nputs(response)', - }, - typescript: { - method: 'client.web.extractStyleguide', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.extractStyleguide();\n\nconsole.log(response.styleguide);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/styleguide \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'search', - endpoint: '/web/search', - httpMethod: 'post', - summary: 'Web Search', - description: 'Search the web and optionally scrape each result to Markdown in one round-trip.', - stainlessPath: '(resource) web > (method) search', - qualified: 'client.web.search', - params: [ - 'query: string;', - 'country?: string;', - 'excludeDomains?: string[];', - "freshness?: 'last_24_hours' | 'last_week' | 'last_month' | 'last_year';", - 'includeDomains?: string[];', - 'markdownOptions?: { enabled?: boolean; includeFrames?: boolean; includeImages?: boolean; includeLinks?: boolean; maxAgeMs?: number; pdf?: { end?: number; shouldParse?: boolean; start?: number; }; shortenBase64Images?: boolean; timeoutMS?: number; useMainContentOnly?: boolean; waitForMs?: number; };', - 'numResults?: number;', - 'queryFanout?: boolean;', - 'tags?: string[];', - 'timeoutMS?: number;', - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; query: string; results: { description: string; markdown: { code: 'SUCCESS' | 'NOT_REQUESTED' | 'TIMEOUT' | 'CONTENT_TOO_LARGE' | 'WEBSITE_ACCESS_ERROR' | 'ERROR'; markdown: string; }; relevance: 'high' | 'medium' | 'low'; title: string; url: string; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## search\n\n`client.web.search(query: string, country?: string, excludeDomains?: string[], freshness?: 'last_24_hours' | 'last_week' | 'last_month' | 'last_year', includeDomains?: string[], markdownOptions?: { enabled?: boolean; includeFrames?: boolean; includeImages?: boolean; includeLinks?: boolean; maxAgeMs?: number; pdf?: { end?: number; shouldParse?: boolean; start?: number; }; shortenBase64Images?: boolean; timeoutMS?: number; useMainContentOnly?: boolean; waitForMs?: number; }, numResults?: number, queryFanout?: boolean, tags?: string[], timeoutMS?: number): { cache_metadata: object; query: string; results: object[]; key_metadata?: object; }`\n\n**post** `/web/search`\n\nSearch the web and optionally scrape each result to Markdown in one round-trip.\n\n### Parameters\n\n- `query: string`\n Search query. Accepts natural language as well as Google-style search operators such as `site:`, `-site:`, `inurl:`, `intitle:`, quoted phrases, and `OR`.\n\n- `country?: string`\n Two-letter ISO 3166-1 alpha-2 country code to localize results to a specific country (maps to Google's `gl` parameter). Example: \"us\", \"gb\", \"de\".\n\n- `excludeDomains?: string[]`\n Blocklist — drop results from these domains. Example: [\"pinterest.com\", \"reddit.com\"].\n\n- `freshness?: 'last_24_hours' | 'last_week' | 'last_month' | 'last_year'`\n Restrict results to content published within this window.\n\n- `includeDomains?: string[]`\n Allowlist — only return results from these domains. Example: [\"arxiv.org\", \"github.com\"].\n\n- `markdownOptions?: { enabled?: boolean; includeFrames?: boolean; includeImages?: boolean; includeLinks?: boolean; maxAgeMs?: number; pdf?: { end?: number; shouldParse?: boolean; start?: number; }; shortenBase64Images?: boolean; timeoutMS?: number; useMainContentOnly?: boolean; waitForMs?: number; }`\n Inline Markdown scraping for each result. Set `enabled: true` to activate.\n - `enabled?: boolean`\n Scrape each result to Markdown. Off by default to keep search cheap and fast.\n - `includeFrames?: boolean`\n Render iframe contents into the Markdown.\n - `includeImages?: boolean`\n Emit image references in the Markdown.\n - `includeLinks?: boolean`\n Keep hyperlinks in the Markdown.\n - `maxAgeMs?: number`\n Cache TTL in ms for scraped Markdown keyed by URL + options. Default 1 day, max 30 days. Set to 0 to force a fresh scrape.\n - `pdf?: { end?: number; shouldParse?: boolean; start?: number; }`\n PDF handling. Use start/end to bound text extraction and OCR to a page range.\n - `shortenBase64Images?: boolean`\n Truncate inline base64 image payloads to keep responses small.\n - `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n - `useMainContentOnly?: boolean`\n Strip nav, header, footer, and sidebar — keep only the primary article content.\n - `waitForMs?: number`\n Extra wait after page load before rendering, in ms (0–30000). Useful for JS-heavy pages.\n\n- `numResults?: number`\n Number of results to request and return (10–100). Defaults to 10.\n\n- `queryFanout?: boolean`\n Expand the query into multiple parallel variants for broader recall.\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; query: string; results: { description: string; markdown: { code: 'SUCCESS' | 'NOT_REQUESTED' | 'TIMEOUT' | 'CONTENT_TOO_LARGE' | 'WEBSITE_ACCESS_ERROR' | 'ERROR'; markdown: string; }; relevance: 'high' | 'medium' | 'low'; title: string; url: string; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `query: string`\n - `results: { description: string; markdown: { code: 'SUCCESS' | 'NOT_REQUESTED' | 'TIMEOUT' | 'CONTENT_TOO_LARGE' | 'WEBSITE_ACCESS_ERROR' | 'ERROR'; markdown: string; }; relevance: 'high' | 'medium' | 'low'; title: string; url: string; }[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.search({ query: 'x' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->search', - example: - "web->search(\n query: 'x',\n country: 'af',\n excludeDomains: ['string'],\n freshness: 'last_24_hours',\n includeDomains: ['string'],\n markdownOptions: [\n 'enabled' => true,\n 'includeFrames' => true,\n 'includeImages' => true,\n 'includeLinks' => true,\n 'maxAgeMs' => 0,\n 'pdf' => ['end' => 1, 'shouldParse' => true, 'start' => 1],\n 'shortenBase64Images' => true,\n 'timeoutMs' => 1000,\n 'useMainContentOnly' => true,\n 'waitForMs' => 0,\n ],\n numResults: 10,\n queryFanout: true,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.Search', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.Search(context.TODO(), contextdev.WebSearchParams{\n\t\tQuery: "x",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'web search', - example: "context-dev web search \\\n --api-key 'My API Key' \\\n --query x", - }, - python: { - method: 'web.search', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.search(\n query="x",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'web.search', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.search(query: "x")\n\nputs(response)', - }, - typescript: { - method: 'client.web.search', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.search({ query: 'x' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/search \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "query": "x",\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, - { - name: 'extract', - endpoint: '/web/extract', - httpMethod: 'post', - summary: 'Extract Structured Website Data', - description: - 'Crawl a website, use the provided JSON Schema and instructions to prioritize relevant internal links, and extract structured data from the selected pages.', - stainlessPath: '(resource) web > (method) extract', - qualified: 'client.web.extract', - params: [ - 'schema: object;', - 'url: string;', - "actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[];", - 'factCheck?: boolean;', - 'followSubdomains?: boolean;', - 'includeFrames?: boolean;', - 'instructions?: string;', - 'maxAgeMs?: number;', - 'maxDepth?: number;', - 'maxPages?: number;', - 'pdf?: { end?: number; shouldParse?: boolean; start?: number; };', - 'settleAnimations?: boolean;', - 'stopAfterMs?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - 'waitForMs?: number;', - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; data: object; metadata: { maxCrawlDepth: number; numBlocked: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; }; status: string; url: string; urls_analyzed: string[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## extract\n\n`client.web.extract(schema: object, url: string, actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[], factCheck?: boolean, followSubdomains?: boolean, includeFrames?: boolean, instructions?: string, maxAgeMs?: number, maxDepth?: number, maxPages?: number, pdf?: { end?: number; shouldParse?: boolean; start?: number; }, settleAnimations?: boolean, stopAfterMs?: number, tags?: string[], timeoutMS?: number, waitForMs?: number): { cache_metadata: object; data: object; metadata: object; status: string; url: string; urls_analyzed: string[]; key_metadata?: object; }`\n\n**post** `/web/extract`\n\nCrawl a website, use the provided JSON Schema and instructions to prioritize relevant internal links, and extract structured data from the selected pages.\n\n### Parameters\n\n- `schema: object`\n JSON Schema for the returned data object. Image fields such as `image_urls` or `product_photos` automatically make page image references available to extraction, so product data and photos can be returned in one call. TypeScript Zod users can pass a JSON Schema generated from a Zod object; Python users can pass the equivalent JSON Schema object.\n\n- `url: string`\n The starting website URL to crawl and extract from. Must include http:// or https://.\n\n- `actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[]`\n Optional browser actions executed in order on the requested page after it loads, before links are discovered or additional pages are crawled. Requires a paid plan. When actions are provided and stopAfterMs is omitted, the crawl budget defaults to 110000 ms.\n\n- `factCheck?: boolean`\n When true, every returned value must be grounded in facts stated on the page; fields that cannot be supported by the page are returned as null/empty. When false (default), the model may make reasonable inferences and derivations from the page content (e.g. ideal customer, competitor analysis, recommendations) while keeping verifiable specifics (names, quotes, URLs, dates, metrics) faithful to the source.\n\n- `followSubdomains?: boolean`\n When true, follow links on subdomains of the starting URL's domain.\n\n- `includeFrames?: boolean`\n When true, iframe contents are included in Markdown before extraction.\n\n- `instructions?: string`\n Optional extraction guidance, such as which facts to prioritize or how to interpret fields in the schema.\n\n- `maxAgeMs?: number`\n Return cached scrape results if a prior scrape for the same parameters is younger than this many milliseconds. Defaults to 7 days (604800000 ms).\n\n- `maxDepth?: number`\n Optional maximum link depth from the starting URL (0 = only the starting page). If omitted, there is no crawl depth limit.\n\n- `maxPages?: number`\n Maximum number of pages to analyze for extraction. Hard cap: 50. Defaults to 5.\n\n- `pdf?: { end?: number; shouldParse?: boolean; start?: number; }`\n - `end?: number`\n Last 1-based PDF page to parse. Must be greater than or equal to start when both are provided.\n - `shouldParse?: boolean`\n When true, PDF pages are fetched and parsed. When false, PDF pages are skipped.\n - `start?: number`\n First 1-based PDF page to parse.\n\n- `settleAnimations?: boolean`\n When true, waits briefly for CSS and transition animations to settle before extracting each crawled page. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `stopAfterMs?: number`\n Soft time budget for the crawl in milliseconds. Min: 10000 (10s). Max: 110000 (110s). Defaults to 80000 (80s), or 110000 (110s) when browser actions are provided.\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load for each crawled page.\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; data: object; metadata: { maxCrawlDepth: number; numBlocked: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; }; status: string; url: string; urls_analyzed: string[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `data: object`\n - `metadata: { maxCrawlDepth: number; numBlocked: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; }`\n - `status: string`\n - `url: string`\n - `urls_analyzed: string[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.extract({\n schema: {\n type: 'bar',\n properties: 'bar',\n required: 'bar',\n additionalProperties: 'bar',\n},\n url: 'https://example.com',\n});\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->extract', - example: - "web->extract(\n schema: [\n 'type' => 'bar',\n 'properties' => 'bar',\n 'required' => 'bar',\n 'additionalProperties' => 'bar',\n ],\n url: 'https://example.com',\n actions: [['do' => 'wait', 'timeMs' => 0]],\n factCheck: true,\n followSubdomains: true,\n includeFrames: true,\n instructions: 'instructions',\n maxAgeMs: 0,\n maxDepth: 0,\n maxPages: 1,\n pdf: ['end' => 1, 'shouldParse' => true, 'start' => 1],\n settleAnimations: true,\n stopAfterMs: 10000,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n waitForMs: 0,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.Extract', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.Extract(context.TODO(), contextdev.WebExtractParams{\n\t\tSchema: map[string]any{\n\t\t\t"type": "bar",\n\t\t\t"properties": "bar",\n\t\t\t"required": "bar",\n\t\t\t"additionalProperties": "bar",\n\t\t},\n\t\tURL: "https://example.com",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'web extract', - example: - "context-dev web extract \\\n --api-key 'My API Key' \\\n --schema '{type: bar, properties: bar, required: bar, additionalProperties: bar}' \\\n --url https://example.com", - }, - python: { - method: 'web.extract', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.extract(\n schema={\n "type": "bar",\n "properties": "bar",\n "required": "bar",\n "additionalProperties": "bar",\n },\n url="https://example.com",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'web.extract', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.extract(\n schema: {type: "bar", properties: "bar", required: "bar", additionalProperties: "bar"},\n url: "https://example.com"\n)\n\nputs(response)', - }, - typescript: { - method: 'client.web.extract', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.extract({\n schema: {\n type: 'bar',\n properties: 'bar',\n required: 'bar',\n additionalProperties: 'bar',\n },\n url: 'https://example.com',\n});\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/extract \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "schema": {\n "type": "bar",\n "properties": "bar",\n "required": "bar",\n "additionalProperties": "bar"\n },\n "url": "https://example.com",\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, - { - name: 'extract_competitors', - endpoint: '/web/competitors', - httpMethod: 'get', - summary: 'Find website competitors', - description: - "Analyze a company's landing page and web search evidence to return direct competitors for the same product or market.", - stainlessPath: '(resource) web > (method) extract_competitors', - qualified: 'client.web.extractCompetitors', - params: ['domain: string;', 'numCompetitors?: number;', 'tags?: string[];', 'timeoutMS?: number;'], - response: - "{ competitors: { confidence: 'high' | 'medium'; description: string; domain: string; name: string; sourceUrls: string[]; url: string; }[]; domain: string; status: 'ok'; target: { companyName: string; field: string; fieldDescription: string; websiteUrl: string; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## extract_competitors\n\n`client.web.extractCompetitors(domain: string, numCompetitors?: number, tags?: string[], timeoutMS?: number): { competitors: object[]; domain: string; status: 'ok'; target: object; key_metadata?: object; }`\n\n**get** `/web/competitors`\n\nAnalyze a company's landing page and web search evidence to return direct competitors for the same product or market.\n\n### Parameters\n\n- `domain: string`\n Company domain to analyze, such as `stripe.com`. Full http(s) URLs are accepted and normalized to their domain.\n\n- `numCompetitors?: number`\n Exact number of direct competitors to return. Defaults to 5.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ competitors: { confidence: 'high' | 'medium'; description: string; domain: string; name: string; sourceUrls: string[]; url: string; }[]; domain: string; status: 'ok'; target: { companyName: string; field: string; fieldDescription: string; websiteUrl: string; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `competitors: { confidence: 'high' | 'medium'; description: string; domain: string; name: string; sourceUrls: string[]; url: string; }[]`\n - `domain: string`\n - `status: 'ok'`\n - `target: { companyName: string; field: string; fieldDescription: string; websiteUrl: string; }`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.extractCompetitors({ domain: 'xxx' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->extractCompetitors', - example: - "web->extractCompetitors(\n domain: 'xxx',\n numCompetitors: 1,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.ExtractCompetitors', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.ExtractCompetitors(context.TODO(), contextdev.WebExtractCompetitorsParams{\n\t\tDomain: "xxx",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Competitors)\n}\n', - }, - cli: { - method: 'web extract_competitors', - example: "context-dev web extract-competitors \\\n --api-key 'My API Key' \\\n --domain xxx", - }, - python: { - method: 'web.extract_competitors', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.extract_competitors(\n domain="xxx",\n)\nprint(response.competitors)', - }, - ruby: { - method: 'web.extract_competitors', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.extract_competitors(domain: "xxx")\n\nputs(response)', - }, - typescript: { - method: 'client.web.extractCompetitors', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.extractCompetitors({ domain: 'xxx' });\n\nconsole.log(response.competitors);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/competitors \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'extract_products', - endpoint: '/brand/ai/products', - httpMethod: 'post', - summary: "Extract products from a brand's website", - description: - "Extract product information from a brand's website. We will analyze the website and return a list of products with details such as name, description, image, pricing, features, and more.", - stainlessPath: '(resource) ai > (method) extract_products', - qualified: 'client.ai.extractProducts', - params: [ - '{ domain: string; maxAgeMs?: number; maxProducts?: number; tags?: string[]; timeoutMS?: number; } | { directUrl: string; maxAgeMs?: number; maxProducts?: number; tags?: string[]; timeoutMS?: number; };', - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; products?: { description: string; features: string[]; images: string[]; name: string; sku: string; tags: string[]; target_audience: string[]; availability?: string; billing_frequency?: 'monthly' | 'yearly' | 'one_time' | 'usage_based'; category?: string; currency?: string; dimensions?: string[]; image_url?: string; price?: number; pricing_model?: 'per_seat' | 'flat' | 'tiered' | 'freemium' | 'custom'; regular_price?: number; url?: string; }[]; }", - perLanguage: { - php: { - method: 'ai->extractProducts', - example: - "ai->extractProducts(\n domain: 'domain',\n maxAgeMs: 0,\n maxProducts: 1,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n directURL: 'https://example.com',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.AI.ExtractProducts', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.AI.ExtractProducts(context.TODO(), contextdev.AIExtractProductsParams{\n\t\tOfByDomain: &contextdev.AIExtractProductsParamsBodyByDomain{\n\t\t\tDomain: "domain",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'ai extract_products', - example: - "context-dev ai extract-products \\\n --api-key 'My API Key' \\\n --domain domain \\\n --direct-url https://example.com", - }, - python: { - method: 'ai.extract_products', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.ai.extract_products(\n domain="domain",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'ai.extract_products', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.ai.extract_products(body: {domain: "domain"})\n\nputs(response)', - }, - typescript: { - method: 'client.ai.extractProducts', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.ai.extractProducts({ domain: 'domain' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/brand/ai/products \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "domain": "domain",\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, - { - name: 'extract_product', - endpoint: '/brand/ai/product', - httpMethod: 'post', - summary: 'Extract a single product from a URL', - description: - 'Given a single URL, determines if it is a product page and extracts the product information.', - stainlessPath: '(resource) ai > (method) extract_product', - qualified: 'client.ai.extractProduct', - params: ['url: string;', 'maxAgeMs?: number;', 'tags?: string[];', 'timeoutMS?: number;'], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; is_product_page?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; platform?: 'amazon' | 'tiktok_shop' | 'etsy' | 'generic'; product?: { description: string; features: string[]; images: string[]; name: string; sku: string; tags: string[]; target_audience: string[]; availability?: string; billing_frequency?: 'monthly' | 'yearly' | 'one_time' | 'usage_based'; category?: string; currency?: string; dimensions?: string[]; image_url?: string; price?: number; pricing_model?: 'per_seat' | 'flat' | 'tiered' | 'freemium' | 'custom'; regular_price?: number; url?: string; }; }", - markdown: - "## extract_product\n\n`client.ai.extractProduct(url: string, maxAgeMs?: number, tags?: string[], timeoutMS?: number): { cache_metadata: object; is_product_page?: boolean; key_metadata?: object; platform?: 'amazon' | 'tiktok_shop' | 'etsy' | 'generic'; product?: object; }`\n\n**post** `/brand/ai/product`\n\nGiven a single URL, determines if it is a product page and extracts the product information.\n\n### Parameters\n\n- `url: string`\n The product page URL to extract product data from.\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 7 days (604800000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; is_product_page?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; platform?: 'amazon' | 'tiktok_shop' | 'etsy' | 'generic'; product?: { description: string; features: string[]; images: string[]; name: string; sku: string; tags: string[]; target_audience: string[]; availability?: string; billing_frequency?: 'monthly' | 'yearly' | 'one_time' | 'usage_based'; category?: string; currency?: string; dimensions?: string[]; image_url?: string; price?: number; pricing_model?: 'per_seat' | 'flat' | 'tiered' | 'freemium' | 'custom'; regular_price?: number; url?: string; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `is_product_page?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `platform?: 'amazon' | 'tiktok_shop' | 'etsy' | 'generic'`\n - `product?: { description: string; features: string[]; images: string[]; name: string; sku: string; tags: string[]; target_audience: string[]; availability?: string; billing_frequency?: 'monthly' | 'yearly' | 'one_time' | 'usage_based'; category?: string; currency?: string; dimensions?: string[]; image_url?: string; price?: number; pricing_model?: 'per_seat' | 'flat' | 'tiered' | 'freemium' | 'custom'; regular_price?: number; url?: string; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.ai.extractProduct({ url: 'https://example.com' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'ai->extractProduct', - example: - "ai->extractProduct(\n url: 'https://example.com',\n maxAgeMs: 0,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.AI.ExtractProduct', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.AI.ExtractProduct(context.TODO(), contextdev.AIExtractProductParams{\n\t\tURL: "https://example.com",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'ai extract_product', - example: - "context-dev ai extract-product \\\n --api-key 'My API Key' \\\n --url https://example.com", - }, - python: { - method: 'ai.extract_product', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.ai.extract_product(\n url="https://example.com",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'ai.extract_product', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.ai.extract_product(url: "https://example.com")\n\nputs(response)', - }, - typescript: { - method: 'client.ai.extractProduct', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.ai.extractProduct({ url: 'https://example.com' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/brand/ai/product \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "url": "https://example.com",\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, - { - name: 'retrieve', - endpoint: '/brand/retrieve', - httpMethod: 'post', - summary: 'Retrieve brand data', - description: - 'Retrieve logos, backdrops, colors, industry, description, and more. Provide exactly one lookup identifier in the request body: a domain, company name, email address, stock ticker, transaction descriptor, or direct URL. Note: `by_direct_url` fetches brand data only from the provided URL — not from the entire internet.', - stainlessPath: '(resource) brand > (method) retrieve', - qualified: 'client.brand.retrieve', - params: [ - "{ domain: string; type: 'by_domain'; force_language?: string; maxAgeMs?: number; maxSpeed?: boolean; tags?: string[]; timeoutMS?: number; } | { name: string; type: 'by_name'; country_gl?: string; force_language?: string; maxAgeMs?: number; maxSpeed?: boolean; tags?: string[]; timeoutMS?: number; } | { email: string; type: 'by_email'; force_language?: string; maxAgeMs?: number; maxSpeed?: boolean; tags?: string[]; timeoutMS?: number; } | { ticker: string; type: 'by_ticker'; force_language?: string; maxAgeMs?: number; maxSpeed?: boolean; tags?: string[]; ticker_exchange?: string; timeoutMS?: number; } | { direct_url: string; type: 'by_direct_url'; tags?: string[]; timeoutMS?: number; } | { transaction_info: string; type: 'by_transaction'; city?: string; country_gl?: string; force_language?: string; high_confidence_only?: boolean; maxSpeed?: boolean; mcc?: string | number; phone?: string | number; tags?: string[]; timeoutMS?: number; };", - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; brand?: { address?: { city?: string; country?: string; country_code?: string; postal_code?: string; state_code?: string; state_province?: string; street?: string; }; backdrops?: { colors?: object[]; resolution?: object; url?: string; }[]; colors?: { hex?: string; name?: string; source?: 'site' | 'logo'; }[]; description?: string; domain?: string; email?: string; employees?: { exact?: number; range?: string; }; industries?: { eic?: object[]; }; is_nsfw?: boolean; links?: { blog?: string; careers?: string; contact?: string; pricing?: string; privacy?: string; terms?: string; }; logos?: { colors?: object[]; mode?: 'light' | 'dark' | 'has_opaque_background'; resolution?: object; type?: 'icon' | 'logo'; url?: string; }[]; phone?: string; primary_language?: string; slogan?: string; socials?: { type?: string; url?: string; }[]; stock?: { exchange?: string; ticker?: string; }; title?: string; }; code?: number; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; }", - perLanguage: { - php: { - method: 'brand->retrieve', - example: - "brand->retrieve(\n domain: 'xxx',\n type: 'by_transaction',\n forceLanguage: 'afrikaans',\n maxAgeMs: 0,\n maxSpeed: true,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n name: 'xxx',\n countryGl: 'country_gl',\n email: 'dev@stainless.com',\n ticker: 'ticker',\n tickerExchange: 'ticker_exchange',\n directURL: 'https://example.com',\n transactionInfo: 'xxx',\n city: 'city',\n highConfidenceOnly: true,\n mcc: 'string',\n phone: 'string',\n);\n\nvar_dump($brand);", - }, - go: { - method: 'client.Brand.Get', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tbrand, err := client.Brand.Get(context.TODO(), contextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", brand.CacheMetadata)\n}\n', - }, - cli: { - method: 'brand retrieve', - example: - "context-dev brand retrieve \\\n --api-key 'My API Key' \\\n --domain xxx \\\n --type by_domain \\\n --name xxx \\\n --email dev@stainless.com \\\n --ticker ticker \\\n --direct-url https://example.com \\\n --transaction-info xxx", - }, - python: { - method: 'brand.retrieve', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nbrand = client.brand.retrieve(\n domain="stripe.com",\n type="by_domain",\n)\nprint(brand.cache_metadata)', - }, - ruby: { - method: 'brand.retrieve', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nbrand = context_dev.brand.retrieve(body: {domain: "stripe.com", type: :by_domain})\n\nputs(brand)', - }, - typescript: { - method: 'client.brand.retrieve', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst brand = await client.brand.retrieve({ domain: 'stripe.com', type: 'by_domain' });\n\nconsole.log(brand.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/brand/retrieve \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "domain": "xxx",\n "type": "by_domain",\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, - { - name: 'search', - endpoint: '/brand/search', - httpMethod: 'get', - summary: 'Brand Search', - description: 'Search indexed brands by name or domain', - stainlessPath: '(resource) brand > (method) search', - qualified: 'client.brand.search', - params: [ - 'query: string;', - 'autocomplete?: boolean;', - "queryBy?: 'name' | 'domain'[];", - 'tags?: string[];', - 'typoTolerance?: number;', - ], - response: - '{ results: { domain: string; logo: string; name: string; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }', - markdown: - "## search\n\n`client.brand.search(query: string, autocomplete?: boolean, queryBy?: 'name' | 'domain'[], tags?: string[], typoTolerance?: number): { results: object[]; key_metadata?: object; }`\n\n**get** `/brand/search`\n\nSearch indexed brands by name or domain\n\n### Parameters\n\n- `query: string`\n Search term, matched against the fields selected by queryBy (e.g. 'nike', 'nike.com', 'nik').\n\n- `autocomplete?: boolean`\n Whether the search term matches by prefix, so partial words match as they are typed (e.g. 'nik' matches Nike). Set to false to match whole words only.\n\n- `queryBy?: 'name' | 'domain'[]`\n Fields to match the search term against, as a comma-separated list or repeated parameter: 'name', 'domain', or both. Defaults to both.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `typoTolerance?: number`\n Maximum number of typos tolerated when matching, from 0 to 2. Defaults to 0 (no typo tolerance).\n\n### Returns\n\n- `{ results: { domain: string; logo: string; name: string; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `results: { domain: string; logo: string; name: string; }[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.brand.search({ query: 'x' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'brand->search', - example: - "brand->search(\n query: 'x',\n autocomplete: true,\n queryBy: ['name'],\n tags: ['production', 'team-alpha'],\n typoTolerance: 0,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Brand.Search', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Brand.Search(context.TODO(), contextdev.BrandSearchParams{\n\t\tQuery: "x",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Results)\n}\n', - }, - cli: { - method: 'brand search', - example: "context-dev brand search \\\n --api-key 'My API Key' \\\n --query x", - }, - python: { - method: 'brand.search', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.brand.search(\n query="x",\n)\nprint(response.results)', - }, - ruby: { - method: 'brand.search', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.brand.search(query: "x")\n\nputs(response)', - }, - typescript: { - method: 'client.brand.search', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.brand.search({ query: 'x' });\n\nconsole.log(response.results);", - }, - http: { - example: - 'curl https://api.context.dev/v1/brand/search \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'retrieve_simplified', - endpoint: '/brand/retrieve-simplified', - httpMethod: 'get', - summary: 'Retrieve simplified brand data by domain', - description: - 'Returns a simplified version of brand data containing only essential information: domain, title, colors, logos, and backdrops. Optimized for faster responses and reduced data transfer.', - stainlessPath: '(resource) brand > (method) retrieve_simplified', - qualified: 'client.brand.retrieveSimplified', - params: [ - 'domain: string;', - 'maxAgeMs?: number;', - 'tags?: string[];', - "theme?: 'light' | 'dark';", - 'timeoutMS?: number;', - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; brand?: { backdrops?: { colors?: object[]; resolution?: object; url?: string; }[]; colors?: { hex?: string; name?: string; source?: 'site' | 'logo'; }[]; domain?: string; logos?: { colors?: object[]; mode?: 'light' | 'dark' | 'has_opaque_background'; resolution?: object; type?: 'icon' | 'logo'; url?: string; }[]; title?: string; }; code?: number; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; }", - markdown: - "## retrieve_simplified\n\n`client.brand.retrieveSimplified(domain: string, maxAgeMs?: number, tags?: string[], theme?: 'light' | 'dark', timeoutMS?: number): { cache_metadata: object; brand?: object; code?: number; key_metadata?: object; status?: string; }`\n\n**get** `/brand/retrieve-simplified`\n\nReturns a simplified version of brand data containing only essential information: domain, title, colors, logos, and backdrops. Optimized for faster responses and reduced data transfer.\n\n### Parameters\n\n- `domain: string`\n Domain name to retrieve simplified brand data for\n\n- `maxAgeMs?: number`\n Maximum age in milliseconds for cached brand data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 year.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `theme?: 'light' | 'dark'`\n Optional theme preference used when selecting brand assets.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; brand?: { backdrops?: { colors?: object[]; resolution?: object; url?: string; }[]; colors?: { hex?: string; name?: string; source?: 'site' | 'logo'; }[]; domain?: string; logos?: { colors?: object[]; mode?: 'light' | 'dark' | 'has_opaque_background'; resolution?: object; type?: 'icon' | 'logo'; url?: string; }[]; title?: string; }; code?: number; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `brand?: { backdrops?: { colors?: { hex?: string; name?: string; }[]; resolution?: { aspect_ratio?: number; height?: number; width?: number; }; url?: string; }[]; colors?: { hex?: string; name?: string; source?: 'site' | 'logo'; }[]; domain?: string; logos?: { colors?: { hex?: string; name?: string; }[]; mode?: 'light' | 'dark' | 'has_opaque_background'; resolution?: { aspect_ratio?: number; height?: number; width?: number; }; type?: 'icon' | 'logo'; url?: string; }[]; title?: string; }`\n - `code?: number`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `status?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.brand.retrieveSimplified({ domain: 'xxx' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'brand->retrieveSimplified', - example: - "brand->retrieveSimplified(\n domain: 'xxx',\n maxAgeMs: 0,\n tags: ['production', 'team-alpha'],\n theme: 'light',\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Brand.GetSimplified', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Brand.GetSimplified(context.TODO(), contextdev.BrandGetSimplifiedParams{\n\t\tDomain: "xxx",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'brand retrieve_simplified', - example: "context-dev brand retrieve-simplified \\\n --api-key 'My API Key' \\\n --domain xxx", - }, - python: { - method: 'brand.retrieve_simplified', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.brand.retrieve_simplified(\n domain="xxx",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'brand.retrieve_simplified', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.brand.retrieve_simplified(domain: "xxx")\n\nputs(response)', - }, - typescript: { - method: 'client.brand.retrieveSimplified', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.brand.retrieveSimplified({ domain: 'xxx' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/brand/retrieve-simplified \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'retrieve_naics', - endpoint: '/web/naics', - httpMethod: 'get', - summary: 'Classify NAICS industries', - description: 'Classify any brand into 2022 NAICS industry codes from its domain or name.', - stainlessPath: '(resource) industry > (method) retrieve_naics', - qualified: 'client.industry.retrieveNaics', - params: [ - 'input: string;', - 'maxResults?: number;', - 'minResults?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - ], - response: - "{ codes?: { code: string; confidence: 'high' | 'medium' | 'low'; name: string; }[]; domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; type?: string; }", - markdown: - "## retrieve_naics\n\n`client.industry.retrieveNaics(input: string, maxResults?: number, minResults?: number, tags?: string[], timeoutMS?: number): { codes?: object[]; domain?: string; key_metadata?: object; status?: string; type?: string; }`\n\n**get** `/web/naics`\n\nClassify any brand into 2022 NAICS industry codes from its domain or name.\n\n### Parameters\n\n- `input: string`\n Brand domain or title to retrieve NAICS code for. If a valid domain is provided, it will be used for classification, otherwise, we will search for the brand using the provided title.\n\n- `maxResults?: number`\n Maximum number of NAICS codes to return. Must be between 1 and 10. Defaults to 5.\n\n- `minResults?: number`\n Minimum number of NAICS codes to return. Must be at least 1. Defaults to 1.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ codes?: { code: string; confidence: 'high' | 'medium' | 'low'; name: string; }[]; domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; type?: string; }`\n\n - `codes?: { code: string; confidence: 'high' | 'medium' | 'low'; name: string; }[]`\n - `domain?: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `status?: string`\n - `type?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.industry.retrieveNaics({ input: 'xxxx' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'industry->retrieveNaics', - example: - "industry->retrieveNaics(\n input: 'xxxx',\n maxResults: 1,\n minResults: 1,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Industry.GetNaics', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Industry.GetNaics(context.TODO(), contextdev.IndustryGetNaicsParams{\n\t\tInput: "xxxx",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Codes)\n}\n', - }, - cli: { - method: 'industry retrieve_naics', - example: "context-dev industry retrieve-naics \\\n --api-key 'My API Key' \\\n --input xxxx", - }, - python: { - method: 'industry.retrieve_naics', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.industry.retrieve_naics(\n input="xxxx",\n)\nprint(response.codes)', - }, - ruby: { - method: 'industry.retrieve_naics', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.industry.retrieve_naics(input: "xxxx")\n\nputs(response)', - }, - typescript: { - method: 'client.industry.retrieveNaics', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.industry.retrieveNaics({ input: 'xxxx' });\n\nconsole.log(response.codes);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/naics \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'retrieve_sic', - endpoint: '/web/sic', - httpMethod: 'get', - summary: 'Classify SIC industries', - description: - 'Classify any brand into Standard Industrial Classification (SIC) codes from its domain or name. Choose between the original SIC system (`original_sic`) or the latest SIC list maintained by the SEC (`latest_sec`).', - stainlessPath: '(resource) industry > (method) retrieve_sic', - qualified: 'client.industry.retrieveSic', - params: [ - 'input: string;', - 'maxResults?: number;', - 'minResults?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - "type?: 'original_sic' | 'latest_sec';", - ], - response: - "{ classification?: 'original_sic' | 'latest_sec'; codes?: { code: string; confidence: 'high' | 'medium' | 'low'; name: string; majorGroup?: string; majorGroupName?: string; office?: string; }[]; domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; type?: string; }", - markdown: - "## retrieve_sic\n\n`client.industry.retrieveSic(input: string, maxResults?: number, minResults?: number, tags?: string[], timeoutMS?: number, type?: 'original_sic' | 'latest_sec'): { classification?: 'original_sic' | 'latest_sec'; codes?: object[]; domain?: string; key_metadata?: object; status?: string; type?: string; }`\n\n**get** `/web/sic`\n\nClassify any brand into Standard Industrial Classification (SIC) codes from its domain or name. Choose between the original SIC system (`original_sic`) or the latest SIC list maintained by the SEC (`latest_sec`).\n\n### Parameters\n\n- `input: string`\n Brand domain or title to retrieve SIC code for. If a valid domain is provided, it will be used for classification, otherwise, we will search for the brand using the provided title.\n\n- `maxResults?: number`\n Maximum number of SIC codes to return. Must be between 1 and 10. Defaults to 5.\n\n- `minResults?: number`\n Minimum number of SIC codes to return. Must be at least 1. Defaults to 1.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `type?: 'original_sic' | 'latest_sec'`\n Which SIC dataset to classify against. `original_sic` uses the 1987 Standard Industrial Classification system; `latest_sec` uses the current SIC list as published by the SEC. Defaults to `original_sic`.\n\n### Returns\n\n- `{ classification?: 'original_sic' | 'latest_sec'; codes?: { code: string; confidence: 'high' | 'medium' | 'low'; name: string; majorGroup?: string; majorGroupName?: string; office?: string; }[]; domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; type?: string; }`\n\n - `classification?: 'original_sic' | 'latest_sec'`\n - `codes?: { code: string; confidence: 'high' | 'medium' | 'low'; name: string; majorGroup?: string; majorGroupName?: string; office?: string; }[]`\n - `domain?: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `status?: string`\n - `type?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.industry.retrieveSic({ input: 'xxxx' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'industry->retrieveSic', - example: - "industry->retrieveSic(\n input: 'xxxx',\n maxResults: 1,\n minResults: 1,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n type: 'original_sic',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Industry.GetSic', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Industry.GetSic(context.TODO(), contextdev.IndustryGetSicParams{\n\t\tInput: "xxxx",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Classification)\n}\n', - }, - cli: { - method: 'industry retrieve_sic', - example: "context-dev industry retrieve-sic \\\n --api-key 'My API Key' \\\n --input xxxx", - }, - python: { - method: 'industry.retrieve_sic', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.industry.retrieve_sic(\n input="xxxx",\n)\nprint(response.classification)', - }, - ruby: { - method: 'industry.retrieve_sic', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.industry.retrieve_sic(input: "xxxx")\n\nputs(response)', - }, - typescript: { - method: 'client.industry.retrieveSic', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.industry.retrieveSic({ input: 'xxxx' });\n\nconsole.log(response.classification);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/sic \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'prefetch', - endpoint: '/utility/prefetch', - httpMethod: 'post', - summary: 'Prefetch data', - description: - "Signal that you may fetch data soon to improve latency. The type field selects what to prefetch ('brand' queues a brand data fetch, 'styleguide' queues a styleguide extraction) and identifier carries exactly one lookup key: a domain, or an email whose domain is extracted and validated (free email providers and disposable email addresses are not allowed).", - stainlessPath: '(resource) utility > (method) prefetch', - qualified: 'client.utility.prefetch', - params: [ - 'identifier: { domain: string; } | { email: string; };', - "type: 'brand' | 'styleguide';", - 'tags?: string[];', - 'timeoutMS?: number;', - ], - response: - "{ domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; message?: string; status?: string; type?: 'brand' | 'styleguide'; }", - markdown: - "## prefetch\n\n`client.utility.prefetch(identifier: { domain: string; } | { email: string; }, type: 'brand' | 'styleguide', tags?: string[], timeoutMS?: number): { domain?: string; key_metadata?: object; message?: string; status?: string; type?: 'brand' | 'styleguide'; }`\n\n**post** `/utility/prefetch`\n\nSignal that you may fetch data soon to improve latency. The type field selects what to prefetch ('brand' queues a brand data fetch, 'styleguide' queues a styleguide extraction) and identifier carries exactly one lookup key: a domain, or an email whose domain is extracted and validated (free email providers and disposable email addresses are not allowed).\n\n### Parameters\n\n- `identifier: { domain: string; } | { email: string; }`\n Identifier of the target to prefetch. Provide exactly one of domain or email.\n\n- `type: 'brand' | 'styleguide'`\n What to prefetch: 'brand' warms the brand data cache, 'styleguide' warms the styleguide cache.\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; message?: string; status?: string; type?: 'brand' | 'styleguide'; }`\n\n - `domain?: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `message?: string`\n - `status?: string`\n - `type?: 'brand' | 'styleguide'`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.utility.prefetch({\n identifier: { domain: 'xxx' },\n type: 'brand',\n});\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'utility->prefetch', - example: - "utility->prefetch(\n identifier: ['domain' => 'xxx'],\n type: 'brand',\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Utility.Prefetch', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Utility.Prefetch(context.TODO(), contextdev.UtilityPrefetchParams{\n\t\tIdentifier: contextdev.UtilityPrefetchParamsIdentifierUnion{\n\t\t\tOfByDomain: &contextdev.UtilityPrefetchParamsIdentifierByDomain{\n\t\t\t\tDomain: "xxx",\n\t\t\t},\n\t\t},\n\t\tType: contextdev.UtilityPrefetchParamsTypeBrand,\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Domain)\n}\n', - }, - cli: { - method: 'utility prefetch', - example: - "context-dev utility prefetch \\\n --api-key 'My API Key' \\\n --identifier '{domain: xxx}' \\\n --type brand", - }, - python: { - method: 'utility.prefetch', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.utility.prefetch(\n identifier={\n "domain": "xxx"\n },\n type="brand",\n)\nprint(response.domain)', - }, - ruby: { - method: 'utility.prefetch', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.utility.prefetch(identifier: {domain: "xxx"}, type: :brand)\n\nputs(response)', - }, - typescript: { - method: 'client.utility.prefetch', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.utility.prefetch({\n identifier: { domain: 'xxx' },\n type: 'brand',\n});\n\nconsole.log(response.domain);", - }, - http: { - example: - 'curl https://api.context.dev/v1/utility/prefetch \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "identifier": {\n "domain": "xxx"\n },\n "type": "brand",\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, - { - name: 'create', - endpoint: '/monitors', - httpMethod: 'post', - summary: 'Create a monitor', - description: - 'Creates a monitor. The request body is a union of the supported target/change detection combinations. The monitor runs immediately after creation to create its initial baseline.', - stainlessPath: '(resource) monitors > (method) create', - qualified: 'client.monitors.create', - params: [ - 'name: string;', - "target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; };", - "change_detection?: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; };", - "mode?: 'web';", - "schedule?: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; };", - 'tags?: string[];', - "webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; };", - ], - response: - "{ id: string; change_detection: object | object; created_at: string; initial_run_id: string; mode: 'web'; name: string; schedule: object; status: 'active' | 'paused' | 'failed'; target: object | object | object; updated_at: string; baseline?: object | object | object; last_change_at?: string; last_error?: object; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: object; webhook_failure?: object; }", - markdown: - "## create\n\n`client.monitors.create(name: string, target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }, change_detection?: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }, mode?: 'web', schedule?: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }, tags?: string[], webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }): { id: string; change_detection: object | object; created_at: string; initial_run_id: string; mode: 'web'; name: string; schedule: object; status: 'active' | 'paused' | 'failed'; target: object | object | object; updated_at: string; baseline?: object | object | object; last_change_at?: string; last_error?: object; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: object; webhook_failure?: object; }`\n\n**post** `/monitors`\n\nCreates a monitor. The request body is a union of the supported target/change detection combinations. The monitor runs immediately after creation to create its initial baseline.\n\n### Parameters\n\n- `name: string`\n\n- `target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }`\n Discriminated union describing what the monitor watches.\n\n- `change_detection?: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }`\n Discriminated union describing how changes are detected.\n\n- `mode?: 'web'`\n Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`.\n\n- `schedule?: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }`\n Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.\n - `frequency: number`\n Number of units between runs. The resulting interval (frequency × unit) must be at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; maximum 365 when unit is days).\n - `type: 'interval'`\n - `unit: 'minutes' | 'hours' | 'days'`\n\n- `tags?: string[]`\n User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.\n\n- `webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }`\n - `url: string`\n Webhook URL events are delivered to.\n - `events?: 'change.detected' | 'run.completed'[]`\n Events delivered to this endpoint. `change.detected` fires only when a run detects a change; `run.completed` fires on every completed run — including runs that detected no change — and embeds the change when one was detected. Defaults to `[\"change.detected\"]` when omitted.\n - `secret?: string`\n Signing secret used to verify webhook authenticity. Each delivery includes an `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over `\"{t}.{rawRequestBody}\"` keyed by this secret. Recompute it with a constant-time compare and reject stale timestamps to prevent replay. Generated by the API; cannot be set by clients.\n\n### Returns\n\n- `{ id: string; change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }; created_at: string; initial_run_id: string; mode: 'web'; name: string; schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }; status: 'active' | 'paused' | 'failed'; target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }; updated_at: string; baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }; last_change_at?: string; last_error?: { code: string; message: string; }; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }; webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }; }`\n A newly created monitor plus `initial_run_id`, the id of the baseline run queued at creation.\n\n - `id: string`\n - `change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }`\n - `created_at: string`\n - `initial_run_id: string`\n - `mode: 'web'`\n - `name: string`\n - `schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }`\n - `status: 'active' | 'paused' | 'failed'`\n - `target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }`\n - `updated_at: string`\n - `baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }`\n - `last_change_at?: string`\n - `last_error?: { code: string; message: string; }`\n - `last_run_at?: string`\n - `next_run_at?: string`\n - `tags?: string[]`\n - `webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }`\n - `webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst monitor = await client.monitors.create({\n name: 'Acme pricing page',\n target: { type: 'page', url: 'https://acme.com/pricing' },\n});\n\nconsole.log(monitor);\n```", - perLanguage: { - php: { - method: 'monitors->create', - example: - "monitors->create(\n name: 'Acme pricing page',\n target: [\n 'type' => 'page',\n 'url' => 'https://acme.com/pricing',\n 'instructions' => 'Report pricing or plan availability changes. Ignore counters, timestamps, testimonials, and navigation.',\n 'normalizeWhitespace' => true,\n ],\n changeDetection: ['type' => 'exact'],\n mode: 'web',\n schedule: ['frequency' => 6, 'type' => 'interval', 'unit' => 'hours'],\n tags: ['pricing', 'competitor'],\n webhook: [\n 'url' => 'https://example.com/webhook',\n 'events' => ['change.detected', 'run.completed'],\n ],\n);\n\nvar_dump($monitor);", - }, - go: { - method: 'client.Monitors.New', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tmonitor, err := client.Monitors.New(context.TODO(), contextdev.MonitorNewParams{\n\t\tName: "Acme pricing page",\n\t\tTarget: contextdev.MonitorNewParamsTargetUnion{\n\t\t\tOfPage: &contextdev.MonitorNewParamsTargetPage{\n\t\t\t\tURL: "https://acme.com/pricing",\n\t\t\t},\n\t\t},\n\t\tChangeDetection: contextdev.MonitorNewParamsChangeDetectionUnion{\n\t\t\tOfExact: &contextdev.MonitorNewParamsChangeDetectionExact{},\n\t\t},\n\t\tMode: contextdev.MonitorNewParamsModeWeb,\n\t\tSchedule: contextdev.MonitorNewParamsSchedule{\n\t\t\tType: "interval",\n\t\t\tFrequency: 6,\n\t\t\tUnit: "hours",\n\t\t},\n\t\tWebhook: contextdev.MonitorNewParamsWebhook{\n\t\t\tURL: "https://example.com/webhook",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", monitor.ID)\n}\n', - }, - cli: { - method: 'monitors create', - example: - "context-dev monitors create \\\n --api-key 'My API Key' \\\n --name 'Acme pricing page' \\\n --target '{type: page, url: https://acme.com/pricing}'", - }, - python: { - method: 'monitors.create', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nmonitor = client.monitors.create(\n name="Acme pricing page",\n target={\n "type": "page",\n "url": "https://acme.com/pricing",\n },\n change_detection={\n "type": "exact"\n },\n mode="web",\n schedule={\n "type": "interval",\n "frequency": 6,\n "unit": "hours",\n },\n webhook={\n "url": "https://example.com/webhook"\n },\n)\nprint(monitor.id)', - }, - ruby: { - method: 'monitors.create', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nmonitor = context_dev.monitors.create(\n name: "Acme pricing page",\n target: {type: :page, url: "https://acme.com/pricing"}\n)\n\nputs(monitor)', - }, - typescript: { - method: 'client.monitors.create', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst monitor = await client.monitors.create({\n name: 'Acme pricing page',\n target: { type: 'page', url: 'https://acme.com/pricing' },\n change_detection: { type: 'exact' },\n mode: 'web',\n schedule: {\n type: 'interval',\n frequency: 6,\n unit: 'hours',\n },\n webhook: { url: 'https://example.com/webhook' },\n});\n\nconsole.log(monitor.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "name": "Acme pricing page",\n "target": {\n "type": "page",\n "url": "https://acme.com/pricing"\n },\n "change_detection": {\n "type": "exact"\n },\n "mode": "web",\n "schedule": {\n "frequency": 6,\n "type": "interval",\n "unit": "hours"\n },\n "tags": [\n "pricing",\n "competitor"\n ],\n "webhook": {\n "url": "https://example.com/webhook"\n }\n }\'', - }, - }, - }, - { - name: 'list', - endpoint: '/monitors', - httpMethod: 'get', - summary: 'List monitors', - description: - 'Lists monitors for the authenticated organization. Supports free-text search (`q` over `search_by` fields, `prefix` or `exact` via `search_type`) plus status/type/tag filters. Results are paginated via the opaque `cursor`.', - stainlessPath: '(resource) monitors > (method) list', - qualified: 'client.monitors.list', - params: [ - "change_detection_type?: 'exact' | 'semantic';", - 'cursor?: string;', - 'limit?: number;', - 'q?: string;', - "search_by?: 'name' | 'url' | 'instructions' | 'tags'[];", - "search_type?: 'exact' | 'prefix';", - "status?: 'active' | 'paused' | 'failed';", - 'tag?: string;', - 'tags?: string[];', - "target_type?: 'page' | 'sitemap' | 'extract';", - ], - response: - "{ data: { id: string; change_detection: object | object; created_at: string; mode: 'web'; name: string; schedule: object; status: 'active' | 'paused' | 'failed'; target: object | object | object; updated_at: string; baseline?: object | object | object; last_change_at?: string; last_error?: object; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: object; webhook_failure?: object; }[]; has_more: boolean; next_cursor: string; }", - markdown: - "## list\n\n`client.monitors.list(change_detection_type?: 'exact' | 'semantic', cursor?: string, limit?: number, q?: string, search_by?: 'name' | 'url' | 'instructions' | 'tags'[], search_type?: 'exact' | 'prefix', status?: 'active' | 'paused' | 'failed', tag?: string, tags?: string[], target_type?: 'page' | 'sitemap' | 'extract'): { data: object[]; has_more: boolean; next_cursor: string; }`\n\n**get** `/monitors`\n\nLists monitors for the authenticated organization. Supports free-text search (`q` over `search_by` fields, `prefix` or `exact` via `search_type`) plus status/type/tag filters. Results are paginated via the opaque `cursor`.\n\n### Parameters\n\n- `change_detection_type?: 'exact' | 'semantic'`\n Filter by change detection type.\n\n- `cursor?: string`\n Opaque pagination cursor from a previous response.\n\n- `limit?: number`\n Maximum number of items to return per page (1-100). Defaults to 25.\n\n- `q?: string`\n Free-text search term, matched against the fields named in `search_by`.\n\n- `search_by?: 'name' | 'url' | 'instructions' | 'tags'[]`\n Comma-separated fields to search with `q`. Defaults to all of them. Note `instructions` only exists on extract monitors.\n\n- `search_type?: 'exact' | 'prefix'`\n `prefix` for as-you-type prefix matching (default), `exact` for full-token matching.\n\n- `status?: 'active' | 'paused' | 'failed'`\n Filter monitors by lifecycle status.\n\n- `tag?: string`\n Filter to items that have this tag.\n\n- `tags?: string[]`\n Comma-separated list of tags to filter by (matches monitors having any of them).\n\n- `target_type?: 'page' | 'sitemap' | 'extract'`\n Filter by target type.\n\n### Returns\n\n- `{ data: { id: string; change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }; created_at: string; mode: 'web'; name: string; schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }; status: 'active' | 'paused' | 'failed'; target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }; updated_at: string; baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }; last_change_at?: string; last_error?: { code: string; message: string; }; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }; webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }; }[]; has_more: boolean; next_cursor: string; }`\n\n - `data: { id: string; change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }; created_at: string; mode: 'web'; name: string; schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }; status: 'active' | 'paused' | 'failed'; target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }; updated_at: string; baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }; last_change_at?: string; last_error?: { code: string; message: string; }; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }; webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }; }[]`\n - `has_more: boolean`\n - `next_cursor: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst monitors = await client.monitors.list();\n\nconsole.log(monitors);\n```", - perLanguage: { - php: { - method: 'monitors->list', - example: - "monitors->list(\n changeDetectionType: 'exact',\n cursor: 'cursor',\n limit: 1,\n q: 'pricing',\n searchBy: ['name'],\n searchType: 'exact',\n status: 'active',\n tag: 'pricing',\n tags: ['x'],\n targetType: 'page',\n);\n\nvar_dump($monitors);", - }, - go: { - method: 'client.Monitors.List', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tmonitors, err := client.Monitors.List(context.TODO(), contextdev.MonitorListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", monitors.Data)\n}\n', - }, - cli: { - method: 'monitors list', - example: "context-dev monitors list \\\n --api-key 'My API Key'", - }, - python: { - method: 'monitors.list', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nmonitors = client.monitors.list()\nprint(monitors.data)', - }, - ruby: { - method: 'monitors.list', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nmonitors = context_dev.monitors.list\n\nputs(monitors)', - }, - typescript: { - method: 'client.monitors.list', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst monitors = await client.monitors.list();\n\nconsole.log(monitors.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'retrieve', - endpoint: '/monitors/{monitor_id}', - httpMethod: 'get', - summary: 'Get a monitor', - description: 'Get a monitor', - stainlessPath: '(resource) monitors > (method) retrieve', - qualified: 'client.monitors.retrieve', - params: ['monitor_id: string;'], - response: - "{ id: string; change_detection: object | object; created_at: string; mode: 'web'; name: string; schedule: object; status: 'active' | 'paused' | 'failed'; target: object | object | object; updated_at: string; baseline?: object | object | object; last_change_at?: string; last_error?: object; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: object; webhook_failure?: object; }", - markdown: - "## retrieve\n\n`client.monitors.retrieve(monitor_id: string): { id: string; change_detection: object | object; created_at: string; mode: 'web'; name: string; schedule: object; status: 'active' | 'paused' | 'failed'; target: object | object | object; updated_at: string; baseline?: object | object | object; last_change_at?: string; last_error?: object; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: object; webhook_failure?: object; }`\n\n**get** `/monitors/{monitor_id}`\n\nGet a monitor\n\n### Parameters\n\n- `monitor_id: string`\n\n### Returns\n\n- `{ id: string; change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }; created_at: string; mode: 'web'; name: string; schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }; status: 'active' | 'paused' | 'failed'; target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }; updated_at: string; baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }; last_change_at?: string; last_error?: { code: string; message: string; }; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }; webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }; }`\n A web monitor. `mode` is the constant `web`; behavior is described by `target` (page/sitemap/extract) and `change_detection` (exact/semantic).\n\n - `id: string`\n - `change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }`\n - `created_at: string`\n - `mode: 'web'`\n - `name: string`\n - `schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }`\n - `status: 'active' | 'paused' | 'failed'`\n - `target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }`\n - `updated_at: string`\n - `baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }`\n - `last_change_at?: string`\n - `last_error?: { code: string; message: string; }`\n - `last_run_at?: string`\n - `next_run_at?: string`\n - `tags?: string[]`\n - `webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }`\n - `webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst monitor = await client.monitors.retrieve('mon_123');\n\nconsole.log(monitor);\n```", - perLanguage: { - php: { - method: 'monitors->retrieve', - example: - "monitors->retrieve('mon_123');\n\nvar_dump($monitor);", - }, - go: { - method: 'client.Monitors.Get', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tmonitor, err := client.Monitors.Get(context.TODO(), "mon_123")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", monitor.ID)\n}\n', - }, - cli: { - method: 'monitors retrieve', - example: "context-dev monitors retrieve \\\n --api-key 'My API Key' \\\n --monitor-id mon_123", - }, - python: { - method: 'monitors.retrieve', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nmonitor = client.monitors.retrieve(\n "mon_123",\n)\nprint(monitor.id)', - }, - ruby: { - method: 'monitors.retrieve', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nmonitor = context_dev.monitors.retrieve("mon_123")\n\nputs(monitor)', - }, - typescript: { - method: 'client.monitors.retrieve', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst monitor = await client.monitors.retrieve('mon_123');\n\nconsole.log(monitor.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/$MONITOR_ID \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'update', - endpoint: '/monitors/{monitor_id}', - httpMethod: 'patch', - summary: 'Update a monitor', - description: - 'Updates a monitor. If `target` or `change_detection` changes, the monitor creates a new baseline. Unsupported target/change detection combinations are rejected.', - stainlessPath: '(resource) monitors > (method) update', - qualified: 'client.monitors.update', - params: [ - 'monitor_id: string;', - "change_detection?: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; };", - 'name?: string;', - "schedule?: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; };", - "status?: 'active' | 'paused';", - 'tags?: string[];', - "target?: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; };", - "webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; };", - ], - response: - "{ id: string; change_detection: object | object; created_at: string; mode: 'web'; name: string; schedule: object; status: 'active' | 'paused' | 'failed'; target: object | object | object; updated_at: string; baseline?: object | object | object; last_change_at?: string; last_error?: object; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: object; webhook_failure?: object; }", - markdown: - "## update\n\n`client.monitors.update(monitor_id: string, change_detection?: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }, name?: string, schedule?: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }, status?: 'active' | 'paused', tags?: string[], target?: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }, webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }): { id: string; change_detection: object | object; created_at: string; mode: 'web'; name: string; schedule: object; status: 'active' | 'paused' | 'failed'; target: object | object | object; updated_at: string; baseline?: object | object | object; last_change_at?: string; last_error?: object; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: object; webhook_failure?: object; }`\n\n**patch** `/monitors/{monitor_id}`\n\nUpdates a monitor. If `target` or `change_detection` changes, the monitor creates a new baseline. Unsupported target/change detection combinations are rejected.\n\n### Parameters\n\n- `monitor_id: string`\n\n- `change_detection?: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }`\n Discriminated union describing how changes are detected.\n\n- `name?: string`\n\n- `schedule?: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }`\n Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.\n - `frequency: number`\n Number of units between runs. The resulting interval (frequency × unit) must be at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; maximum 365 when unit is days).\n - `type: 'interval'`\n - `unit: 'minutes' | 'hours' | 'days'`\n\n- `status?: 'active' | 'paused'`\n\n- `tags?: string[]`\n User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.\n\n- `target?: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }`\n Discriminated union describing what the monitor watches.\n\n- `webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }`\n Set to null to remove the webhook.\n - `url: string`\n Webhook URL events are delivered to.\n - `events?: 'change.detected' | 'run.completed'[]`\n Events delivered to this endpoint. `change.detected` fires only when a run detects a change; `run.completed` fires on every completed run — including runs that detected no change — and embeds the change when one was detected. Defaults to `[\"change.detected\"]` when omitted.\n - `secret?: string`\n Signing secret used to verify webhook authenticity. Each delivery includes an `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over `\"{t}.{rawRequestBody}\"` keyed by this secret. Recompute it with a constant-time compare and reject stale timestamps to prevent replay. Generated by the API; cannot be set by clients.\n\n### Returns\n\n- `{ id: string; change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }; created_at: string; mode: 'web'; name: string; schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }; status: 'active' | 'paused' | 'failed'; target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }; updated_at: string; baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }; last_change_at?: string; last_error?: { code: string; message: string; }; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }; webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }; }`\n A web monitor. `mode` is the constant `web`; behavior is described by `target` (page/sitemap/extract) and `change_detection` (exact/semantic).\n\n - `id: string`\n - `change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }`\n - `created_at: string`\n - `mode: 'web'`\n - `name: string`\n - `schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }`\n - `status: 'active' | 'paused' | 'failed'`\n - `target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }`\n - `updated_at: string`\n - `baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }`\n - `last_change_at?: string`\n - `last_error?: { code: string; message: string; }`\n - `last_run_at?: string`\n - `next_run_at?: string`\n - `tags?: string[]`\n - `webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }`\n - `webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst monitor = await client.monitors.update('mon_123');\n\nconsole.log(monitor);\n```", - perLanguage: { - php: { - method: 'monitors->update', - example: - "monitors->update(\n 'mon_123',\n changeDetection: ['type' => 'exact'],\n name: 'Acme pricing monitor',\n schedule: ['frequency' => 1, 'type' => 'interval', 'unit' => 'hours'],\n status: 'active',\n tags: ['pricing', 'competitor'],\n target: [\n 'type' => 'page',\n 'url' => 'https://acme.com/pricing',\n 'instructions' => 'Report pricing or plan availability changes. Ignore counters, timestamps, testimonials, and navigation.',\n 'normalizeWhitespace' => true,\n ],\n webhook: [\n 'url' => 'https://example.com/webhook',\n 'events' => ['change.detected', 'run.completed'],\n ],\n);\n\nvar_dump($monitor);", - }, - go: { - method: 'client.Monitors.Update', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tmonitor, err := client.Monitors.Update(\n\t\tcontext.TODO(),\n\t\t"mon_123",\n\t\tcontextdev.MonitorUpdateParams{\n\t\t\tName: contextdev.String("Acme pricing monitor"),\n\t\t\tSchedule: contextdev.MonitorUpdateParamsSchedule{\n\t\t\t\tType: "interval",\n\t\t\t\tFrequency: 1,\n\t\t\t\tUnit: "hours",\n\t\t\t},\n\t\t\tStatus: contextdev.MonitorUpdateParamsStatusActive,\n\t\t\tWebhook: contextdev.MonitorUpdateParamsWebhook{\n\t\t\t\tURL: "https://example.com/webhook",\n\t\t\t},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", monitor.ID)\n}\n', - }, - cli: { - method: 'monitors update', - example: "context-dev monitors update \\\n --api-key 'My API Key' \\\n --monitor-id mon_123", - }, - python: { - method: 'monitors.update', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nmonitor = client.monitors.update(\n monitor_id="mon_123",\n name="Acme pricing monitor",\n schedule={\n "type": "interval",\n "frequency": 1,\n "unit": "hours",\n },\n status="active",\n webhook={\n "url": "https://example.com/webhook"\n },\n)\nprint(monitor.id)', - }, - ruby: { - method: 'monitors.update', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nmonitor = context_dev.monitors.update("mon_123")\n\nputs(monitor)', - }, - typescript: { - method: 'client.monitors.update', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst monitor = await client.monitors.update('mon_123', {\n name: 'Acme pricing monitor',\n schedule: {\n type: 'interval',\n frequency: 1,\n unit: 'hours',\n },\n status: 'active',\n webhook: { url: 'https://example.com/webhook' },\n});\n\nconsole.log(monitor.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/$MONITOR_ID \\\n -X PATCH \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "name": "Acme pricing monitor",\n "schedule": {\n "frequency": 1,\n "type": "interval",\n "unit": "hours"\n },\n "status": "active",\n "tags": [\n "pricing",\n "competitor"\n ],\n "webhook": {\n "url": "https://example.com/webhook"\n }\n }\'', - }, - }, - }, - { - name: 'delete', - endpoint: '/monitors/{monitor_id}', - httpMethod: 'delete', - summary: 'Delete a monitor', - description: 'Delete a monitor', - stainlessPath: '(resource) monitors > (method) delete', - qualified: 'client.monitors.delete', - params: ['monitor_id: string;'], - response: '{ id: string; deleted: boolean; }', - markdown: - "## delete\n\n`client.monitors.delete(monitor_id: string): { id: string; deleted: boolean; }`\n\n**delete** `/monitors/{monitor_id}`\n\nDelete a monitor\n\n### Parameters\n\n- `monitor_id: string`\n\n### Returns\n\n- `{ id: string; deleted: boolean; }`\n\n - `id: string`\n - `deleted: boolean`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst monitor = await client.monitors.delete('mon_123');\n\nconsole.log(monitor);\n```", - perLanguage: { - php: { - method: 'monitors->delete', - example: - "monitors->delete('mon_123');\n\nvar_dump($monitor);", - }, - go: { - method: 'client.Monitors.Delete', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tmonitor, err := client.Monitors.Delete(context.TODO(), "mon_123")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", monitor.ID)\n}\n', - }, - cli: { - method: 'monitors delete', - example: "context-dev monitors delete \\\n --api-key 'My API Key' \\\n --monitor-id mon_123", - }, - python: { - method: 'monitors.delete', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nmonitor = client.monitors.delete(\n "mon_123",\n)\nprint(monitor.id)', - }, - ruby: { - method: 'monitors.delete', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nmonitor = context_dev.monitors.delete("mon_123")\n\nputs(monitor)', - }, - typescript: { - method: 'client.monitors.delete', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst monitor = await client.monitors.delete('mon_123');\n\nconsole.log(monitor.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/$MONITOR_ID \\\n -X DELETE \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'run', - endpoint: '/monitors/{monitor_id}/run', - httpMethod: 'post', - summary: 'Run a monitor now', - description: - 'Triggers an immediate run of the monitor outside its normal schedule. The run is queued and processed asynchronously.', - stainlessPath: '(resource) monitors > (method) run', - qualified: 'client.monitors.run', - params: ['monitor_id: string;'], - response: '{ monitor_id: string; queued: boolean; run_id: string; }', - markdown: - "## run\n\n`client.monitors.run(monitor_id: string): { monitor_id: string; queued: boolean; run_id: string; }`\n\n**post** `/monitors/{monitor_id}/run`\n\nTriggers an immediate run of the monitor outside its normal schedule. The run is queued and processed asynchronously.\n\n### Parameters\n\n- `monitor_id: string`\n\n### Returns\n\n- `{ monitor_id: string; queued: boolean; run_id: string; }`\n\n - `monitor_id: string`\n - `queued: boolean`\n - `run_id: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.run('mon_123');\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->run', - example: - "monitors->run('mon_123');\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.Run', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.Run(context.TODO(), "mon_123")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.MonitorID)\n}\n', - }, - cli: { - method: 'monitors run', - example: "context-dev monitors run \\\n --api-key 'My API Key' \\\n --monitor-id mon_123", - }, - python: { - method: 'monitors.run', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.run(\n "mon_123",\n)\nprint(response.monitor_id)', - }, - ruby: { - method: 'monitors.run', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.run("mon_123")\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.run', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.run('mon_123');\n\nconsole.log(response.monitor_id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/$MONITOR_ID/run \\\n -X POST \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'list_runs', - endpoint: '/monitors/{monitor_id}/runs', - httpMethod: 'get', - summary: 'List monitor runs', - description: 'List monitor runs', - stainlessPath: '(resource) monitors > (method) list_runs', - qualified: 'client.monitors.listRuns', - params: [ - 'monitor_id: string;', - 'cursor?: string;', - 'limit?: number;', - "status?: 'queued' | 'running' | 'completed' | 'failed' | 'skipped';", - ], - response: - "{ data: { id: string; baseline_created: boolean; change_detected: boolean; change_detection_type: 'exact' | 'semantic'; credits_charged: number; monitor_id: string; run_type: 'baseline' | 'scheduled'; status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; target_type: 'page' | 'sitemap' | 'extract'; change_id?: string; completed_at?: string; error?: { code: string; message: string; }; skip_reason?: 'insufficient_credits' | 'monitor_paused' | 'superseded'; started_at?: string; webhook_deliveries?: object[]; webhook_delivery?: object; }[]; has_more: boolean; next_cursor: string; }", - markdown: - "## list_runs\n\n`client.monitors.listRuns(monitor_id: string, cursor?: string, limit?: number, status?: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'): { data: object[]; has_more: boolean; next_cursor: string; }`\n\n**get** `/monitors/{monitor_id}/runs`\n\nList monitor runs\n\n### Parameters\n\n- `monitor_id: string`\n\n- `cursor?: string`\n Opaque pagination cursor from a previous response.\n\n- `limit?: number`\n Maximum number of items to return per page (1-100). Defaults to 25.\n\n- `status?: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'`\n Filter runs by lifecycle status.\n\n### Returns\n\n- `{ data: { id: string; baseline_created: boolean; change_detected: boolean; change_detection_type: 'exact' | 'semantic'; credits_charged: number; monitor_id: string; run_type: 'baseline' | 'scheduled'; status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; target_type: 'page' | 'sitemap' | 'extract'; change_id?: string; completed_at?: string; error?: { code: string; message: string; }; skip_reason?: 'insufficient_credits' | 'monitor_paused' | 'superseded'; started_at?: string; webhook_deliveries?: object[]; webhook_delivery?: object; }[]; has_more: boolean; next_cursor: string; }`\n\n - `data: { id: string; baseline_created: boolean; change_detected: boolean; change_detection_type: 'exact' | 'semantic'; credits_charged: number; monitor_id: string; run_type: 'baseline' | 'scheduled'; status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; target_type: 'page' | 'sitemap' | 'extract'; change_id?: string; completed_at?: string; error?: { code: string; message: string; }; skip_reason?: 'insufficient_credits' | 'monitor_paused' | 'superseded'; started_at?: string; webhook_deliveries?: { attempted_at: string; error: { code: string; message: string; }; event: 'change.detected' | 'run.completed'; event_id: string; http_status: number; status: 'delivered' | 'rejected' | 'failed' | 'skipped_unsafe_url'; }[]; webhook_delivery?: { attempted_at: string; error: { code: string; message: string; }; event: 'change.detected' | 'run.completed'; event_id: string; http_status: number; status: 'delivered' | 'rejected' | 'failed' | 'skipped_unsafe_url'; }; }[]`\n - `has_more: boolean`\n - `next_cursor: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.listRuns('mon_123');\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->listRuns', - example: - "monitors->listRuns(\n 'mon_123', cursor: 'cursor', limit: 1, status: 'queued'\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.ListRuns', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.ListRuns(\n\t\tcontext.TODO(),\n\t\t"mon_123",\n\t\tcontextdev.MonitorListRunsParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Data)\n}\n', - }, - cli: { - method: 'monitors list_runs', - example: "context-dev monitors list-runs \\\n --api-key 'My API Key' \\\n --monitor-id mon_123", - }, - python: { - method: 'monitors.list_runs', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.list_runs(\n monitor_id="mon_123",\n)\nprint(response.data)', - }, - ruby: { - method: 'monitors.list_runs', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.list_runs("mon_123")\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.listRuns', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.listRuns('mon_123');\n\nconsole.log(response.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/$MONITOR_ID/runs \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'list_changes', - endpoint: '/monitors/{monitor_id}/changes', - httpMethod: 'get', - summary: 'List changes for a monitor', - description: 'List changes for a monitor', - stainlessPath: '(resource) monitors > (method) list_changes', - qualified: 'client.monitors.listChanges', - params: [ - 'monitor_id: string;', - 'cursor?: string;', - 'limit?: number;', - 'since?: string;', - 'tag?: string;', - 'until?: string;', - ], - response: - "{ data: { id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; summary: string; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; confidence?: number; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; removed_url_count?: number; tags?: string[]; }[]; has_more: boolean; next_cursor: string; }", - markdown: - "## list_changes\n\n`client.monitors.listChanges(monitor_id: string, cursor?: string, limit?: number, since?: string, tag?: string, until?: string): { data: object[]; has_more: boolean; next_cursor: string; }`\n\n**get** `/monitors/{monitor_id}/changes`\n\nList changes for a monitor\n\n### Parameters\n\n- `monitor_id: string`\n\n- `cursor?: string`\n Opaque pagination cursor from a previous response.\n\n- `limit?: number`\n Maximum number of items to return per page (1-100). Defaults to 25.\n\n- `since?: string`\n Only include items at or after this ISO 8601 timestamp.\n\n- `tag?: string`\n Filter to items that have this tag.\n\n- `until?: string`\n Only include items before this ISO 8601 timestamp.\n\n### Returns\n\n- `{ data: { id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; summary: string; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; confidence?: number; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; removed_url_count?: number; tags?: string[]; }[]; has_more: boolean; next_cursor: string; }`\n\n - `data: { id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; summary: string; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; confidence?: number; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; removed_url_count?: number; tags?: string[]; }[]`\n - `has_more: boolean`\n - `next_cursor: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.listChanges('mon_123');\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->listChanges', - example: - "monitors->listChanges(\n 'mon_123',\n cursor: 'cursor',\n limit: 1,\n since: new \\DateTimeImmutable('2026-06-01T00:00:00Z'),\n tag: 'pricing',\n until: new \\DateTimeImmutable('2026-06-28T00:00:00Z'),\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.ListChanges', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.ListChanges(\n\t\tcontext.TODO(),\n\t\t"mon_123",\n\t\tcontextdev.MonitorListChangesParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Data)\n}\n', - }, - cli: { - method: 'monitors list_changes', - example: "context-dev monitors list-changes \\\n --api-key 'My API Key' \\\n --monitor-id mon_123", - }, - python: { - method: 'monitors.list_changes', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.list_changes(\n monitor_id="mon_123",\n)\nprint(response.data)', - }, - ruby: { - method: 'monitors.list_changes', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.list_changes("mon_123")\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.listChanges', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.listChanges('mon_123');\n\nconsole.log(response.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/$MONITOR_ID/changes \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'list_account_runs', - endpoint: '/monitors/runs', - httpMethod: 'get', - summary: 'List runs', - description: 'Returns an account-wide feed of monitor runs across all monitors.', - stainlessPath: '(resource) monitors > (method) list_account_runs', - qualified: 'client.monitors.listAccountRuns', - params: [ - 'cursor?: string;', - 'limit?: number;', - "status?: 'queued' | 'running' | 'completed' | 'failed' | 'skipped';", - ], - response: - "{ data: { id: string; baseline_created: boolean; change_detected: boolean; change_detection_type: 'exact' | 'semantic'; credits_charged: number; monitor_id: string; run_type: 'baseline' | 'scheduled'; status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; target_type: 'page' | 'sitemap' | 'extract'; change_id?: string; completed_at?: string; error?: { code: string; message: string; }; skip_reason?: 'insufficient_credits' | 'monitor_paused' | 'superseded'; started_at?: string; webhook_deliveries?: object[]; webhook_delivery?: object; }[]; has_more: boolean; next_cursor: string; }", - markdown: - "## list_account_runs\n\n`client.monitors.listAccountRuns(cursor?: string, limit?: number, status?: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'): { data: object[]; has_more: boolean; next_cursor: string; }`\n\n**get** `/monitors/runs`\n\nReturns an account-wide feed of monitor runs across all monitors.\n\n### Parameters\n\n- `cursor?: string`\n Opaque pagination cursor from a previous response.\n\n- `limit?: number`\n Maximum number of items to return per page (1-100). Defaults to 25.\n\n- `status?: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'`\n Filter runs by lifecycle status.\n\n### Returns\n\n- `{ data: { id: string; baseline_created: boolean; change_detected: boolean; change_detection_type: 'exact' | 'semantic'; credits_charged: number; monitor_id: string; run_type: 'baseline' | 'scheduled'; status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; target_type: 'page' | 'sitemap' | 'extract'; change_id?: string; completed_at?: string; error?: { code: string; message: string; }; skip_reason?: 'insufficient_credits' | 'monitor_paused' | 'superseded'; started_at?: string; webhook_deliveries?: object[]; webhook_delivery?: object; }[]; has_more: boolean; next_cursor: string; }`\n\n - `data: { id: string; baseline_created: boolean; change_detected: boolean; change_detection_type: 'exact' | 'semantic'; credits_charged: number; monitor_id: string; run_type: 'baseline' | 'scheduled'; status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; target_type: 'page' | 'sitemap' | 'extract'; change_id?: string; completed_at?: string; error?: { code: string; message: string; }; skip_reason?: 'insufficient_credits' | 'monitor_paused' | 'superseded'; started_at?: string; webhook_deliveries?: { attempted_at: string; error: { code: string; message: string; }; event: 'change.detected' | 'run.completed'; event_id: string; http_status: number; status: 'delivered' | 'rejected' | 'failed' | 'skipped_unsafe_url'; }[]; webhook_delivery?: { attempted_at: string; error: { code: string; message: string; }; event: 'change.detected' | 'run.completed'; event_id: string; http_status: number; status: 'delivered' | 'rejected' | 'failed' | 'skipped_unsafe_url'; }; }[]`\n - `has_more: boolean`\n - `next_cursor: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.listAccountRuns();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->listAccountRuns', - example: - "monitors->listAccountRuns(\n cursor: 'cursor', limit: 1, status: 'queued'\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.ListAccountRuns', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.ListAccountRuns(context.TODO(), contextdev.MonitorListAccountRunsParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Data)\n}\n', - }, - cli: { - method: 'monitors list_account_runs', - example: "context-dev monitors list-account-runs \\\n --api-key 'My API Key'", - }, - python: { - method: 'monitors.list_account_runs', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.list_account_runs()\nprint(response.data)', - }, - ruby: { - method: 'monitors.list_account_runs', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.list_account_runs\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.listAccountRuns', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.listAccountRuns();\n\nconsole.log(response.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/runs \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'list_account_changes', - endpoint: '/monitors/changes', - httpMethod: 'get', - summary: 'List changes', - description: 'Returns an account-wide feed of detected changes across monitors.', - stainlessPath: '(resource) monitors > (method) list_account_changes', - qualified: 'client.monitors.listAccountChanges', - params: [ - "change_detection_type?: 'exact' | 'semantic';", - 'cursor?: string;', - 'limit?: number;', - 'monitor_id?: string;', - 'since?: string;', - 'tag?: string;', - "target_type?: 'page' | 'sitemap' | 'extract';", - 'until?: string;', - ], - response: - "{ data: { id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; summary: string; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; confidence?: number; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; removed_url_count?: number; tags?: string[]; }[]; has_more: boolean; next_cursor: string; }", - markdown: - "## list_account_changes\n\n`client.monitors.listAccountChanges(change_detection_type?: 'exact' | 'semantic', cursor?: string, limit?: number, monitor_id?: string, since?: string, tag?: string, target_type?: 'page' | 'sitemap' | 'extract', until?: string): { data: object[]; has_more: boolean; next_cursor: string; }`\n\n**get** `/monitors/changes`\n\nReturns an account-wide feed of detected changes across monitors.\n\n### Parameters\n\n- `change_detection_type?: 'exact' | 'semantic'`\n Filter by change detection type.\n\n- `cursor?: string`\n Opaque pagination cursor from a previous response.\n\n- `limit?: number`\n Maximum number of items to return per page (1-100). Defaults to 25.\n\n- `monitor_id?: string`\n Filter changes to a single monitor.\n\n- `since?: string`\n Only include items at or after this ISO 8601 timestamp.\n\n- `tag?: string`\n Filter to items that have this tag.\n\n- `target_type?: 'page' | 'sitemap' | 'extract'`\n Filter by target type.\n\n- `until?: string`\n Only include items before this ISO 8601 timestamp.\n\n### Returns\n\n- `{ data: { id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; summary: string; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; confidence?: number; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; removed_url_count?: number; tags?: string[]; }[]; has_more: boolean; next_cursor: string; }`\n\n - `data: { id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; summary: string; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; confidence?: number; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; removed_url_count?: number; tags?: string[]; }[]`\n - `has_more: boolean`\n - `next_cursor: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.listAccountChanges();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->listAccountChanges', - example: - "monitors->listAccountChanges(\n changeDetectionType: 'exact',\n cursor: 'cursor',\n limit: 1,\n monitorID: 'mon_123',\n since: new \\DateTimeImmutable('2026-06-01T00:00:00Z'),\n tag: 'pricing',\n targetType: 'page',\n until: new \\DateTimeImmutable('2026-06-28T00:00:00Z'),\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.ListAccountChanges', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.ListAccountChanges(context.TODO(), contextdev.MonitorListAccountChangesParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Data)\n}\n', - }, - cli: { - method: 'monitors list_account_changes', - example: "context-dev monitors list-account-changes \\\n --api-key 'My API Key'", - }, - python: { - method: 'monitors.list_account_changes', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.list_account_changes()\nprint(response.data)', - }, - ruby: { - method: 'monitors.list_account_changes', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.list_account_changes\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.listAccountChanges', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.listAccountChanges();\n\nconsole.log(response.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/changes \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'retrieve_change', - endpoint: '/monitors/changes/{change_id}', - httpMethod: 'get', - summary: 'Get a change', - description: 'Get a change', - stainlessPath: '(resource) monitors > (method) retrieve_change', - qualified: 'client.monitors.retrieveChange', - params: ['change_id: string;'], - response: - "{ id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; run_id: string; summary: string; tags: string[]; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; added_urls?: string[]; after_text_excerpt?: string; before_text_excerpt?: string; confidence?: number; diff?: string; evidence?: { after: string; before: string; url?: string; }[]; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; matched_urls?: string[]; removed_url_count?: number; removed_urls?: string[]; }", - markdown: - "## retrieve_change\n\n`client.monitors.retrieveChange(change_id: string): { id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; run_id: string; summary: string; tags: string[]; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; added_urls?: string[]; after_text_excerpt?: string; before_text_excerpt?: string; confidence?: number; diff?: string; evidence?: object[]; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; matched_urls?: string[]; removed_url_count?: number; removed_urls?: string[]; }`\n\n**get** `/monitors/changes/{change_id}`\n\nGet a change\n\n### Parameters\n\n- `change_id: string`\n\n### Returns\n\n- `{ id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; run_id: string; summary: string; tags: string[]; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; added_urls?: string[]; after_text_excerpt?: string; before_text_excerpt?: string; confidence?: number; diff?: string; evidence?: { after: string; before: string; url?: string; }[]; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; matched_urls?: string[]; removed_url_count?: number; removed_urls?: string[]; }`\n A detected change. `mode` is the constant `web`; `target_type` and `change_detection_type` describe the change, and which optional fields are present depends on them (page: `diff` + excerpts; sitemap: `added_urls`/`removed_urls`; semantic: `confidence`/`importance`/`evidence`/`matched_urls`).\n\n - `id: string`\n - `change_detection_type: 'exact' | 'semantic'`\n - `detected_at: string`\n - `mode: 'web'`\n - `monitor_id: string`\n - `run_id: string`\n - `summary: string`\n - `tags: string[]`\n - `target_type: 'page' | 'sitemap' | 'extract'`\n - `title: string`\n - `url: string`\n - `added_url_count?: number`\n - `added_urls?: string[]`\n - `after_text_excerpt?: string`\n - `before_text_excerpt?: string`\n - `confidence?: number`\n - `diff?: string`\n - `evidence?: { after: string; before: string; url?: string; }[]`\n - `importance?: 'low' | 'medium' | 'high'`\n - `matched_url_count?: number`\n - `matched_urls?: string[]`\n - `removed_url_count?: number`\n - `removed_urls?: string[]`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.retrieveChange('chg_123');\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->retrieveChange', - example: - "monitors->retrieveChange('chg_123');\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.GetChange', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.GetChange(context.TODO(), "chg_123")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.ID)\n}\n', - }, - cli: { - method: 'monitors retrieve_change', - example: - "context-dev monitors retrieve-change \\\n --api-key 'My API Key' \\\n --change-id chg_123", - }, - python: { - method: 'monitors.retrieve_change', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.retrieve_change(\n "chg_123",\n)\nprint(response.id)', - }, - ruby: { - method: 'monitors.retrieve_change', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.retrieve_change("chg_123")\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.retrieveChange', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.retrieveChange('chg_123');\n\nconsole.log(response.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/changes/$CHANGE_ID \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'get_credit_usage', - endpoint: '/monitors/credit-usage', - httpMethod: 'get', - summary: 'Monitor credit usage', - description: - 'Returns credits charged per monitor over an optional [since, until] window, newest spenders first.', - stainlessPath: '(resource) monitors > (method) get_credit_usage', - qualified: 'client.monitors.getCreditUsage', - params: ['since?: string;', 'until?: string;'], - response: - '{ data: { credits: number; monitor_id: string; name: string; runs: number; }[]; total_credits: number; }', - markdown: - "## get_credit_usage\n\n`client.monitors.getCreditUsage(since?: string, until?: string): { data: object[]; total_credits: number; }`\n\n**get** `/monitors/credit-usage`\n\nReturns credits charged per monitor over an optional [since, until] window, newest spenders first.\n\n### Parameters\n\n- `since?: string`\n Only include items at or after this ISO 8601 timestamp.\n\n- `until?: string`\n Only include items before this ISO 8601 timestamp.\n\n### Returns\n\n- `{ data: { credits: number; monitor_id: string; name: string; runs: number; }[]; total_credits: number; }`\n\n - `data: { credits: number; monitor_id: string; name: string; runs: number; }[]`\n - `total_credits: number`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.getCreditUsage();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->getCreditUsage', - example: - "monitors->getCreditUsage(\n since: new \\DateTimeImmutable('2026-06-01T00:00:00Z'),\n until: new \\DateTimeImmutable('2026-06-28T00:00:00Z'),\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.GetCreditUsage', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.GetCreditUsage(context.TODO(), contextdev.MonitorGetCreditUsageParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Data)\n}\n', - }, - cli: { - method: 'monitors get_credit_usage', - example: "context-dev monitors get-credit-usage \\\n --api-key 'My API Key'", - }, - python: { - method: 'monitors.get_credit_usage', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.get_credit_usage()\nprint(response.data)', - }, - ruby: { - method: 'monitors.get_credit_usage', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.get_credit_usage\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.getCreditUsage', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.getCreditUsage();\n\nconsole.log(response.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/credit-usage \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'get_limits', - endpoint: '/monitors/limits', - httpMethod: 'get', - summary: 'Monitor limits', - description: 'Returns how many monitors the account has and the maximum it allows.', - stainlessPath: '(resource) monitors > (method) get_limits', - qualified: 'client.monitors.getLimits', - response: - "{ monitors_limit: number; monitors_used: number; plan: 'free' | 'starter' | 'pro' | 'scale'; }", - markdown: - "## get_limits\n\n`client.monitors.getLimits(): { monitors_limit: number; monitors_used: number; plan: 'free' | 'starter' | 'pro' | 'scale'; }`\n\n**get** `/monitors/limits`\n\nReturns how many monitors the account has and the maximum it allows.\n\n### Returns\n\n- `{ monitors_limit: number; monitors_used: number; plan: 'free' | 'starter' | 'pro' | 'scale'; }`\n\n - `monitors_limit: number`\n - `monitors_used: number`\n - `plan: 'free' | 'starter' | 'pro' | 'scale'`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.getLimits();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->getLimits', - example: - "monitors->getLimits();\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.GetLimits', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.GetLimits(context.TODO())\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.MonitorsLimit)\n}\n', - }, - cli: { - method: 'monitors get_limits', - example: "context-dev monitors get-limits \\\n --api-key 'My API Key'", - }, - python: { - method: 'monitors.get_limits', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.get_limits()\nprint(response.monitors_limit)', - }, - ruby: { - method: 'monitors.get_limits', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.get_limits\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.getLimits', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.getLimits();\n\nconsole.log(response.monitors_limit);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/limits \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'submit', - endpoint: '/batch/submit', - httpMethod: 'post', - summary: 'Submit a batch', - description: 'Scrape 25K URLs or crawl large websites asynchronously. ', - stainlessPath: '(resource) batch > (method) submit', - qualified: 'client.batch.submit', - params: [ - "input: { data: { format: 'markdown'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeHTML?: boolean; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'scrape'; } | { data: { format: 'markdown'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeHTML?: boolean; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'crawl'; };", - 'tags?: string[];', - 'webhookUrl?: string;', - 'Idempotency-Key?: string;', - ], - response: - "{ id: string; cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: object | object; url_pattern: string; }; created_at: string; credits: { reserved: number; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; invalid_urls: { reason: string; url: string; }[]; mode: 'scrape' | 'crawl'; status: 'queued'; tags: string[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; webhook_secret?: string; }", - markdown: - "## submit\n\n`client.batch.submit(input: { data: { format: 'markdown'; urls: object[]; options?: object; } | { format: 'html'; urls: object[]; options?: object; }; mode: 'scrape'; } | { data: { format: 'markdown'; source: object | object; options?: object; } | { format: 'html'; source: object | object; options?: object; }; mode: 'crawl'; }, tags?: string[], webhookUrl?: string, Idempotency-Key?: string): { id: string; cache_metadata: object; crawl: crawl_controls; created_at: string; credits: object; format: 'markdown' | 'html'; input: intake; invalid_urls: object[]; mode: 'scrape' | 'crawl'; status: 'queued'; tags: string[]; key_metadata?: object; webhook_secret?: string; }`\n\n**post** `/batch/submit`\n\nScrape 25K URLs or crawl large websites asynchronously. \n\n### Parameters\n\n- `input: { data: { format: 'markdown'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeHTML?: boolean; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'scrape'; } | { data: { format: 'markdown'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeHTML?: boolean; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'crawl'; }`\n Choose a URL list or a site crawl.\n\n- `tags?: string[]`\n Tags stored on the batch. Filter the batch list by them later.\n\n- `webhookUrl?: string`\n URL notified when the batch finishes.\n\n- `Idempotency-Key?: string`\n Any string unique to this submission. Retries with the same key return the original batch.\n\n### Returns\n\n- `{ id: string; cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: object | object; url_pattern: string; }; created_at: string; credits: { reserved: number; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; invalid_urls: { reason: string; url: string; }[]; mode: 'scrape' | 'crawl'; status: 'queued'; tags: string[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; webhook_secret?: string; }`\n\n - `id: string`\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: { type: 'start_url'; url: string; } | { domain: string; type: 'sitemap'; }; url_pattern: string; }`\n - `created_at: string`\n - `credits: { reserved: number; }`\n - `format: 'markdown' | 'html'`\n - `input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }`\n - `invalid_urls: { reason: string; url: string; }[]`\n - `mode: 'scrape' | 'crawl'`\n - `status: 'queued'`\n - `tags: string[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `webhook_secret?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.batch.submit({ input: {\n data: { format: 'markdown', urls: [{ url: 'https://example.com/products/anvil' }, { url: 'https://example.com/products/hammer' }] },\n mode: 'scrape',\n} });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'batch->submit', - example: - "batch->submit(\n input: [\n 'data' => [\n 'format' => 'markdown',\n 'urls' => [\n [\n 'url' => 'https://example.com/products/anvil',\n 'itemID' => 'sku-1',\n 'meta' => ['category' => 'bar'],\n ],\n [\n 'url' => 'https://example.com/products/hammer',\n 'itemID' => 'sku-2',\n 'meta' => ['foo' => 'bar'],\n ],\n ],\n 'options' => [\n 'country' => 'de',\n 'excludeSelectors' => ['x'],\n 'includeHTML' => true,\n 'includeImages' => true,\n 'includeLinks' => true,\n 'includeSelectors' => ['x'],\n 'maxAgeMs' => 0,\n 'pdf' => [\n 'end' => 1, 'ocr' => true, 'shouldParse' => true, 'start' => 1\n ],\n 'settleAnimations' => true,\n 'shortenBase64Images' => true,\n 'useMainContentOnly' => true,\n 'waitForMs' => 0,\n ],\n ],\n 'mode' => 'scrape',\n ],\n tags: ['docs', 'competitor'],\n webhookURL: 'webhookUrl',\n idempotencyKey: 'Idempotency-Key',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Batch.Submit', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Batch.Submit(context.TODO(), contextdev.BatchSubmitParams{\n\t\tInput: contextdev.BatchSubmitParamsInputUnion{\n\t\t\tOfScrape: &contextdev.BatchSubmitParamsInputScrape{\n\t\t\t\tData: contextdev.BatchSubmitParamsInputScrapeDataUnion{\n\t\t\t\t\tOfMarkdown: &contextdev.BatchSubmitParamsInputScrapeDataMarkdown{\n\t\t\t\t\t\tURLs: []contextdev.BatchSubmitParamsInputScrapeDataMarkdownURL{{\n\t\t\t\t\t\t\tURL: "https://example.com/products/anvil",\n\t\t\t\t\t\t\tItemID: contextdev.String("sku-1"),\n\t\t\t\t\t\t\tMeta: map[string]any{\n\t\t\t\t\t\t\t\t"category": "tools",\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t}, {\n\t\t\t\t\t\t\tURL: "https://example.com/products/hammer",\n\t\t\t\t\t\t\tItemID: contextdev.String("sku-2"),\n\t\t\t\t\t\t}},\n\t\t\t\t\t\tOptions: contextdev.BatchSubmitParamsInputScrapeDataMarkdownOptions{\n\t\t\t\t\t\t\tUseMainContentOnly: contextdev.Bool(true),\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.ID)\n}\n', - }, - cli: { - method: 'batch submit', - example: - "context-dev batch submit \\\n --api-key 'My API Key' \\\n --input '{data: {format: markdown, urls: [{url: https://example.com/products/anvil}, {url: https://example.com/products/hammer}]}, mode: scrape}'", - }, - python: { - method: 'batch.submit', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.batch.submit(\n input={\n "data": {\n "urls": [{\n "url": "https://example.com/products/anvil",\n "item_id": "sku-1",\n "meta": {\n "category": "tools"\n },\n }, {\n "url": "https://example.com/products/hammer",\n "item_id": "sku-2",\n }],\n "options": {\n "use_main_content_only": True\n },\n }\n },\n)\nprint(response.id)', - }, - ruby: { - method: 'batch.submit', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.batch.submit(\n input: {\n data: {\n format: :markdown,\n urls: [{url: "https://example.com/products/anvil"}, {url: "https://example.com/products/hammer"}]\n },\n mode: :scrape\n }\n)\n\nputs(response)', - }, - typescript: { - method: 'client.batch.submit', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.batch.submit({\n input: {\n data: {\n urls: [\n {\n url: 'https://example.com/products/anvil',\n itemId: 'sku-1',\n meta: { category: 'tools' },\n },\n { url: 'https://example.com/products/hammer', itemId: 'sku-2' },\n ],\n options: { useMainContentOnly: true },\n },\n },\n});\n\nconsole.log(response.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/batch/submit \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "input": {\n "data": {\n "format": "markdown",\n "urls": [\n {\n "url": "https://example.com/products/anvil",\n "itemId": "sku-1",\n "meta": {\n "category": "bar"\n }\n },\n {\n "url": "https://example.com/products/hammer",\n "itemId": "sku-2"\n }\n ],\n "options": {\n "useMainContentOnly": true\n }\n },\n "mode": "scrape"\n },\n "tags": [\n "docs",\n "competitor"\n ]\n }\'', - }, - }, - }, - { - name: 'list', - endpoint: '/batch/list', - httpMethod: 'get', - summary: 'List batches', - description: 'List your batches from newest to oldest. Filter by status or continue with a cursor.', - stainlessPath: '(resource) batch > (method) list', - qualified: 'client.batch.list', - params: [ - 'cursor?: string;', - 'limit?: number;', - 'q?: string;', - "search_type?: 'exact' | 'prefix';", - "status?: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed';", - 'tags?: string;', - ], - response: - "{ data?: { id: string; crawl: object; credits: { net: number; ocr_charged: number; refunded: number; reserved: number; }; failure: object; format: 'markdown' | 'html'; input: object; mode: 'scrape' | 'crawl'; page_errors: object[]; progress: { failed: number; pending: number; succeeded: number; }; results: { expires_at: string; files: object[]; }; status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; tags: string[]; timing: { completed_at: string; created_at: string; started_at: string; }; }[]; has_more?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; next_cursor?: string; }", - markdown: - "## list\n\n`client.batch.list(cursor?: string, limit?: number, q?: string, search_type?: 'exact' | 'prefix', status?: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed', tags?: string): { data?: object[]; has_more?: boolean; key_metadata?: object; next_cursor?: string; }`\n\n**get** `/batch/list`\n\nList your batches from newest to oldest. Filter by status or continue with a cursor.\n\n### Parameters\n\n- `cursor?: string`\n Cursor from the previous page.\n\n- `limit?: number`\n Batches per page. Defaults to 25.\n\n- `q?: string`\n Free-text search term, matched against the batch id, crawl source (start URL or sitemap domain), and tags.\n\n- `search_type?: 'exact' | 'prefix'`\n `prefix` for as-you-type prefix matching (default), `exact` for full-token matching.\n\n- `status?: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'`\n Filter by status.\n\n- `tags?: string`\n Comma-separated list of tags to filter by (matches batches having any of them).\n\n### Returns\n\n- `{ data?: { id: string; crawl: object; credits: { net: number; ocr_charged: number; refunded: number; reserved: number; }; failure: object; format: 'markdown' | 'html'; input: object; mode: 'scrape' | 'crawl'; page_errors: object[]; progress: { failed: number; pending: number; succeeded: number; }; results: { expires_at: string; files: object[]; }; status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; tags: string[]; timing: { completed_at: string; created_at: string; started_at: string; }; }[]; has_more?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; next_cursor?: string; }`\n\n - `data?: { id: string; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: { type: 'start_url'; url: string; } | { domain: string; type: 'sitemap'; }; url_pattern: string; }; credits: { net: number; ocr_charged: number; refunded: number; reserved: number; }; failure: { code: string; message: string; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; mode: 'scrape' | 'crawl'; page_errors: { code: string; count: number; }[]; progress: { failed: number; pending: number; succeeded: number; }; results: { expires_at: string; files: { bytes: number; items: number; url: string; }[]; }; status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; tags: string[]; timing: { completed_at: string; created_at: string; started_at: string; }; }[]`\n - `has_more?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `next_cursor?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst batches = await client.batch.list();\n\nconsole.log(batches);\n```", - perLanguage: { - php: { - method: 'batch->list', - example: - "batch->list(\n cursor: 'cursor',\n limit: 1,\n q: 'batch_1a2b',\n searchType: 'exact',\n status: 'queued',\n tags: 'docs,competitor',\n);\n\nvar_dump($batches);", - }, - go: { - method: 'client.Batch.List', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tbatches, err := client.Batch.List(context.TODO(), contextdev.BatchListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", batches.Data)\n}\n', - }, - cli: { - method: 'batch list', - example: "context-dev batch list \\\n --api-key 'My API Key'", - }, - python: { - method: 'batch.list', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nbatches = client.batch.list()\nprint(batches.data)', - }, - ruby: { - method: 'batch.list', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nbatches = context_dev.batch.list\n\nputs(batches)', - }, - typescript: { - method: 'client.batch.list', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst batches = await client.batch.list();\n\nconsole.log(batches.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/batch/list \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'retrieve', - endpoint: '/batch/{batch_id}', - httpMethod: 'get', - summary: 'Get a batch', - description: 'Check progress, and get download links once the batch finishes.', - stainlessPath: '(resource) batch > (method) retrieve', - qualified: 'client.batch.retrieve', - params: ['batch_id: string;'], - response: - "{ id: string; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: object | object; url_pattern: string; }; credits: { net: number; ocr_charged: number; refunded: number; reserved: number; }; failure: { code: string; message: string; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; invalid_urls: { reason: string; url: string; }[]; mode: 'scrape' | 'crawl'; page_errors: { code: string; count: number; }[]; progress: { failed: number; pending: number; succeeded: number; }; results: { expires_at: string; files: { bytes: number; items: number; url: string; }[]; }; status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; tags: string[]; timing: { completed_at: string; created_at: string; started_at: string; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## retrieve\n\n`client.batch.retrieve(batch_id: string): { id: string; crawl: crawl_controls; credits: object; failure: failure; format: 'markdown' | 'html'; input: intake; invalid_urls: object[]; mode: 'scrape' | 'crawl'; page_errors: page_error_count[]; progress: object; results: object; status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; tags: string[]; timing: object; key_metadata?: object; }`\n\n**get** `/batch/{batch_id}`\n\nCheck progress, and get download links once the batch finishes.\n\n### Parameters\n\n- `batch_id: string`\n ID of the batch to retrieve or cancel.\n\n### Returns\n\n- `{ id: string; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: object | object; url_pattern: string; }; credits: { net: number; ocr_charged: number; refunded: number; reserved: number; }; failure: { code: string; message: string; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; invalid_urls: { reason: string; url: string; }[]; mode: 'scrape' | 'crawl'; page_errors: { code: string; count: number; }[]; progress: { failed: number; pending: number; succeeded: number; }; results: { expires_at: string; files: { bytes: number; items: number; url: string; }[]; }; status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; tags: string[]; timing: { completed_at: string; created_at: string; started_at: string; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `id: string`\n - `crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: { type: 'start_url'; url: string; } | { domain: string; type: 'sitemap'; }; url_pattern: string; }`\n - `credits: { net: number; ocr_charged: number; refunded: number; reserved: number; }`\n - `failure: { code: string; message: string; }`\n - `format: 'markdown' | 'html'`\n - `input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }`\n - `invalid_urls: { reason: string; url: string; }[]`\n - `mode: 'scrape' | 'crawl'`\n - `page_errors: { code: string; count: number; }[]`\n - `progress: { failed: number; pending: number; succeeded: number; }`\n - `results: { expires_at: string; files: { bytes: number; items: number; url: string; }[]; }`\n - `status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'`\n - `tags: string[]`\n - `timing: { completed_at: string; created_at: string; started_at: string; }`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst batch = await client.batch.retrieve('batch_9f2c8a');\n\nconsole.log(batch);\n```", - perLanguage: { - php: { - method: 'batch->retrieve', - example: - "batch->retrieve('batch_9f2c8a');\n\nvar_dump($batch);", - }, - go: { - method: 'client.Batch.Get', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tbatch, err := client.Batch.Get(context.TODO(), "batch_9f2c8a")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", batch.ID)\n}\n', - }, - cli: { - method: 'batch retrieve', - example: "context-dev batch retrieve \\\n --api-key 'My API Key' \\\n --batch-id batch_9f2c8a", - }, - python: { - method: 'batch.retrieve', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nbatch = client.batch.retrieve(\n "batch_9f2c8a",\n)\nprint(batch.id)', - }, - ruby: { - method: 'batch.retrieve', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nbatch = context_dev.batch.retrieve("batch_9f2c8a")\n\nputs(batch)', - }, - typescript: { - method: 'client.batch.retrieve', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst batch = await client.batch.retrieve('batch_9f2c8a');\n\nconsole.log(batch.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/batch/$BATCH_ID \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'get_results', - endpoint: '/batch/{batch_id}/results', - httpMethod: 'get', - summary: 'Get batch results', - description: "Page through a finished batch's results as JSON instead of downloading the NDJSON files.", - stainlessPath: '(resource) batch > (method) get_results', - qualified: 'client.batch.getResults', - params: ['batch_id: string;', 'cursor?: string;', 'limit?: number;'], - response: - "{ data?: { cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; final_url: string; http_status: number; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: object[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; status: 'ok'; url: string; html?: string; itemId?: string; markdown?: string; meta?: object; ocr_pages?: number; } | { error_code: string; message: string; status: 'error'; url: string; itemId?: string; meta?: object; }[]; has_more?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; next_cursor?: string; }", - markdown: - "## get_results\n\n`client.batch.getResults(batch_id: string, cursor?: string, limit?: number): { data?: object | object[]; has_more?: boolean; key_metadata?: object; next_cursor?: string; }`\n\n**get** `/batch/{batch_id}/results`\n\nPage through a finished batch's results as JSON instead of downloading the NDJSON files.\n\n### Parameters\n\n- `batch_id: string`\n ID of the batch to retrieve or cancel.\n\n- `cursor?: string`\n next_cursor from the previous page.\n\n- `limit?: number`\n Records per page. Defaults to 25. A page can close early so its payload stays under ~8 MB; rely on next_cursor rather than counting records.\n\n### Returns\n\n- `{ data?: { cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; final_url: string; http_status: number; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: object[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; status: 'ok'; url: string; html?: string; itemId?: string; markdown?: string; meta?: object; ocr_pages?: number; } | { error_code: string; message: string; status: 'error'; url: string; itemId?: string; meta?: object; }[]; has_more?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; next_cursor?: string; }`\n\n - `data?: { cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; final_url: string; http_status: number; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; status: 'ok'; url: string; html?: string; itemId?: string; markdown?: string; meta?: object; ocr_pages?: number; } | { error_code: string; message: string; status: 'error'; url: string; itemId?: string; meta?: object; }[]`\n - `has_more?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `next_cursor?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.batch.getResults('batch_9f2c8a');\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'batch->getResults', - example: - "batch->getResults(\n 'batch_9f2c8a', cursor: 'cursor', limit: 1\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Batch.GetResults', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Batch.GetResults(\n\t\tcontext.TODO(),\n\t\t"batch_9f2c8a",\n\t\tcontextdev.BatchGetResultsParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Data)\n}\n', - }, - cli: { - method: 'batch get_results', - example: "context-dev batch get-results \\\n --api-key 'My API Key' \\\n --batch-id batch_9f2c8a", - }, - python: { - method: 'batch.get_results', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.batch.get_results(\n batch_id="batch_9f2c8a",\n)\nprint(response.data)', - }, - ruby: { - method: 'batch.get_results', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.batch.get_results("batch_9f2c8a")\n\nputs(response)', - }, - typescript: { - method: 'client.batch.getResults', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.batch.getResults('batch_9f2c8a');\n\nconsole.log(response.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/batch/$BATCH_ID/results \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'cancel', - endpoint: '/batch/{batch_id}/cancel', - httpMethod: 'post', - summary: 'Cancel a batch', - description: - 'Stop a batch from starting new pages. In-progress pages finish, and unused credits are refunded.', - stainlessPath: '(resource) batch > (method) cancel', - qualified: 'client.batch.cancel', - params: ['batch_id: string;'], - response: - "{ id: string; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: object | object; url_pattern: string; }; credits: { reserved: number; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; mode: 'scrape' | 'crawl'; page_errors: { code: string; count: number; }[]; progress: { failed: number; pending: number; succeeded: number; }; status: 'cancelling'; tags: string[]; timing: { created_at: string; started_at: string; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## cancel\n\n`client.batch.cancel(batch_id: string): { id: string; crawl: crawl_controls; credits: object; format: 'markdown' | 'html'; input: intake; mode: 'scrape' | 'crawl'; page_errors: page_error_count[]; progress: object; status: 'cancelling'; tags: string[]; timing: object; key_metadata?: object; }`\n\n**post** `/batch/{batch_id}/cancel`\n\nStop a batch from starting new pages. In-progress pages finish, and unused credits are refunded.\n\n### Parameters\n\n- `batch_id: string`\n ID of the batch to retrieve or cancel.\n\n### Returns\n\n- `{ id: string; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: object | object; url_pattern: string; }; credits: { reserved: number; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; mode: 'scrape' | 'crawl'; page_errors: { code: string; count: number; }[]; progress: { failed: number; pending: number; succeeded: number; }; status: 'cancelling'; tags: string[]; timing: { created_at: string; started_at: string; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `id: string`\n - `crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: { type: 'start_url'; url: string; } | { domain: string; type: 'sitemap'; }; url_pattern: string; }`\n - `credits: { reserved: number; }`\n - `format: 'markdown' | 'html'`\n - `input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }`\n - `mode: 'scrape' | 'crawl'`\n - `page_errors: { code: string; count: number; }[]`\n - `progress: { failed: number; pending: number; succeeded: number; }`\n - `status: 'cancelling'`\n - `tags: string[]`\n - `timing: { created_at: string; started_at: string; }`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.batch.cancel('batch_9f2c8a');\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'batch->cancel', - example: - "batch->cancel('batch_9f2c8a');\n\nvar_dump($response);", - }, - go: { - method: 'client.Batch.Cancel', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Batch.Cancel(context.TODO(), "batch_9f2c8a")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.ID)\n}\n', - }, - cli: { - method: 'batch cancel', - example: "context-dev batch cancel \\\n --api-key 'My API Key' \\\n --batch-id batch_9f2c8a", - }, - python: { - method: 'batch.cancel', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.batch.cancel(\n "batch_9f2c8a",\n)\nprint(response.id)', - }, - ruby: { - method: 'batch.cancel', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.batch.cancel("batch_9f2c8a")\n\nputs(response)', - }, - typescript: { - method: 'client.batch.cancel', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.batch.cancel('batch_9f2c8a');\n\nconsole.log(response.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/batch/$BATCH_ID/cancel \\\n -X POST \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'delete', - endpoint: '/batch/{batch_id}', - httpMethod: 'delete', - summary: 'Delete a batch', - description: - 'Permanently delete a finished batch and its stored results. Active batches must settle first.', - stainlessPath: '(resource) batch > (method) delete', - qualified: 'client.batch.delete', - params: ['batch_id: string;'], - response: - '{ id?: string; deleted?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }', - markdown: - "## delete\n\n`client.batch.delete(batch_id: string): { id?: string; deleted?: boolean; key_metadata?: object; }`\n\n**delete** `/batch/{batch_id}`\n\nPermanently delete a finished batch and its stored results. Active batches must settle first.\n\n### Parameters\n\n- `batch_id: string`\n ID of the batch to retrieve or cancel.\n\n### Returns\n\n- `{ id?: string; deleted?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `id?: string`\n - `deleted?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst batch = await client.batch.delete('batch_9f2c8a');\n\nconsole.log(batch);\n```", - perLanguage: { - php: { - method: 'batch->delete', - example: - "batch->delete('batch_9f2c8a');\n\nvar_dump($batch);", - }, - go: { - method: 'client.Batch.Delete', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tbatch, err := client.Batch.Delete(context.TODO(), "batch_9f2c8a")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", batch.ID)\n}\n', - }, - cli: { - method: 'batch delete', - example: "context-dev batch delete \\\n --api-key 'My API Key' \\\n --batch-id batch_9f2c8a", - }, - python: { - method: 'batch.delete', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nbatch = client.batch.delete(\n "batch_9f2c8a",\n)\nprint(batch.id)', - }, - ruby: { - method: 'batch.delete', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nbatch = context_dev.batch.delete("batch_9f2c8a")\n\nputs(batch)', - }, - typescript: { - method: 'client.batch.delete', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst batch = await client.batch.delete('batch_9f2c8a');\n\nconsole.log(batch.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/batch/$BATCH_ID \\\n -X DELETE \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'enrich', - endpoint: '/people/enrich', - httpMethod: 'post', - summary: 'Enrich Person', - description: - 'Finds and normalizes the best available person candidate from additive identity clues, then assigns an identity match score from 0 to 100. Available on all paid plans. Successful requests cost 20 credits. Disposable and free email addresses (like gmail.com, yahoo.com) will throw a 422 error.', - stainlessPath: '(resource) people > (method) enrich', - qualified: 'client.people.enrich', - params: [ - 'company?: { domain?: string; name?: string; };', - 'education?: { degree?: string; field_of_study?: string; graduation_year?: number; institution?: { domain?: string; name?: string; }; }[];', - 'email?: string;', - 'location?: { city?: string; country?: string; region?: string; };', - 'name?: { first?: string; last?: string; };', - 'social_urls?: string[];', - 'tags?: string[];', - 'timeoutMS?: number;', - ], - response: - "{ match: { person: { current_role_status: 'present' | 'none' | 'unknown'; education: object[]; experience: object[]; skills: string[]; social_urls: string[]; website_urls: string[]; avatar_url?: string; bio?: string; checked_at?: string; current_role?: object; email?: string; last_updated?: string; location?: object; name?: object; }; score: number; status: 'candidate'; } | { person: null; score: null; status: 'not_found'; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## enrich\n\n`client.people.enrich(company?: { domain?: string; name?: string; }, education?: { degree?: string; field_of_study?: string; graduation_year?: number; institution?: { domain?: string; name?: string; }; }[], email?: string, location?: { city?: string; country?: string; region?: string; }, name?: { first?: string; last?: string; }, social_urls?: string[], tags?: string[], timeoutMS?: number): { match: object | object; key_metadata?: object; }`\n\n**post** `/people/enrich`\n\nFinds and normalizes the best available person candidate from additive identity clues, then assigns an identity match score from 0 to 100. Available on all paid plans. Successful requests cost 20 credits. Disposable and free email addresses (like gmail.com, yahoo.com) will throw a 422 error.\n\n### Parameters\n\n- `company?: { domain?: string; name?: string; }`\n - `domain?: string`\n - `name?: string`\n\n- `education?: { degree?: string; field_of_study?: string; graduation_year?: number; institution?: { domain?: string; name?: string; }; }[]`\n\n- `email?: string`\n\n- `location?: { city?: string; country?: string; region?: string; }`\n - `city?: string`\n - `country?: string`\n - `region?: string`\n\n- `name?: { first?: string; last?: string; }`\n - `first?: string`\n - `last?: string`\n\n- `social_urls?: string[]`\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ match: { person: { current_role_status: 'present' | 'none' | 'unknown'; education: object[]; experience: object[]; skills: string[]; social_urls: string[]; website_urls: string[]; avatar_url?: string; bio?: string; checked_at?: string; current_role?: object; email?: string; last_updated?: string; location?: object; name?: object; }; score: number; status: 'candidate'; } | { person: null; score: null; status: 'not_found'; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `match: { person: { current_role_status: 'present' | 'none' | 'unknown'; education: { institution: { name: string; domain?: string; }; degree?: string; description?: string; end_date?: { year: number; day?: number; month?: number; }; field_of_study?: string; start_date?: { year: number; day?: number; month?: number; }; }[]; experience: { organization: { name: string; domain?: string; }; title: string; description?: string; end_date?: { year: number; day?: number; month?: number; }; is_current?: boolean; location?: string; start_date?: { year: number; day?: number; month?: number; }; }[]; skills: string[]; social_urls: string[]; website_urls: string[]; avatar_url?: string; bio?: string; checked_at?: string; current_role?: { organization: { name: string; domain?: string; }; title: string; description?: string; end_date?: { year: number; day?: number; month?: number; }; is_current?: boolean; location?: string; start_date?: { year: number; day?: number; month?: number; }; }; email?: string; last_updated?: string; location?: { city?: string; country?: string; country_code?: string; display?: string; region?: string; }; name?: { first?: string; full?: string; last?: string; }; }; score: number; status: 'candidate'; } | { person: null; score: null; status: 'not_found'; }`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.people.enrich();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'people->enrich', - example: - "people->enrich(\n company: [\n 'domain' => 'analyticalengines.example', 'name' => 'Analytical Engines'\n ],\n education: [\n [\n 'degree' => 'x',\n 'fieldOfStudy' => 'x',\n 'graduationYear' => 1900,\n 'institution' => ['domain' => 'x', 'name' => 'x'],\n ],\n ],\n email: 'dev@stainless.com',\n location: ['city' => 'x', 'country' => 'x', 'region' => 'x'],\n name: ['first' => 'Ada', 'last' => 'Lovelace'],\n socialURLs: ['https://www.linkedin.com/in/ada-lovelace/'],\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.People.Enrich', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.People.Enrich(context.TODO(), contextdev.PersonEnrichParams{\n\t\tCompany: contextdev.PersonEnrichParamsCompany{\n\t\t\tName: contextdev.String("Analytical Engines"),\n\t\t\tDomain: contextdev.String("analyticalengines.example"),\n\t\t},\n\t\tName: contextdev.PersonEnrichParamsName{\n\t\t\tFirst: contextdev.String("Ada"),\n\t\t\tLast: contextdev.String("Lovelace"),\n\t\t},\n\t\tSocialURLs: []string{"https://www.linkedin.com/in/ada-lovelace/"},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Match)\n}\n', - }, - cli: { - method: 'people enrich', - example: "context-dev people enrich \\\n --api-key 'My API Key'", - }, - python: { - method: 'people.enrich', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.people.enrich(\n company={\n "name": "Analytical Engines",\n "domain": "analyticalengines.example",\n },\n name={\n "first": "Ada",\n "last": "Lovelace",\n },\n social_urls=["https://www.linkedin.com/in/ada-lovelace/"],\n)\nprint(response.match)', - }, - ruby: { - method: 'people.enrich', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.people.enrich\n\nputs(response)', - }, - typescript: { - method: 'client.people.enrich', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.people.enrich({\n company: { name: 'Analytical Engines', domain: 'analyticalengines.example' },\n name: { first: 'Ada', last: 'Lovelace' },\n social_urls: ['https://www.linkedin.com/in/ada-lovelace/'],\n});\n\nconsole.log(response.match);", - }, - http: { - example: - 'curl https://api.context.dev/v1/people/enrich \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "company": {\n "domain": "analyticalengines.example",\n "name": "Analytical Engines"\n },\n "name": {\n "first": "Ada",\n "last": "Lovelace"\n },\n "social_urls": [\n "https://www.linkedin.com/in/ada-lovelace/"\n ],\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, - { - name: 'search', - endpoint: '/news/search', - httpMethod: 'post', - summary: 'Search company news', - description: - 'Searches live and historical company news for one company, identified in searchBy by name, domain, ticker (optionally disambiguated by exchange), or ISIN. Results can be filtered by publisher domain, publisher country, article language, article type, and published-at date, and include stable story IDs, source metadata, verified entity relevance, and cursor pagination.', - stainlessPath: '(resource) news > (method) search', - qualified: 'client.news.search', - params: [ - "searchBy: { entity: { name: string; type: 'name'; } | { domain: string; type: 'domain'; } | { ticker: string; type: 'ticker'; exchange?: string; } | { isin: string; type: 'isin'; }; type: 'entity'; };", - 'cursor?: string;', - "filterBy?: { articleLanguage?: 'ar' | 'de' | 'en' | 'es' | 'fr' | 'hi' | 'it' | 'ja' | 'ko' | 'nl' | 'pt' | 'ru' | 'zh'[]; articleType?: 'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'[]; date?: { from?: number; to?: number; }; sourceCountry?: string[]; sourceDomain?: string[]; };", - 'limit?: number;', - "sortBy?: { type: 'relevance' | 'newest'; };", - 'tags?: string[];', - ], - response: - "{ data: { id: string; authors: string[]; description: string; image_url: string; language: string; match: { confidence: number; level: 'primary' | 'secondary'; }; published_at: string; source: { direct: boolean; domain: string; name: string; }; story_id: string; title: string; type: 'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'; url: string; }[]; has_more: boolean; meta: { count: number; }; next_cursor: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## search\n\n`client.news.search(searchBy: { entity: { name: string; type: 'name'; } | { domain: string; type: 'domain'; } | { ticker: string; type: 'ticker'; exchange?: string; } | { isin: string; type: 'isin'; }; type: 'entity'; }, cursor?: string, filterBy?: { articleLanguage?: 'ar' | 'de' | 'en' | 'es' | 'fr' | 'hi' | 'it' | 'ja' | 'ko' | 'nl' | 'pt' | 'ru' | 'zh'[]; articleType?: 'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'[]; date?: { from?: number; to?: number; }; sourceCountry?: string[]; sourceDomain?: string[]; }, limit?: number, sortBy?: { type: 'relevance' | 'newest'; }, tags?: string[]): { data: object[]; has_more: boolean; meta: object; next_cursor: string; key_metadata?: object; }`\n\n**post** `/news/search`\n\nSearches live and historical company news for one company, identified in searchBy by name, domain, ticker (optionally disambiguated by exchange), or ISIN. Results can be filtered by publisher domain, publisher country, article language, article type, and published-at date, and include stable story IDs, source metadata, verified entity relevance, and cursor pagination.\n\n### Parameters\n\n- `searchBy: { entity: { name: string; type: 'name'; } | { domain: string; type: 'domain'; } | { ticker: string; type: 'ticker'; exchange?: string; } | { isin: string; type: 'isin'; }; type: 'entity'; }`\n What to search for.\n - `entity: { name: string; type: 'name'; } | { domain: string; type: 'domain'; } | { ticker: string; type: 'ticker'; exchange?: string; } | { isin: string; type: 'isin'; }`\n The company to search news for, identified by name, domain, ticker, or ISIN.\n - `type: 'entity'`\n How to search. Only entity search is supported.\n\n- `cursor?: string`\n Opaque next_cursor from the previous response, or null for the first page.\n\n- `filterBy?: { articleLanguage?: 'ar' | 'de' | 'en' | 'es' | 'fr' | 'hi' | 'it' | 'ja' | 'ko' | 'nl' | 'pt' | 'ru' | 'zh'[]; articleType?: 'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'[]; date?: { from?: number; to?: number; }; sourceCountry?: string[]; sourceDomain?: string[]; }`\n Optional result filters.\n - `articleLanguage?: 'ar' | 'de' | 'en' | 'es' | 'fr' | 'hi' | 'it' | 'ja' | 'ko' | 'nl' | 'pt' | 'ru' | 'zh'[]`\n Article languages to include. Up to 3.\n - `articleType?: 'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'[]`\n Article types to include. Up to 3.\n - `date?: { from?: number; to?: number; }`\n Published-at window in epoch milliseconds.\n - `sourceCountry?: string[]`\n Publisher countries to include, as lowercase ISO 3166-1 alpha-2 codes. Up to 3.\n - `sourceDomain?: string[]`\n Publisher domains to include. Up to 3.\n\n- `limit?: number`\n Maximum results to return. Defaults to 10.\n\n- `sortBy?: { type: 'relevance' | 'newest'; }`\n Result ordering. Defaults to newest.\n - `type: 'relevance' | 'newest'`\n Result ordering.\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n### Returns\n\n- `{ data: { id: string; authors: string[]; description: string; image_url: string; language: string; match: { confidence: number; level: 'primary' | 'secondary'; }; published_at: string; source: { direct: boolean; domain: string; name: string; }; story_id: string; title: string; type: 'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'; url: string; }[]; has_more: boolean; meta: { count: number; }; next_cursor: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `data: { id: string; authors: string[]; description: string; image_url: string; language: string; match: { confidence: number; level: 'primary' | 'secondary'; }; published_at: string; source: { direct: boolean; domain: string; name: string; }; story_id: string; title: string; type: 'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'; url: string; }[]`\n - `has_more: boolean`\n - `meta: { count: number; }`\n - `next_cursor: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.news.search({ searchBy: {\n entity: { name: 'xx', type: 'name' },\n type: 'entity',\n} });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'news->search', - example: - "news->search(\n searchBy: [\n 'entity' => ['name' => 'xx', 'type' => 'name'], 'type' => 'entity'\n ],\n cursor: 'cursor',\n filterBy: [\n 'articleLanguage' => ['ar'],\n 'articleType' => ['editorial'],\n 'date' => ['from' => 0, 'to' => 0],\n 'sourceCountry' => ['ae'],\n 'sourceDomain' => ['x'],\n ],\n limit: 1,\n sortBy: ['type' => 'relevance'],\n tags: ['production', 'team-alpha'],\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.News.Search', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.News.Search(context.TODO(), contextdev.NewsSearchParams{\n\t\tSearchBy: contextdev.NewsSearchParamsSearchBy{\n\t\t\tEntity: contextdev.NewsSearchParamsSearchByEntityUnion{\n\t\t\t\tOfName: &contextdev.NewsSearchParamsSearchByEntityName{\n\t\t\t\t\tName: "xx",\n\t\t\t\t},\n\t\t\t},\n\t\t\tType: "entity",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Data)\n}\n', - }, - cli: { - method: 'news search', - example: - "context-dev news search \\\n --api-key 'My API Key' \\\n --search-by '{entity: {name: xx, type: name}, type: entity}'", - }, - python: { - method: 'news.search', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.news.search(\n search_by={\n "entity": {\n "name": "xx",\n "type": "name",\n },\n "type": "entity",\n },\n)\nprint(response.data)', - }, - ruby: { - method: 'news.search', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.news.search(search_by: {entity: {name: "xx", type: :name}, type: :entity})\n\nputs(response)', - }, - typescript: { - method: 'client.news.search', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.news.search({\n searchBy: {\n entity: { name: 'xx', type: 'name' },\n type: 'entity',\n },\n});\n\nconsole.log(response.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/news/search \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "searchBy": {\n "entity": {\n "name": "xx",\n "type": "name"\n },\n "type": "entity"\n },\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, -]; - -const EMBEDDED_READMES: { language: string; content: string }[] = [ - { - language: 'php', - content: - "# Context Dev PHP API Library\n\nThe Context Dev PHP library provides convenient access to the Context Dev REST API from any PHP 8.1.0+ application.\n\n## Installation\n\n\n```\ncomposer require \"context-dev/context-dev-php 2.13.0\"\n```\n\n\n## Usage\n\n```php\nbrand->retrieve(domain: 'REPLACE_ME', type: 'by_domain');\n\nvar_dump($brand->cache_metadata);\n```", - }, - { - language: 'go', - content: - '# Context Dev Go API Library\n\nGo Reference\n\nThe Context Dev Go library provides convenient access to the [Context Dev REST API](https://docs.context.dev/)\nfrom applications written in Go.\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n## MCP Server\n\nUse the Context Dev MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0)\n[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D)\n\n> Note: You may need to set environment variables in your MCP client.\n\n## Installation\n\n\n\n```go\nimport (\n\t"github.com/context-dot-dev/context-go-sdk/v2" // imported as SDK_PackageName\n)\n```\n\n\n\nOr to pin the version:\n\n\n\n```sh\ngo get -u \'github.com/context-dot-dev/context-go-sdk/v2@v2.13.0\'\n```\n\n\n\n## Requirements\n\nThis library requires Go 1.22+.\n\n## Usage\n\nThe full API of this library can be found in [api.md](api.md).\n\n```go\npackage main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"), // defaults to os.LookupEnv("CONTEXT_DEV_API_KEY")\n\t)\n\tbrand, err := client.Brand.Get(context.TODO(), contextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", brand.CacheMetadata)\n}\n\n```\n\n### Request fields\n\nAll request parameters are wrapped in a generic `Field` type,\nwhich we use to distinguish zero values from null or omitted fields.\n\nThis prevents accidentally sending a zero value if you forget a required parameter,\nand enables explicitly sending `null`, `false`, `\'\'`, or `0` on optional parameters.\nAny field not specified is not sent.\n\nTo construct fields with values, use the helpers `String()`, `Int()`, `Float()`, or most commonly, the generic `F[T]()`.\nTo send a null, use `Null[T]()`, and to send a nonconforming value, use `Raw[T](any)`. For example:\n\n```go\nparams := FooParams{\n\tName: SDK_PackageName.F("hello"),\n\n\t// Explicitly send `"description": null`\n\tDescription: SDK_PackageName.Null[string](),\n\n\tPoint: SDK_PackageName.F(SDK_PackageName.Point{\n\t\tX: SDK_PackageName.Int(0),\n\t\tY: SDK_PackageName.Int(1),\n\n\t\t// In cases where the API specifies a given type,\n\t\t// but you want to send something else, use `Raw`:\n\t\tZ: SDK_PackageName.Raw[int64](0.01), // sends a float\n\t}),\n}\n```\n\n### Response objects\n\nAll fields in response structs are value types (not pointers or wrappers).\n\nIf a given field is `null`, not present, or invalid, the corresponding field\nwill simply be its zero value.\n\nAll response structs also include a special `JSON` field, containing more detailed\ninformation about each property, which you can use like so:\n\n```go\nif res.Name == "" {\n\t// true if `"name"` is either not present or explicitly null\n\tres.JSON.Name.IsNull()\n\n\t// true if the `"name"` key was not present in the response JSON at all\n\tres.JSON.Name.IsMissing()\n\n\t// When the API returns data that cannot be coerced to the expected type:\n\tif res.JSON.Name.IsInvalid() {\n\t\traw := res.JSON.Name.Raw()\n\n\t\tlegacyName := struct{\n\t\t\tFirst string `json:"first"`\n\t\t\tLast string `json:"last"`\n\t\t}{}\n\t\tjson.Unmarshal([]byte(raw), &legacyName)\n\t\tname = legacyName.First + " " + legacyName.Last\n\t}\n}\n```\n\nThese `.JSON` structs also include an `Extras` map containing\nany properties in the json response that were not specified\nin the struct. This can be useful for API features not yet\npresent in the SDK.\n\n```go\nbody := res.JSON.ExtraFields["my_unexpected_field"].Raw()\n```\n\n### RequestOptions\n\nThis library uses the functional options pattern. Functions defined in the\n`SDK_PackageOptionName` package return a `RequestOption`, which is a closure that mutates a\n`RequestConfig`. These options can be supplied to the client or at individual\nrequests. For example:\n\n```go\nclient := SDK_PackageName.SDK_ClientInitializerName(\n\t// Adds a header to every request made by the client\n\tSDK_PackageOptionName.WithHeader("X-Some-Header", "custom_header_info"),\n)\n\nclient.Brand.Get(context.TODO(), ...,\n\t// Override the header\n\tSDK_PackageOptionName.WithHeader("X-Some-Header", "some_other_custom_header_info"),\n\t// Add an undocumented field to the request body, using sjson syntax\n\tSDK_PackageOptionName.WithJSONSet("some.json.path", map[string]string{"my": "object"}),\n)\n```\n\nSee the [full list of request options](https://pkg.go.dev/github.com/context-dot-dev/context-go-sdk/v2/SDK_PackageOptionName).\n\n### Pagination\n\nThis library provides some conveniences for working with paginated list endpoints.\n\nYou can use `.ListAutoPaging()` methods to iterate through items across all pages:\n\n\n\nOr you can use simple `.List()` methods to fetch a single page and receive a standard response object\nwith additional helper methods like `.GetNextPage()`, e.g.:\n\n\n\n### Errors\n\nWhen the API returns a non-success status code, we return an error with type\n`*SDK_PackageName.Error`. This contains the `StatusCode`, `*http.Request`, and\n`*http.Response` values of the request, as well as the JSON of the error body\n(much like other response objects in the SDK).\n\nTo handle errors, we recommend that you use the `errors.As` pattern:\n\n```go\n_, err := client.Brand.Get(context.TODO(), contextdev.BrandGetParams{\n\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\tDomain: "stripe.com",\n\t},\n})\nif err != nil {\n\tvar apierr *contextdev.Error\n\tif errors.As(err, &apierr) {\n\t\tprintln(string(apierr.DumpRequest(true))) // Prints the serialized HTTP request\n\t\tprintln(string(apierr.DumpResponse(true))) // Prints the serialized HTTP response\n\t}\n\tpanic(err.Error()) // GET "/brand/retrieve": 400 Bad Request { ... }\n}\n```\n\nWhen other errors occur, they are returned unwrapped; for example,\nif HTTP transport fails, you might receive `*url.Error` wrapping `*net.OpError`.\n\n### Timeouts\n\nRequests do not time out by default; use context to configure a timeout for a request lifecycle.\n\nNote that if a request is [retried](#retries), the context timeout does not start over.\nTo set a per-retry timeout, use `SDK_PackageOptionName.WithRequestTimeout()`.\n\n```go\n// This sets the timeout for the request, including all the retries.\nctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)\ndefer cancel()\nclient.Brand.Get(\n\tctx,\n\tcontextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t},\n\t// This sets the per-retry timeout\n\toption.WithRequestTimeout(20*time.Second),\n)\n```\n\n### File uploads\n\nRequest parameters that correspond to file uploads in multipart requests are typed as\n`param.Field[io.Reader]`. The contents of the `io.Reader` will by default be sent as a multipart form\npart with the file name of "anonymous_file" and content-type of "application/octet-stream".\n\nThe file name and content-type can be customized by implementing `Name() string` or `ContentType()\nstring` on the run-time type of `io.Reader`. Note that `os.File` implements `Name() string`, so a\nfile returned by `os.Open` will be sent with the file name on disk.\n\nWe also provide a helper `SDK_PackageName.FileParam(reader io.Reader, filename string, contentType string)`\nwhich can be used to wrap any `io.Reader` with the appropriate file name and content type.\n\n\n\n### Retries\n\nCertain errors will be automatically retried 2 times by default, with a short exponential backoff.\nWe retry by default all connection errors, 408 Request Timeout, 409 Conflict, 429 Rate Limit,\nand >=500 Internal errors.\n\nYou can use the `WithMaxRetries` option to configure or disable this:\n\n```go\n// Configure the default for all requests:\nclient := contextdev.NewClient(\n\toption.WithMaxRetries(0), // default is 2\n)\n\n// Override per-request:\nclient.Brand.Get(\n\tcontext.TODO(),\n\tcontextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t},\n\toption.WithMaxRetries(5),\n)\n```\n\n\n### Accessing raw response data (e.g. response headers)\n\nYou can access the raw HTTP response data by using the `option.WithResponseInto()` request option. This is useful when\nyou need to examine response headers, status codes, or other details.\n\n```go\n// Create a variable to store the HTTP response\nvar response *http.Response\nbrand, err := client.Brand.Get(\n\tcontext.TODO(),\n\tcontextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t},\n\toption.WithResponseInto(&response),\n)\nif err != nil {\n\t// handle error\n}\nfmt.Printf("%+v\\n", brand)\n\nfmt.Printf("Status Code: %d\\n", response.StatusCode)\nfmt.Printf("Headers: %+#v\\n", response.Header)\n```\n\n### Making custom/undocumented requests\n\nThis library is typed for convenient access to the documented API. If you need to access undocumented\nendpoints, params, or response properties, the library can still be used.\n\n#### Undocumented endpoints\n\nTo make requests to undocumented endpoints, you can use `client.Get`, `client.Post`, and other HTTP verbs.\n`RequestOptions` on the client, such as retries, will be respected when making these requests.\n\n```go\nvar (\n // params can be an io.Reader, a []byte, an encoding/json serializable object,\n // or a "…Params" struct defined in this library.\n params map[string]interface{}\n\n // result can be an []byte, *http.Response, a encoding/json deserializable object,\n // or a model defined in this library.\n result *http.Response\n)\nerr := client.Post(context.Background(), "/unspecified", params, &result)\nif err != nil {\n …\n}\n```\n\n#### Undocumented request params\n\nTo make requests using undocumented parameters, you may use either the `SDK_PackageOptionName.WithQuerySet()`\nor the `SDK_PackageOptionName.WithJSONSet()` methods.\n\n```go\nparams := FooNewParams{\n ID: SDK_PackageName.F("id_xxxx"),\n Data: SDK_PackageName.F(FooNewParamsData{\n FirstName: SDK_PackageName.F("John"),\n }),\n}\nclient.Foo.New(context.Background(), params, SDK_PackageOptionName.WithJSONSet("data.last_name", "Doe"))\n```\n\n#### Undocumented response properties\n\nTo access undocumented response properties, you may either access the raw JSON of the response as a string\nwith `result.JSON.RawJSON()`, or get the raw JSON of a particular field on the result with\n`result.JSON.Foo.Raw()`.\n\nAny fields that are not present on the response struct will be saved and can be accessed by `result.JSON.ExtraFields()` which returns the extra fields as a `map[string]Field`.\n\n### Middleware\n\nWe provide `SDK_PackageOptionName.WithMiddleware` which applies the given\nmiddleware to requests.\n\n```go\nfunc Logger(req *http.Request, next SDK_PackageOptionName.MiddlewareNext) (res *http.Response, err error) {\n\t// Before the request\n\tstart := time.Now()\n\tLogReq(req)\n\n\t// Forward the request to the next handler\n\tres, err = next(req)\n\n\t// Handle stuff after the request\n\tend := time.Now()\n\tLogRes(res, err, start - end)\n\n return res, err\n}\n\nclient := SDK_PackageName.SDK_ClientInitializerName(\n\tSDK_PackageOptionName.WithMiddleware(Logger),\n)\n```\n\nWhen multiple middlewares are provided as variadic arguments, the middlewares\nare applied left to right. If `SDK_PackageOptionName.WithMiddleware` is given\nmultiple times, for example first in the client then the method, the\nmiddleware in the client will run first and the middleware given in the method\nwill run next.\n\nYou may also replace the default `http.Client` with\n`SDK_PackageOptionName.WithHTTPClient(client)`. Only one http client is\naccepted (this overwrites any previous client) and receives requests after any\nmiddleware has been applied.\n\n## Semantic versioning\n\nThis package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:\n\n1. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_\n2. Changes that we do not expect to impact the vast majority of users in practice.\n\nWe take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.\n\nWe are keen for your feedback; please open an [issue](https://www.github.com/context-dot-dev/context-go-sdk/issues) with questions, bugs, or suggestions.\n\n## Contributing\n\nSee [the contributing documentation](./CONTRIBUTING.md).\n', - }, - { - language: 'cli', - content: - "# Context Dev CLI\n\nThe official CLI for the [Context Dev REST API](https://docs.context.dev/).\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n\n\n## Installation\n\n### Installing with Go\n\nTo test or install the CLI locally, you need [Go](https://go.dev/doc/install) version 1.22 or later installed.\n\n~~~sh\ngo install 'github.com/context-dot-dev/context-dev-cli/cmd/context-dev@latest'\n~~~\n\nOnce you have run `go install`, the binary is placed in your Go bin directory:\n\n- **Default location**: `$HOME/go/bin` (or `$GOPATH/bin` if GOPATH is set)\n- **Check your path**: Run `go env GOPATH` to see the base directory\n\nIf commands aren't found after installation, add the Go bin directory to your PATH:\n\n~~~sh\n# Add to your shell profile (.zshrc, .bashrc, etc.)\nexport PATH=\"$PATH:$(go env GOPATH)/bin\"\n~~~\n\n\n\n### Running Locally\n\nAfter cloning the git repository for this project, you can use the\n`scripts/run` script to run the tool locally:\n\n~~~sh\n./scripts/run args...\n~~~\n\n## Usage\n\nThe CLI follows a resource-based command structure:\n\n~~~sh\ncontext-dev [resource] [flags...]\n~~~\n\n~~~sh\ncontext-dev brand retrieve \\\n --api-key 'My API Key' \\\n --domain REPLACE_ME \\\n --type by_domain\n~~~\n\nFor details about specific commands, use the `--help` flag.\n\n### Environment variables\n\n| Environment variable | Required |\n| --------------------- | -------- |\n| `CONTEXT_DEV_API_KEY` | yes |\n\n### Global flags\n\n- `--api-key` (can also be set with `CONTEXT_DEV_API_KEY` env var)\n- `--help` - Show command line usage\n- `--debug` - Enable debug logging (includes HTTP request/response details)\n- `--version`, `-v` - Show the CLI version\n- `--base-url` - Use a custom API backend URL\n- `--format` - Change the output format (`auto`, `explore`, `json`, `jsonl`, `pretty`, `raw`, `yaml`)\n- `--format-error` - Change the output format for errors (`auto`, `explore`, `json`, `jsonl`, `pretty`, `raw`, `yaml`)\n- `--transform` - Transform the data output using [GJSON syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)\n- `--transform-error` - Transform the error output using [GJSON syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)\n\n### Passing files as arguments\n\nTo pass files to your API, you can use the `@myfile.ext` syntax:\n\n~~~bash\ncontext-dev --arg @abe.jpg\n~~~\n\nFiles can also be passed inside JSON or YAML blobs:\n\n~~~bash\ncontext-dev --arg '{image: \"@abe.jpg\"}'\n# Equivalent:\ncontext-dev < --username '\\@abe'\n~~~\n\n#### Explicit encoding\n\nFor JSON endpoints, the CLI tool does filetype sniffing to determine whether the\nfile contents should be sent as a string literal (for plain text files) or as a\nbase64-encoded string literal (for binary files). If you need to explicitly send\nthe file as either plain text or base64-encoded data, you can use\n`@file://myfile.txt` (for string encoding) or `@data://myfile.dat` (for\nbase64-encoding). Note that absolute paths will begin with `@file://` or\n`@data://`, followed by a third `/` (for example, `@file:///tmp/file.txt`).\n\n~~~bash\ncontext-dev --arg @data://file.txt\n~~~\n\n## Linking different Go SDK versions\n\nYou can link the CLI against a different version of the Context Dev Go SDK\nfor development purposes using the `./scripts/link` script.\n\nTo link to a specific version from a repository (version can be a branch,\ngit tag, or commit hash):\n\n~~~bash\n./scripts/link github.com/org/repo@version\n~~~\n\nTo link to a local copy of the SDK:\n\n~~~bash\n./scripts/link ../path/to/contextdev-go\n~~~\n\nIf you run the link script without any arguments, it will default to `../contextdev-go`.\n", - }, - { - language: 'python', - content: - '# Context Dev Python API library\n\n\n[![PyPI version](https://img.shields.io/pypi/v/context.dev.svg?label=pypi%20(stable))](https://pypi.org/project/context.dev/)\n\nThe Context Dev Python library provides convenient access to the Context Dev REST API from any Python 3.9+\napplication. The library includes type definitions for all request params and response fields,\nand offers both synchronous and asynchronous clients powered by [httpx](https://github.com/encode/httpx).\n\n\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n## MCP Server\n\nUse the Context Dev MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0)\n[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D)\n\n> Note: You may need to set environment variables in your MCP client.\n\n## Documentation\n\nThe REST API documentation can be found on [docs.context.dev](https://docs.context.dev/). The full API of this library can be found in [api.md](api.md).\n\n## Installation\n\n```sh\n# install from PyPI\npip install context.dev\n```\n\n## Usage\n\nThe full API of this library can be found in [api.md](api.md).\n\n```python\nimport os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\n\nbrand = client.brand.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n)\nprint(brand.cache_metadata)\n```\n\nWhile you can provide an `api_key` keyword argument,\nwe recommend using [python-dotenv](https://pypi.org/project/python-dotenv/)\nto add `CONTEXT_DEV_API_KEY="My API Key"` to your `.env` file\nso that your API Key is not stored in source control.\n\n## Async usage\n\nSimply import `AsyncContextDev` instead of `ContextDev` and use `await` with each API call:\n\n```python\nimport os\nimport asyncio\nfrom context.dev import AsyncContextDev\n\nclient = AsyncContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\n\nasync def main() -> None:\n brand = await client.brand.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n )\n print(brand.cache_metadata)\n\nasyncio.run(main())\n```\n\nFunctionality between the synchronous and asynchronous clients is otherwise identical.\n\n### With aiohttp\n\nBy default, the async client uses `httpx` for HTTP requests. However, for improved concurrency performance you may also use `aiohttp` as the HTTP backend.\n\nYou can enable this by installing `aiohttp`:\n\n```sh\n# install from PyPI\npip install context.dev[aiohttp]\n```\n\nThen you can enable it by instantiating the client with `http_client=DefaultAioHttpClient()`:\n\n```python\nimport os\nimport asyncio\nfrom context.dev import DefaultAioHttpClient\nfrom context.dev import AsyncContextDev\n\nasync def main() -> None:\n async with AsyncContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n http_client=DefaultAioHttpClient(),\n) as client:\n brand = await client.brand.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n )\n print(brand.cache_metadata)\n\nasyncio.run(main())\n```\n\n\n\n## Using types\n\nNested request parameters are [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict). Responses are [Pydantic models](https://docs.pydantic.dev) which also provide helper methods for things like:\n\n- Serializing back into JSON, `model.to_json()`\n- Converting to a dictionary, `model.to_dict()`\n\nTyped requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `basic`.\n\n\n\n## Nested params\n\nNested parameters are dictionaries, typed using `TypedDict`, for example:\n\n```python\nfrom context.dev import ContextDev\n\nclient = ContextDev()\n\nresponse = client.parse.handle(\n body=b"Example data",\n pdf={},\n)\nprint(response.pdf)\n```\n\n\n\n## Handling errors\n\nWhen the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of `context.dev.APIConnectionError` is raised.\n\nWhen the API returns a non-success status code (that is, 4xx or 5xx\nresponse), a subclass of `context.dev.APIStatusError` is raised, containing `status_code` and `response` properties.\n\nAll errors inherit from `context.dev.APIError`.\n\n```python\nimport context.dev\nfrom context.dev import ContextDev\n\nclient = ContextDev()\n\ntry:\n client.brand.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n )\nexcept context.dev.APIConnectionError as e:\n print("The server could not be reached")\n print(e.__cause__) # an underlying Exception, likely raised within httpx.\nexcept context.dev.RateLimitError as e:\n print("A 429 status code was received; we should back off a bit.")\nexcept context.dev.APIStatusError as e:\n print("Another non-200-range status code was received")\n print(e.status_code)\n print(e.response)\n```\n\nError codes are as follows:\n\n| Status Code | Error Type |\n| ----------- | -------------------------- |\n| 400 | `BadRequestError` |\n| 401 | `AuthenticationError` |\n| 403 | `PermissionDeniedError` |\n| 404 | `NotFoundError` |\n| 422 | `UnprocessableEntityError` |\n| 429 | `RateLimitError` |\n| >=500 | `InternalServerError` |\n| N/A | `APIConnectionError` |\n\n### Retries\n\nCertain errors are automatically retried 2 times by default, with a short exponential backoff.\nConnection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,\n429 Rate Limit, and >=500 Internal errors are all retried by default.\n\nYou can use the `max_retries` option to configure or disable retry settings:\n\n```python\nfrom context.dev import ContextDev\n\n# Configure the default for all requests:\nclient = ContextDev(\n # default is 2\n max_retries=0,\n)\n\n# Or, configure per-request:\nclient.with_options(max_retries = 5).brand.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n)\n```\n\n### Timeouts\n\nBy default requests time out after 1 minute. You can configure this with a `timeout` option,\nwhich accepts a float or an [`httpx.Timeout`](https://www.python-httpx.org/advanced/timeouts/#fine-tuning-the-configuration) object:\n\n```python\nfrom context.dev import ContextDev\n\n# Configure the default for all requests:\nclient = ContextDev(\n # 20 seconds (default is 1 minute)\n timeout=20.0,\n)\n\n# More granular control:\nclient = ContextDev(\n timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),\n)\n\n# Override per-request:\nclient.with_options(timeout = 5.0).brand.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n)\n```\n\nOn timeout, an `APITimeoutError` is thrown.\n\nNote that requests that time out are [retried twice by default](#retries).\n\n\n\n## Advanced\n\n### Logging\n\nWe use the standard library [`logging`](https://docs.python.org/3/library/logging.html) module.\n\nYou can enable logging by setting the environment variable `CONTEXT_DEV_LOG` to `info`.\n\n```shell\n$ export CONTEXT_DEV_LOG=info\n```\n\nOr to `debug` for more verbose logging.\n\n### How to tell whether `None` means `null` or missing\n\nIn an API response, a field may be explicitly `null`, or missing entirely; in either case, its value is `None` in this library. You can differentiate the two cases with `.model_fields_set`:\n\n```py\nif response.my_field is None:\n if \'my_field\' not in response.model_fields_set:\n print(\'Got json like {}, without a "my_field" key present at all.\')\n else:\n print(\'Got json like {"my_field": null}.\')\n```\n\n### Accessing raw response data (e.g. headers)\n\nThe "raw" Response object can be accessed by prefixing `.with_raw_response.` to any HTTP method call, e.g.,\n\n```py\nfrom context.dev import ContextDev\n\nclient = ContextDev()\nresponse = client.brand.with_raw_response.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n)\nprint(response.headers.get(\'X-My-Header\'))\n\nbrand = response.parse() # get the object that `brand.retrieve()` would have returned\nprint(brand.cache_metadata)\n```\n\nThese methods return an [`APIResponse`](https://github.com/context-dot-dev/context-python-sdk/tree/main/src/context/dev/_response.py) object.\n\nThe async client returns an [`AsyncAPIResponse`](https://github.com/context-dot-dev/context-python-sdk/tree/main/src/context/dev/_response.py) with the same structure, the only difference being `await`able methods for reading the response content.\n\n#### `.with_streaming_response`\n\nThe above interface eagerly reads the full response body when you make the request, which may not always be what you want.\n\nTo stream the response body, use `.with_streaming_response` instead, which requires a context manager and only reads the response body once you call `.read()`, `.text()`, `.json()`, `.iter_bytes()`, `.iter_text()`, `.iter_lines()` or `.parse()`. In the async client, these are async methods.\n\n```python\nwith client.brand.with_streaming_response.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n) as response :\n print(response.headers.get(\'X-My-Header\'))\n\n for line in response.iter_lines():\n print(line)\n```\n\nThe context manager is required so that the response will reliably be closed.\n\n### Making custom/undocumented requests\n\nThis library is typed for convenient access to the documented API.\n\nIf you need to access undocumented endpoints, params, or response properties, the library can still be used.\n\n#### Undocumented endpoints\n\nTo make requests to undocumented endpoints, you can make requests using `client.get`, `client.post`, and other\nhttp verbs. Options on the client will be respected (such as retries) when making this request.\n\n```py\nimport httpx\n\nresponse = client.post(\n "/foo",\n cast_to=httpx.Response,\n body={"my_param": True},\n)\n\nprint(response.headers.get("x-foo"))\n```\n\n#### Undocumented request params\n\nIf you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` request\noptions.\n\n#### Undocumented response properties\n\nTo access undocumented response properties, you can access the extra fields like `response.unknown_prop`. You\ncan also get all the extra fields on the Pydantic model as a dict with\n[`response.model_extra`](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_extra).\n\n### Configuring the HTTP client\n\nYou can directly override the [httpx client](https://www.python-httpx.org/api/#client) to customize it for your use case, including:\n\n- Support for [proxies](https://www.python-httpx.org/advanced/proxies/)\n- Custom [transports](https://www.python-httpx.org/advanced/transports/)\n- Additional [advanced](https://www.python-httpx.org/advanced/clients/) functionality\n\n```python\nimport httpx\nfrom context.dev import ContextDev, DefaultHttpxClient\n\nclient = ContextDev(\n # Or use the `CONTEXT_DEV_BASE_URL` env var\n base_url="http://my.test.server.example.com:8083",\n http_client=DefaultHttpxClient(proxy="http://my.test.proxy.example.com", transport=httpx.HTTPTransport(local_address="0.0.0.0")),\n)\n```\n\nYou can also customize the client on a per-request basis by using `with_options()`:\n\n```python\nclient.with_options(http_client=DefaultHttpxClient(...))\n```\n\n### Managing HTTP resources\n\nBy default the library closes underlying HTTP connections whenever the client is [garbage collected](https://docs.python.org/3/reference/datamodel.html#object.__del__). You can manually close the client using the `.close()` method if desired, or with a context manager that closes when exiting.\n\n```py\nfrom context.dev import ContextDev\n\nwith ContextDev() as client:\n # make requests here\n ...\n\n# HTTP client is now closed\n```\n\n## Versioning\n\nThis package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:\n\n1. Changes that only affect static types, without breaking runtime behavior.\n2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_\n3. Changes that we do not expect to impact the vast majority of users in practice.\n\nWe take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.\n\nWe are keen for your feedback; please open an [issue](https://www.github.com/context-dot-dev/context-python-sdk/issues) with questions, bugs, or suggestions.\n\n### Determining the installed version\n\nIf you\'ve upgraded to the latest version but aren\'t seeing any new features you were expecting then your python environment is likely still using an older version.\n\nYou can determine the version that is being used at runtime with:\n\n```py\nimport context.dev\nprint(context.dev.__version__)\n```\n\n## Requirements\n\nPython 3.9 or higher.\n\n## Contributing\n\nSee [the contributing documentation](./CONTRIBUTING.md).\n', - }, - { - language: 'ruby', - content: - '# Context Dev Ruby API library\n\nThe Context Dev Ruby library provides convenient access to the Context Dev REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/context-dot-dev/context-ruby-sdk#Sorbet) for usage with Sorbet. The standard library\'s `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.\n\n\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n## MCP Server\n\nUse the Context Dev MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0)\n[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D)\n\n> Note: You may need to set environment variables in your MCP client.\n\n## Documentation\n\nDocumentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/context.dev).\n\nThe REST API documentation can be found on [docs.context.dev](https://docs.context.dev/).\n\n## Installation\n\nTo use this gem, install via Bundler by adding the following to your application\'s `Gemfile`:\n\n\n\n```ruby\ngem "context.dev", "~> 2.13.0"\n```\n\n\n\n## Usage\n\n```ruby\nrequire "bundler/setup"\nrequire "context_dev"\n\ncontext_dev = ContextDev::Client.new(\n api_key: ENV["CONTEXT_DEV_API_KEY"] # This is the default and can be omitted\n)\n\nbrand = context_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"})\n\nputs(brand.cache_metadata)\n```\n\n\n\n\n\n\n\n### Handling errors\n\nWhen the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `ContextDev::Errors::APIError` will be thrown:\n\n```ruby\nbegin\n brand = context_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"})\nrescue ContextDev::Errors::APIConnectionError => e\n puts("The server could not be reached")\n puts(e.cause) # an underlying Exception, likely raised within `net/http`\nrescue ContextDev::Errors::RateLimitError => e\n puts("A 429 status code was received; we should back off a bit.")\nrescue ContextDev::Errors::APIStatusError => e\n puts("Another non-200-range status code was received")\n puts(e.status)\nend\n```\n\nError codes are as follows:\n\n| Cause | Error Type |\n| ---------------- | -------------------------- |\n| HTTP 400 | `BadRequestError` |\n| HTTP 401 | `AuthenticationError` |\n| HTTP 403 | `PermissionDeniedError` |\n| HTTP 404 | `NotFoundError` |\n| HTTP 409 | `ConflictError` |\n| HTTP 422 | `UnprocessableEntityError` |\n| HTTP 429 | `RateLimitError` |\n| HTTP >= 500 | `InternalServerError` |\n| Other HTTP error | `APIStatusError` |\n| Timeout | `APITimeoutError` |\n| Network error | `APIConnectionError` |\n\n### Retries\n\nCertain errors will be automatically retried 2 times by default, with a short exponential backoff.\n\nConnection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.\n\nYou can use the `max_retries` option to configure or disable this:\n\n```ruby\n# Configure the default for all requests:\ncontext_dev = ContextDev::Client.new(\n max_retries: 0 # default is 2\n)\n\n# Or, configure per-request:\ncontext_dev.brand.retrieve(\n body: {domain: "stripe.com", type: "by_domain"},\n request_options: {max_retries: 5}\n)\n```\n\n### Timeouts\n\nBy default, requests will time out after 60 seconds. You can use the timeout option to configure or disable this:\n\n```ruby\n# Configure the default for all requests:\ncontext_dev = ContextDev::Client.new(\n timeout: nil # default is 60\n)\n\n# Or, configure per-request:\ncontext_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"}, request_options: {timeout: 5})\n```\n\nOn timeout, `ContextDev::Errors::APITimeoutError` is raised.\n\nNote that requests that time out are retried by default.\n\n## Advanced concepts\n\n### BaseModel\n\nAll parameter and response objects inherit from `ContextDev::Internal::Type::BaseModel`, which provides several conveniences, including:\n\n1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.\n\n2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.\n\n3. Both instances and the classes themselves can be pretty-printed.\n\n4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.\n\n### Making custom or undocumented requests\n\n#### Undocumented properties\n\nYou can send undocumented parameters to any endpoint, and read undocumented response properties, like so:\n\nNote: the `extra_` parameters of the same name overrides the documented parameters.\n\n```ruby\nbrand =\n context_dev.brand.retrieve(\n body: {domain: "stripe.com", type: "by_domain"},\n request_options: {\n extra_query: {my_query_parameter: value},\n extra_body: {my_body_parameter: value},\n extra_headers: {"my-header": value}\n }\n )\n\nputs(brand[:my_undocumented_property])\n```\n\n#### Undocumented request params\n\nIf you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request, as seen in the examples above.\n\n#### Undocumented endpoints\n\nTo make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using `client.request`, like so:\n\n```ruby\nresponse = client.request(\n method: :post,\n path: \'/undocumented/endpoint\',\n query: {"dog": "woof"},\n headers: {"useful-header": "interesting-value"},\n body: {"hello": "world"}\n)\n```\n\n### Concurrency & connection pooling\n\nThe `ContextDev::Client` instances are threadsafe, but are only are fork-safe when there are no in-flight HTTP requests.\n\nEach instance of `ContextDev::Client` has its own HTTP connection pool with a default size of 99. As such, we recommend instantiating the client once per application in most settings.\n\nWhen all available connections from the pool are checked out, requests wait for a new connection to become available, with queue time counting towards the request timeout.\n\nUnless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.\n\n## Sorbet\n\nThis library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.\n\nYou can provide typesafe request parameters like so:\n\n```ruby\ncontext_dev.brand.retrieve(\n body: ContextDev::BrandRetrieveParams::Body::ByDomain.new(domain: "stripe.com")\n)\n```\n\nOr, equivalently:\n\n```ruby\n# Hashes work, but are not typesafe:\ncontext_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"})\n\n# You can also splat a full Params class:\nparams = ContextDev::BrandRetrieveParams.new(\n body: ContextDev::BrandRetrieveParams::Body::ByDomain.new(domain: "stripe.com")\n)\ncontext_dev.brand.retrieve(**params)\n```\n\n### Enums\n\nSince this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:\n\n```ruby\n# :txt\nputs(ContextDev::ParseHandleParams::Extension::TXT)\n\n# Revealed type: `T.all(ContextDev::ParseHandleParams::Extension, Symbol)`\nT.reveal_type(ContextDev::ParseHandleParams::Extension::TXT)\n```\n\nEnum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:\n\n```ruby\n# Using the enum constants preserves the tagged type information:\ncontext_dev.parse.handle(\n extension: ContextDev::ParseHandleParams::Extension::TXT,\n # …\n)\n\n# Literal values are also permissible:\ncontext_dev.parse.handle(\n extension: :txt,\n # …\n)\n```\n\n## Versioning\n\nThis package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.\n\nThis package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.\n\n## Requirements\n\nRuby 3.2.0 or higher.\n\n## Contributing\n\nSee [the contributing documentation](https://github.com/context-dot-dev/context-ruby-sdk/tree/main/CONTRIBUTING.md).\n', - }, - { - language: 'typescript', - content: - "# Context Dev TypeScript API Library\n\n[![NPM version](https://img.shields.io/npm/v/context.dev.svg?label=npm%20(stable))](https://npmjs.org/package/context.dev) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/context.dev)\n\nThis library provides convenient access to the Context Dev REST API from server-side TypeScript or JavaScript.\n\n\n\nThe REST API documentation can be found on [docs.context.dev](https://docs.context.dev/). The full API of this library can be found in [api.md](api.md).\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n## MCP Server\n\nUse the Context Dev MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0)\n[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D)\n\n> Note: You may need to set environment variables in your MCP client.\n\n## Installation\n\n```sh\nnpm install context.dev\n```\n\n\n\n## Usage\n\nThe full API of this library can be found in [api.md](api.md).\n\n\n```js\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst brand = await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' });\n\nconsole.log(brand.cache_metadata);\n```\n\n\n\n### Request & Response types\n\nThis library includes TypeScript definitions for all request params and response fields. You may import and use them like so:\n\n\n```ts\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst params: ContextDev.BrandRetrieveParams = { domain: 'REPLACE_ME', type: 'by_domain' };\nconst brand: ContextDev.BrandRetrieveResponse = await client.brand.retrieve(params);\n```\n\nDocumentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.\n\n\n\n\n\n## Handling errors\n\nWhen the library is unable to connect to the API,\nor if the API returns a non-success status code (i.e., 4xx or 5xx response),\na subclass of `APIError` will be thrown:\n\n\n```ts\nconst brand = await client.brand\n .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' })\n .catch(async (err) => {\n if (err instanceof ContextDev.APIError) {\n console.log(err.status); // 400\n console.log(err.name); // BadRequestError\n console.log(err.headers); // {server: 'nginx', ...}\n } else {\n throw err;\n }\n });\n```\n\nError codes are as follows:\n\n| Status Code | Error Type |\n| ----------- | -------------------------- |\n| 400 | `BadRequestError` |\n| 401 | `AuthenticationError` |\n| 403 | `PermissionDeniedError` |\n| 404 | `NotFoundError` |\n| 422 | `UnprocessableEntityError` |\n| 429 | `RateLimitError` |\n| >=500 | `InternalServerError` |\n| N/A | `APIConnectionError` |\n\n### Retries\n\nCertain errors will be automatically retried 2 times by default, with a short exponential backoff.\nConnection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,\n429 Rate Limit, and >=500 Internal errors will all be retried by default.\n\nYou can use the `maxRetries` option to configure or disable this:\n\n\n```js\n// Configure the default for all requests:\nconst client = new ContextDev({\n maxRetries: 0, // default is 2\n});\n\n// Or, configure per-request:\nawait client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }, {\n maxRetries: 5,\n});\n```\n\n### Timeouts\n\nRequests time out after 1 minute by default. You can configure this with a `timeout` option:\n\n\n```ts\n// Configure the default for all requests:\nconst client = new ContextDev({\n timeout: 20 * 1000, // 20 seconds (default is 1 minute)\n});\n\n// Override per-request:\nawait client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }, {\n timeout: 5 * 1000,\n});\n```\n\nOn timeout, an `APIConnectionTimeoutError` is thrown.\n\nNote that requests which time out will be [retried twice by default](#retries).\n\n\n\n\n\n## Advanced Usage\n\n### Accessing raw Response data (e.g., headers)\n\nThe \"raw\" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.\nThis method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.\n\nYou can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.\nUnlike `.asResponse()` this method consumes the body, returning once it is parsed.\n\n\n```ts\nconst client = new ContextDev();\n\nconst response = await client.brand\n .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' })\n .asResponse();\nconsole.log(response.headers.get('X-My-Header'));\nconsole.log(response.statusText); // access the underlying Response object\n\nconst { data: brand, response: raw } = await client.brand\n .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' })\n .withResponse();\nconsole.log(raw.headers.get('X-My-Header'));\nconsole.log(brand.cache_metadata);\n```\n\n### Logging\n\n> [!IMPORTANT]\n> All log messages are intended for debugging only. The format and content of log messages\n> may change between releases.\n\n#### Log levels\n\nThe log level can be configured in two ways:\n\n1. Via the `CONTEXT_DEV_LOG` environment variable\n2. Using the `logLevel` client option (overrides the environment variable if set)\n\n```ts\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n logLevel: 'debug', // Show all log messages\n});\n```\n\nAvailable log levels, from most to least verbose:\n\n- `'debug'` - Show debug messages, info, warnings, and errors\n- `'info'` - Show info messages, warnings, and errors\n- `'warn'` - Show warnings and errors (default)\n- `'error'` - Show only errors\n- `'off'` - Disable all logging\n\nAt the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.\nSome authentication-related headers are redacted, but sensitive data in request and response bodies\nmay still be visible.\n\n#### Custom logger\n\nBy default, this library logs to `globalThis.console`. You can also provide a custom logger.\nMost logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.\n\nWhen providing a custom logger, the `logLevel` option still controls which messages are emitted, messages\nbelow the configured level will not be sent to your logger.\n\n```ts\nimport ContextDev from 'context.dev';\nimport pino from 'pino';\n\nconst logger = pino();\n\nconst client = new ContextDev({\n logger: logger.child({ name: 'ContextDev' }),\n logLevel: 'debug', // Send all messages to pino, allowing it to filter\n});\n```\n\n### Making custom/undocumented requests\n\nThis library is typed for convenient access to the documented API. If you need to access undocumented\nendpoints, params, or response properties, the library can still be used.\n\n#### Undocumented endpoints\n\nTo make requests to undocumented endpoints, you can use `client.get`, `client.post`, and other HTTP verbs.\nOptions on the client, such as retries, will be respected when making these requests.\n\n```ts\nawait client.post('/some/path', {\n body: { some_prop: 'foo' },\n query: { some_query_arg: 'bar' },\n});\n```\n\n#### Undocumented request params\n\nTo make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented\nparameter. This library doesn't validate at runtime that the request matches the type, so any extra values you\nsend will be sent as-is.\n\n```ts\nclient.brand.retrieve({\n // ...\n // @ts-expect-error baz is not yet public\n baz: 'undocumented option',\n});\n```\n\nFor requests with the `GET` verb, any extra params will be in the query, all other requests will send the\nextra param in the body.\n\nIf you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request\noptions.\n\n#### Undocumented response properties\n\nTo access undocumented response properties, you may access the response object with `// @ts-expect-error` on\nthe response object, or cast the response object to the requisite type. Like the request params, we do not\nvalidate or strip extra properties from the response from the API.\n\n### Customizing the fetch client\n\nBy default, this library expects a global `fetch` function is defined.\n\nIf you want to use a different `fetch` function, you can either polyfill the global:\n\n```ts\nimport fetch from 'my-fetch';\n\nglobalThis.fetch = fetch;\n```\n\nOr pass it to the client:\n\n```ts\nimport ContextDev from 'context.dev';\nimport fetch from 'my-fetch';\n\nconst client = new ContextDev({ fetch });\n```\n\n### Fetch options\n\nIf you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)\n\n```ts\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n fetchOptions: {\n // `RequestInit` options\n },\n});\n```\n\n#### Configuring proxies\n\nTo modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy\noptions to requests:\n\n **Node** [[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]\n\n```ts\nimport ContextDev from 'context.dev';\nimport * as undici from 'undici';\n\nconst proxyAgent = new undici.ProxyAgent('http://localhost:8888');\nconst client = new ContextDev({\n fetchOptions: {\n dispatcher: proxyAgent,\n },\n});\n```\n\n **Bun** [[docs](https://bun.sh/guides/http/proxy)]\n\n```ts\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n fetchOptions: {\n proxy: 'http://localhost:8888',\n },\n});\n```\n\n **Deno** [[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]\n\n```ts\nimport ContextDev from 'npm:context.dev';\n\nconst httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });\nconst client = new ContextDev({\n fetchOptions: {\n client: httpClient,\n },\n});\n```\n\n## Frequently Asked Questions\n\n## Semantic versioning\n\nThis package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:\n\n1. Changes that only affect static types, without breaking runtime behavior.\n2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_\n3. Changes that we do not expect to impact the vast majority of users in practice.\n\nWe take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.\n\nWe are keen for your feedback; please open an [issue](https://www.github.com/context-dot-dev/context-typescript-sdk/issues) with questions, bugs, or suggestions.\n\n## Requirements\n\nTypeScript >= 4.9 is supported.\n\nThe following runtimes are supported:\n\n- Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)\n- Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.\n- Deno v1.28.0 or higher.\n- Bun 1.0 or later.\n- Cloudflare Workers.\n- Vercel Edge Runtime.\n- Jest 28 or greater with the `\"node\"` environment (`\"jsdom\"` is not supported at this time).\n- Nitro v2.6 or greater.\n\nNote that React Native is not supported at this time.\n\nIf you are interested in other runtime environments, please open or upvote an issue on GitHub.\n\n## Contributing\n\nSee [the contributing documentation](./CONTRIBUTING.md).\n", - }, -]; - -const INDEX_OPTIONS = { - fields: [ - 'name', - 'endpoint', - 'summary', - 'description', - 'qualified', - 'stainlessPath', - 'content', - 'sectionContext', - ], - storeFields: ['kind', '_original'], - searchOptions: { - prefix: true, - fuzzy: 0.1, - boost: { - name: 5, - stainlessPath: 3, - endpoint: 3, - qualified: 3, - summary: 2, - content: 1, - description: 1, - } as Record, - }, -}; - -/** - * Self-contained local search engine backed by MiniSearch. - * Method data is embedded at SDK build time; prose documents - * can be loaded from an optional docs directory at runtime. - */ -export class LocalDocsSearch { - private methodIndex: MiniSearch; - private proseIndex: MiniSearch; - - private constructor() { - this.methodIndex = new MiniSearch(INDEX_OPTIONS); - this.proseIndex = new MiniSearch(INDEX_OPTIONS); - } - - static async create(opts?: { docsDir?: string }): Promise { - const instance = new LocalDocsSearch(); - instance.indexMethods(EMBEDDED_METHODS); - for (const readme of EMBEDDED_READMES) { - instance.indexProse(readme.content, `readme:${readme.language}`); - } - if (opts?.docsDir) { - await instance.loadDocsDirectory(opts.docsDir); - } - return instance; - } - - search(props: { - query: string; - language?: string; - detail?: string; - maxResults?: number; - maxLength?: number; - }): SearchResult { - const { query, language = 'typescript', detail = 'default', maxResults = 5, maxLength = 100_000 } = props; - - const useMarkdown = detail === 'verbose' || detail === 'high'; - - // Search both indices and merge results by score. - // Filter prose hits so language-tagged content (READMEs and docs with - // frontmatter) only matches the requested language. - const methodHits = this.methodIndex - .search(query) - .map((hit) => ({ ...hit, _kind: 'http_method' as const })); - const proseHits = this.proseIndex - .search(query) - .filter((hit) => { - const source = ((hit as Record)['_original'] as ProseChunk | undefined)?.source; - if (!source) return true; - // Check for language-tagged sources: "readme:" or "lang::" - let taggedLang: string | undefined; - if (source.startsWith('readme:')) taggedLang = source.slice('readme:'.length); - else if (source.startsWith('lang:')) taggedLang = source.split(':')[1]; - if (!taggedLang) return true; - return taggedLang === language || (language === 'javascript' && taggedLang === 'typescript'); - }) - .map((hit) => ({ ...hit, _kind: 'prose' as const })); - const merged = [...methodHits, ...proseHits].sort((a, b) => b.score - a.score); - const top = merged.slice(0, maxResults); - - const fullResults: (string | Record)[] = []; - - for (const hit of top) { - const original = (hit as Record)['_original']; - if (hit._kind === 'http_method') { - const m = original as MethodEntry; - if (useMarkdown && m.markdown) { - fullResults.push(m.markdown); - } else { - // Use per-language data when available, falling back to the - // top-level fields (which are TypeScript-specific in the - // legacy codepath). - const langData = m.perLanguage?.[language]; - fullResults.push({ - method: langData?.method ?? m.qualified, - summary: m.summary, - description: m.description, - endpoint: `${m.httpMethod.toUpperCase()} ${m.endpoint}`, - ...(langData?.example ? { example: langData.example } : {}), - ...(m.params ? { params: m.params } : {}), - ...(m.response ? { response: m.response } : {}), - }); - } - } else { - const c = original as ProseChunk; - fullResults.push({ - content: c.content, - ...(c.source ? { source: c.source } : {}), - }); - } - } - - let totalLength = 0; - const results: (string | Record)[] = []; - for (const result of fullResults) { - const len = typeof result === 'string' ? result.length : JSON.stringify(result).length; - totalLength += len; - if (totalLength > maxLength) break; - results.push(result); - } - - if (results.length < fullResults.length) { - results.unshift(`Truncated; showing ${results.length} of ${fullResults.length} results.`); - } - - return { results }; - } - - private indexMethods(methods: MethodEntry[]): void { - const docs: MiniSearchDocument[] = methods.map((m, i) => ({ - id: `method-${i}`, - kind: 'http_method' as const, - name: m.name, - endpoint: m.endpoint, - summary: m.summary, - description: m.description, - qualified: m.qualified, - stainlessPath: m.stainlessPath, - _original: m as unknown as Record, - })); - if (docs.length > 0) { - this.methodIndex.addAll(docs); - } - } - - private async loadDocsDirectory(docsDir: string): Promise { - let entries; - try { - entries = await fs.readdir(docsDir, { withFileTypes: true }); - } catch (err) { - getLogger().warn({ err, docsDir }, 'Could not read docs directory'); - return; - } - - const files = entries - .filter((e) => e.isFile()) - .filter((e) => e.name.endsWith('.md') || e.name.endsWith('.markdown') || e.name.endsWith('.json')); - - for (const file of files) { - try { - const filePath = path.join(docsDir, file.name); - const content = await fs.readFile(filePath, 'utf-8'); - - if (file.name.endsWith('.json')) { - const texts = extractTexts(JSON.parse(content)); - if (texts.length > 0) { - this.indexProse(texts.join('\n\n'), file.name); - } - } else { - // Parse optional YAML frontmatter for language tagging. - // Files with a "language" field in frontmatter will only - // surface in searches for that language. - // - // Example: - // --- - // language: python - // --- - // # Error handling in Python - // ... - const frontmatter = parseFrontmatter(content); - const source = frontmatter.language ? `lang:${frontmatter.language}:${file.name}` : file.name; - this.indexProse(content, source); - } - } catch (err) { - getLogger().warn({ err, file: file.name }, 'Failed to index docs file'); - } - } - } - - private indexProse(markdown: string, source: string): void { - const chunks = chunkMarkdown(markdown); - const baseId = this.proseIndex.documentCount; - - const docs: MiniSearchDocument[] = chunks.map((chunk, i) => ({ - id: `prose-${baseId + i}`, - kind: 'prose' as const, - content: chunk.content, - ...(chunk.sectionContext != null ? { sectionContext: chunk.sectionContext } : {}), - _original: { ...chunk, source } as unknown as Record, - })); - - if (docs.length > 0) { - this.proseIndex.addAll(docs); - } - } -} - -/** Lightweight markdown chunker — splits on headers, chunks by word count. */ -function chunkMarkdown(markdown: string): { content: string; tag: string; sectionContext?: string }[] { - // Strip YAML frontmatter - const stripped = markdown.replace(/^---\n[\s\S]*?\n---\n?/, ''); - const lines = stripped.split('\n'); - - const chunks: { content: string; tag: string; sectionContext?: string }[] = []; - const headers: string[] = []; - let current: string[] = []; - - const flush = () => { - const text = current.join('\n').trim(); - if (!text) return; - const sectionContext = headers.length > 0 ? headers.join(' > ') : undefined; - // Split into ~200-word chunks - const words = text.split(/\s+/); - for (let i = 0; i < words.length; i += 200) { - const slice = words.slice(i, i + 200).join(' '); - if (slice) { - chunks.push({ content: slice, tag: 'p', ...(sectionContext != null ? { sectionContext } : {}) }); - } - } - current = []; - }; - - for (const line of lines) { - const headerMatch = line.match(/^(#{1,6})\s+(.+)/); - if (headerMatch) { - flush(); - const level = headerMatch[1]!.length; - const text = headerMatch[2]!.trim(); - while (headers.length >= level) headers.pop(); - headers.push(text); - } else { - current.push(line); - } - } - flush(); - - return chunks; -} - -/** Recursively extracts string values from a JSON structure. */ -function extractTexts(data: unknown, depth = 0): string[] { - if (depth > 10) return []; - if (typeof data === 'string') return data.trim() ? [data] : []; - if (Array.isArray(data)) return data.flatMap((item) => extractTexts(item, depth + 1)); - if (typeof data === 'object' && data !== null) { - return Object.values(data).flatMap((v) => extractTexts(v, depth + 1)); - } - return []; -} - -/** Parses YAML frontmatter from a markdown string, extracting the language field if present. */ -function parseFrontmatter(markdown: string): { language?: string } { - const match = markdown.match(/^---\n([\s\S]*?)\n---/); - if (!match) return {}; - const body = match[1] ?? ''; - const langMatch = body.match(/^language:\s*(.+)$/m); - return langMatch ? { language: langMatch[1]!.trim() } : {}; -} diff --git a/packages/mcp-server/src/logger.ts b/packages/mcp-server/src/logger.ts deleted file mode 100644 index 29dab11c..00000000 --- a/packages/mcp-server/src/logger.ts +++ /dev/null @@ -1,28 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { pino, type Level, type Logger } from 'pino'; -import pretty from 'pino-pretty'; - -let _logger: Logger | undefined; - -export function configureLogger({ level, pretty: usePretty }: { level: Level; pretty: boolean }): void { - _logger = pino( - { - level, - timestamp: pino.stdTimeFunctions.isoTime, - formatters: { - level(label) { - return { level: label }; - }, - }, - }, - usePretty ? pretty({ colorize: true, levelFirst: true, destination: 2 }) : process.stderr, - ); -} - -export function getLogger(): Logger { - if (!_logger) { - throw new Error('Logger has not been configured. Call configureLogger() before using the logger.'); - } - return _logger; -} diff --git a/packages/mcp-server/src/methods.ts b/packages/mcp-server/src/methods.ts deleted file mode 100644 index 71e4da35..00000000 --- a/packages/mcp-server/src/methods.ts +++ /dev/null @@ -1,332 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { McpOptions } from './options'; - -export type SdkMethod = { - clientCallName: string; - fullyQualifiedName: string; - httpMethod?: 'get' | 'post' | 'put' | 'patch' | 'delete' | 'query'; - httpPath?: string; -}; - -export const sdkMethods: SdkMethod[] = [ - { - clientCallName: 'client.parse.handle', - fullyQualifiedName: 'parse.handle', - httpMethod: 'post', - httpPath: '/parse', - }, - { - clientCallName: 'client.web.extract', - fullyQualifiedName: 'web.extract', - httpMethod: 'post', - httpPath: '/web/extract', - }, - { - clientCallName: 'client.web.extractCompetitors', - fullyQualifiedName: 'web.extractCompetitors', - httpMethod: 'get', - httpPath: '/web/competitors', - }, - { - clientCallName: 'client.web.extractFonts', - fullyQualifiedName: 'web.extractFonts', - httpMethod: 'get', - httpPath: '/web/fonts', - }, - { - clientCallName: 'client.web.extractStyleguide', - fullyQualifiedName: 'web.extractStyleguide', - httpMethod: 'get', - httpPath: '/web/styleguide', - }, - { - clientCallName: 'client.web.screenshot', - fullyQualifiedName: 'web.screenshot', - httpMethod: 'get', - httpPath: '/web/screenshot', - }, - { - clientCallName: 'client.web.search', - fullyQualifiedName: 'web.search', - httpMethod: 'post', - httpPath: '/web/search', - }, - { - clientCallName: 'client.web.webCrawlMd', - fullyQualifiedName: 'web.webCrawlMd', - httpMethod: 'post', - httpPath: '/web/crawl', - }, - { - clientCallName: 'client.web.webScrapeHTML', - fullyQualifiedName: 'web.webScrapeHTML', - httpMethod: 'get', - httpPath: '/web/scrape/html', - }, - { - clientCallName: 'client.web.webScrapeImages', - fullyQualifiedName: 'web.webScrapeImages', - httpMethod: 'get', - httpPath: '/web/scrape/images', - }, - { - clientCallName: 'client.web.webScrapeMd', - fullyQualifiedName: 'web.webScrapeMd', - httpMethod: 'get', - httpPath: '/web/scrape/markdown', - }, - { - clientCallName: 'client.web.webScrapeSitemap', - fullyQualifiedName: 'web.webScrapeSitemap', - httpMethod: 'get', - httpPath: '/web/scrape/sitemap', - }, - { - clientCallName: 'client.ai.extractProduct', - fullyQualifiedName: 'ai.extractProduct', - httpMethod: 'post', - httpPath: '/brand/ai/product', - }, - { - clientCallName: 'client.ai.extractProducts', - fullyQualifiedName: 'ai.extractProducts', - httpMethod: 'post', - httpPath: '/brand/ai/products', - }, - { - clientCallName: 'client.brand.retrieve', - fullyQualifiedName: 'brand.retrieve', - httpMethod: 'post', - httpPath: '/brand/retrieve', - }, - { - clientCallName: 'client.brand.retrieveSimplified', - fullyQualifiedName: 'brand.retrieveSimplified', - httpMethod: 'get', - httpPath: '/brand/retrieve-simplified', - }, - { - clientCallName: 'client.brand.search', - fullyQualifiedName: 'brand.search', - httpMethod: 'get', - httpPath: '/brand/search', - }, - { - clientCallName: 'client.industry.retrieveNaics', - fullyQualifiedName: 'industry.retrieveNaics', - httpMethod: 'get', - httpPath: '/web/naics', - }, - { - clientCallName: 'client.industry.retrieveSic', - fullyQualifiedName: 'industry.retrieveSic', - httpMethod: 'get', - httpPath: '/web/sic', - }, - { - clientCallName: 'client.utility.prefetch', - fullyQualifiedName: 'utility.prefetch', - httpMethod: 'post', - httpPath: '/utility/prefetch', - }, - { - clientCallName: 'client.monitors.create', - fullyQualifiedName: 'monitors.create', - httpMethod: 'post', - httpPath: '/monitors', - }, - { - clientCallName: 'client.monitors.retrieve', - fullyQualifiedName: 'monitors.retrieve', - httpMethod: 'get', - httpPath: '/monitors/{monitor_id}', - }, - { - clientCallName: 'client.monitors.update', - fullyQualifiedName: 'monitors.update', - httpMethod: 'patch', - httpPath: '/monitors/{monitor_id}', - }, - { - clientCallName: 'client.monitors.list', - fullyQualifiedName: 'monitors.list', - httpMethod: 'get', - httpPath: '/monitors', - }, - { - clientCallName: 'client.monitors.delete', - fullyQualifiedName: 'monitors.delete', - httpMethod: 'delete', - httpPath: '/monitors/{monitor_id}', - }, - { - clientCallName: 'client.monitors.getCreditUsage', - fullyQualifiedName: 'monitors.getCreditUsage', - httpMethod: 'get', - httpPath: '/monitors/credit-usage', - }, - { - clientCallName: 'client.monitors.getLimits', - fullyQualifiedName: 'monitors.getLimits', - httpMethod: 'get', - httpPath: '/monitors/limits', - }, - { - clientCallName: 'client.monitors.listAccountChanges', - fullyQualifiedName: 'monitors.listAccountChanges', - httpMethod: 'get', - httpPath: '/monitors/changes', - }, - { - clientCallName: 'client.monitors.listAccountRuns', - fullyQualifiedName: 'monitors.listAccountRuns', - httpMethod: 'get', - httpPath: '/monitors/runs', - }, - { - clientCallName: 'client.monitors.listChanges', - fullyQualifiedName: 'monitors.listChanges', - httpMethod: 'get', - httpPath: '/monitors/{monitor_id}/changes', - }, - { - clientCallName: 'client.monitors.listRuns', - fullyQualifiedName: 'monitors.listRuns', - httpMethod: 'get', - httpPath: '/monitors/{monitor_id}/runs', - }, - { - clientCallName: 'client.monitors.retrieveChange', - fullyQualifiedName: 'monitors.retrieveChange', - httpMethod: 'get', - httpPath: '/monitors/changes/{change_id}', - }, - { - clientCallName: 'client.monitors.run', - fullyQualifiedName: 'monitors.run', - httpMethod: 'post', - httpPath: '/monitors/{monitor_id}/run', - }, - { - clientCallName: 'client.batch.retrieve', - fullyQualifiedName: 'batch.retrieve', - httpMethod: 'get', - httpPath: '/batch/{batch_id}', - }, - { - clientCallName: 'client.batch.list', - fullyQualifiedName: 'batch.list', - httpMethod: 'get', - httpPath: '/batch/list', - }, - { - clientCallName: 'client.batch.delete', - fullyQualifiedName: 'batch.delete', - httpMethod: 'delete', - httpPath: '/batch/{batch_id}', - }, - { - clientCallName: 'client.batch.cancel', - fullyQualifiedName: 'batch.cancel', - httpMethod: 'post', - httpPath: '/batch/{batch_id}/cancel', - }, - { - clientCallName: 'client.batch.getResults', - fullyQualifiedName: 'batch.getResults', - httpMethod: 'get', - httpPath: '/batch/{batch_id}/results', - }, - { - clientCallName: 'client.batch.submit', - fullyQualifiedName: 'batch.submit', - httpMethod: 'post', - httpPath: '/batch/submit', - }, - { - clientCallName: 'client.people.enrich', - fullyQualifiedName: 'people.enrich', - httpMethod: 'post', - httpPath: '/people/enrich', - }, - { - clientCallName: 'client.news.search', - fullyQualifiedName: 'news.search', - httpMethod: 'post', - httpPath: '/news/search', - }, -]; - -function allowedMethodsForCodeTool(options: McpOptions | undefined): SdkMethod[] | undefined { - if (!options) { - return undefined; - } - - let allowedMethods: SdkMethod[]; - - if (options.codeAllowHttpGets || options.codeAllowedMethods) { - // Start with nothing allowed and then add into it from options - let allowedMethodsSet = new Set(); - - if (options.codeAllowHttpGets) { - // Add all methods that map to an HTTP GET - sdkMethods - .filter((method) => method.httpMethod === 'get') - .forEach((method) => allowedMethodsSet.add(method)); - } - - if (options.codeAllowedMethods) { - // Add all methods that match any of the allowed regexps - const allowedRegexps = options.codeAllowedMethods.map((pattern) => { - try { - return new RegExp(pattern); - } catch (e) { - throw new Error( - `Invalid regex pattern for allowed method: "${pattern}": ${e instanceof Error ? e.message : e}`, - ); - } - }); - - sdkMethods - .filter((method) => allowedRegexps.some((regexp) => regexp.test(method.fullyQualifiedName))) - .forEach((method) => allowedMethodsSet.add(method)); - } - - allowedMethods = Array.from(allowedMethodsSet); - } else { - // Start with everything allowed - allowedMethods = [...sdkMethods]; - } - - if (options.codeBlockedMethods) { - // Filter down based on blocked regexps - const blockedRegexps = options.codeBlockedMethods.map((pattern) => { - try { - return new RegExp(pattern); - } catch (e) { - throw new Error( - `Invalid regex pattern for blocked method: "${pattern}": ${e instanceof Error ? e.message : e}`, - ); - } - }); - - allowedMethods = allowedMethods.filter( - (method) => !blockedRegexps.some((regexp) => regexp.test(method.fullyQualifiedName)), - ); - } - - return allowedMethods; -} - -export function blockedMethodsForCodeTool(options: McpOptions | undefined): SdkMethod[] | undefined { - const allowedMethods = allowedMethodsForCodeTool(options); - if (!allowedMethods) { - return undefined; - } - - const allowedSet = new Set(allowedMethods.map((method) => method.fullyQualifiedName)); - - // Return any methods that are not explicitly allowed - return sdkMethods.filter((method) => !allowedSet.has(method.fullyQualifiedName)); -} diff --git a/packages/mcp-server/src/options.ts b/packages/mcp-server/src/options.ts deleted file mode 100644 index ff817c70..00000000 --- a/packages/mcp-server/src/options.ts +++ /dev/null @@ -1,185 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import qs from 'qs'; -import yargs from 'yargs'; -import { hideBin } from 'yargs/helpers'; -import z from 'zod'; -import { readEnv } from './util'; - -export type CLIOptions = McpOptions & { - debug: boolean; - logFormat: 'json' | 'pretty'; - transport: 'stdio' | 'http'; - port: number | undefined; - socket: string | undefined; -}; - -export type McpOptions = { - includeCodeTool?: boolean | undefined; - includeDocsTools?: boolean | undefined; - stainlessApiKey?: string | undefined; - docsSearchMode?: 'local' | undefined; - docsDir?: string | undefined; - codeAllowHttpGets?: boolean | undefined; - codeAllowedMethods?: string[] | undefined; - codeBlockedMethods?: string[] | undefined; - codeExecutionMode: McpCodeExecutionMode; - customInstructionsPath?: string | undefined; -}; - -export type McpCodeExecutionMode = 'local'; - -export function parseCLIOptions(): CLIOptions { - const opts = yargs(hideBin(process.argv)) - .option('code-allow-http-gets', { - type: 'boolean', - description: - 'Allow all code tool methods that map to HTTP GET operations. If all code-allow-* flags are unset, then everything is allowed.', - }) - .option('code-allowed-methods', { - type: 'string', - array: true, - description: - 'Methods to explicitly allow for code tool. Evaluated as regular expressions against method fully qualified names. If all code-allow-* flags are unset, then everything is allowed.', - }) - .option('code-blocked-methods', { - type: 'string', - array: true, - description: - 'Methods to explicitly block for code tool. Evaluated as regular expressions against method fully qualified names. If all code-allow-* flags are unset, then everything is allowed.', - }) - .option('code-execution-mode', { - type: 'string', - choices: ['local'], - default: 'local', - description: - 'The server was generated without access to the Stainless API, so code execution can only run locally on the MCP server machine.', - }) - .option('custom-instructions-path', { - type: 'string', - description: 'Path to custom instructions for the MCP server', - }) - .option('debug', { type: 'boolean', description: 'Enable debug logging' }) - .option('docs-dir', { - type: 'string', - description: - 'Path to a directory of local documentation files (markdown/JSON) to include in local docs search.', - }) - .option('docs-search-mode', { - type: 'string', - choices: ['local'], - default: 'local', - description: - "Documentation search will use an in-memory search index built from embedded SDK method data and optional local docs files; the 'stainless-api' option is unavailable.", - }) - .option('log-format', { - type: 'string', - choices: ['json', 'pretty'], - description: 'Format for log output; defaults to json unless tty is detected', - }) - .option('no-tools', { - type: 'string', - array: true, - choices: ['code', 'docs'], - description: 'Tools to explicitly disable', - }) - .option('port', { - type: 'number', - default: 3000, - description: 'Port to serve on if using http transport', - }) - .option('socket', { type: 'string', description: 'Unix socket to serve on if using http transport' }) - .option('stainless-api-key', { - type: 'string', - default: readEnv('STAINLESS_API_KEY'), - description: - 'API key for Stainless. Used to authenticate requests to Stainless-hosted tools endpoints.', - }) - .option('tools', { - type: 'string', - array: true, - choices: ['code', 'docs'], - description: 'Tools to explicitly enable', - }) - .option('transport', { - type: 'string', - choices: ['stdio', 'http'], - default: 'stdio', - description: 'What transport to use; stdio for local servers or http for remote servers', - }) - .env('MCP_SERVER') - .version(true) - .help(); - - const argv = opts.parseSync(); - - const shouldIncludeToolType = (toolType: 'code' | 'docs') => - argv.noTools?.includes(toolType) ? false - : argv.tools?.includes(toolType) ? true - : undefined; - - const includeCodeTool = shouldIncludeToolType('code'); - const includeDocsTools = shouldIncludeToolType('docs'); - - const transport = argv.transport as 'stdio' | 'http'; - const logFormat = - argv.logFormat ? (argv.logFormat as 'json' | 'pretty') - : process.stderr.isTTY ? 'pretty' - : 'json'; - - return { - ...(includeCodeTool !== undefined && { includeCodeTool }), - ...(includeDocsTools !== undefined && { includeDocsTools }), - debug: !!argv.debug, - stainlessApiKey: argv.stainlessApiKey, - docsSearchMode: argv.docsSearchMode as 'local' | undefined, - docsDir: argv.docsDir, - codeAllowHttpGets: argv.codeAllowHttpGets, - codeAllowedMethods: argv.codeAllowedMethods, - codeBlockedMethods: argv.codeBlockedMethods, - codeExecutionMode: argv.codeExecutionMode as McpCodeExecutionMode, - customInstructionsPath: argv.customInstructionsPath, - transport, - logFormat, - port: argv.port, - socket: argv.socket, - }; -} - -const coerceArray = (zodType: T) => - z.preprocess( - (val) => - Array.isArray(val) ? val - : val ? [val] - : val, - z.array(zodType).optional(), - ); - -const QueryOptions = z.object({ - tools: coerceArray(z.enum(['code', 'docs'])).describe('Specify which MCP tools to use'), - no_tools: coerceArray(z.enum(['code', 'docs'])).describe('Specify which MCP tools to not use.'), - tool: coerceArray(z.string()).describe('Include tools matching the specified names'), -}); - -export function parseQueryOptions(defaultOptions: McpOptions, query: unknown): McpOptions { - const queryObject = typeof query === 'string' ? qs.parse(query) : query; - const queryOptions = QueryOptions.parse(queryObject); - - let codeTool: boolean | undefined = - queryOptions.no_tools && queryOptions.no_tools?.includes('code') ? false - : queryOptions.tools?.includes('code') ? true - : defaultOptions.includeCodeTool; - - let docsTools: boolean | undefined = - queryOptions.no_tools && queryOptions.no_tools?.includes('docs') ? false - : queryOptions.tools?.includes('docs') ? true - : defaultOptions.includeDocsTools; - - return { - ...(codeTool !== undefined && { includeCodeTool: codeTool }), - ...(docsTools !== undefined && { includeDocsTools: docsTools }), - codeExecutionMode: defaultOptions.codeExecutionMode, - docsSearchMode: defaultOptions.docsSearchMode, - docsDir: defaultOptions.docsDir, - }; -} diff --git a/packages/mcp-server/src/server.ts b/packages/mcp-server/src/server.ts deleted file mode 100644 index 31404104..00000000 --- a/packages/mcp-server/src/server.ts +++ /dev/null @@ -1,208 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { Server } from '@modelcontextprotocol/sdk/server/index.js'; -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { - CallToolRequestSchema, - ListToolsRequestSchema, - SetLevelRequestSchema, -} from '@modelcontextprotocol/sdk/types.js'; -import { ClientOptions } from 'context.dev'; -import ContextDev from 'context.dev'; -import { codeTool } from './code-tool'; -import docsSearchTool from './docs-search-tool'; -import { setLocalSearch } from './docs-search-tool'; -import { LocalDocsSearch } from './local-docs-search'; -import { getInstructions } from './instructions'; -import { McpOptions } from './options'; -import { blockedMethodsForCodeTool } from './methods'; -import { HandlerFunction, McpRequestContext, ToolCallResult, McpTool } from './types'; - -export const newMcpServer = async ({ - stainlessApiKey, - customInstructionsPath, -}: { - stainlessApiKey?: string | undefined; - customInstructionsPath?: string | undefined; -}) => - new McpServer( - { - name: 'context_dev_api', - version: '2.14.0', - }, - { - instructions: await getInstructions({ stainlessApiKey, customInstructionsPath }), - capabilities: { tools: {}, logging: {} }, - }, - ); - -/** - * Initializes the provided MCP Server with the given tools and handlers. - * If not provided, the default client, tools and handlers will be used. - */ -export async function initMcpServer(params: { - server: Server | McpServer; - clientOptions?: ClientOptions; - mcpOptions?: McpOptions; - stainlessApiKey?: string | undefined; - upstreamClientEnvs?: Record | undefined; - mcpSessionId?: string | undefined; - mcpClientInfo?: { name: string; version: string } | undefined; -}) { - const server = params.server instanceof McpServer ? params.server.server : params.server; - - const logAtLevel = - (level: 'debug' | 'info' | 'warning' | 'error') => - (message: string, ...rest: unknown[]) => { - void server.sendLoggingMessage({ - level, - data: { message, rest }, - }); - }; - const logger = { - debug: logAtLevel('debug'), - info: logAtLevel('info'), - warn: logAtLevel('warning'), - error: logAtLevel('error'), - }; - - if (params.mcpOptions?.docsSearchMode === 'local') { - const docsDir = params.mcpOptions?.docsDir; - const localSearch = await LocalDocsSearch.create(docsDir ? { docsDir } : undefined); - setLocalSearch(localSearch); - } - - let _client: ContextDev | undefined; - let _clientError: Error | undefined; - let _logLevel: 'debug' | 'info' | 'warn' | 'error' | 'off' | undefined; - - const getClient = (): ContextDev => { - if (_clientError) throw _clientError; - if (!_client) { - try { - _client = new ContextDev({ - logger, - ...params.clientOptions, - defaultHeaders: { - ...params.clientOptions?.defaultHeaders, - 'X-Stainless-MCP': 'true', - }, - }); - if (_logLevel) { - _client = _client.withOptions({ logLevel: _logLevel }); - } - } catch (e) { - _clientError = e instanceof Error ? e : new Error(String(e)); - throw _clientError; - } - } - return _client; - }; - - const providedTools = selectTools(params.mcpOptions); - const toolMap = Object.fromEntries(providedTools.map((mcpTool) => [mcpTool.tool.name, mcpTool])); - - server.setRequestHandler(ListToolsRequestSchema, async () => { - return { - tools: providedTools.map((mcpTool) => mcpTool.tool), - }; - }); - - server.setRequestHandler(CallToolRequestSchema, async (request) => { - const { name, arguments: args } = request.params; - const mcpTool = toolMap[name]; - if (!mcpTool) { - throw new Error(`Unknown tool: ${name}`); - } - - let client: ContextDev; - try { - client = getClient(); - } catch (error) { - return { - content: [ - { - type: 'text' as const, - text: `Failed to initialize client: ${error instanceof Error ? error.message : String(error)}`, - }, - ], - isError: true, - }; - } - - return executeHandler({ - handler: mcpTool.handler, - reqContext: { - client, - stainlessApiKey: params.stainlessApiKey ?? params.mcpOptions?.stainlessApiKey, - upstreamClientEnvs: params.upstreamClientEnvs, - mcpSessionId: params.mcpSessionId, - mcpClientInfo: params.mcpClientInfo, - }, - args, - }); - }); - - server.setRequestHandler(SetLevelRequestSchema, async (request) => { - const { level } = request.params; - let logLevel: 'debug' | 'info' | 'warn' | 'error' | 'off'; - switch (level) { - case 'debug': - logLevel = 'debug'; - break; - case 'info': - logLevel = 'info'; - break; - case 'notice': - case 'warning': - logLevel = 'warn'; - break; - case 'error': - logLevel = 'error'; - break; - default: - logLevel = 'off'; - break; - } - _logLevel = logLevel; - if (_client) { - _client = _client.withOptions({ logLevel }); - } - return {}; - }); -} - -/** - * Selects the tools to include in the MCP Server based on the provided options. - */ -export function selectTools(options?: McpOptions): McpTool[] { - const includedTools = []; - - if (options?.includeCodeTool ?? true) { - includedTools.push( - codeTool({ - blockedMethods: blockedMethodsForCodeTool(options), - codeExecutionMode: options?.codeExecutionMode ?? 'local', - }), - ); - } - if (options?.includeDocsTools ?? true) { - includedTools.push(docsSearchTool); - } - return includedTools; -} - -/** - * Runs the provided handler with the given client and arguments. - */ -export async function executeHandler({ - handler, - reqContext, - args, -}: { - handler: HandlerFunction; - reqContext: McpRequestContext; - args: Record | undefined; -}): Promise { - return await handler({ reqContext, args: args || {} }); -} diff --git a/packages/mcp-server/src/stdio.ts b/packages/mcp-server/src/stdio.ts deleted file mode 100644 index b04a5441..00000000 --- a/packages/mcp-server/src/stdio.ts +++ /dev/null @@ -1,17 +0,0 @@ -import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; -import { McpOptions } from './options'; -import { initMcpServer, newMcpServer } from './server'; -import { getLogger } from './logger'; - -export const launchStdioServer = async (mcpOptions: McpOptions) => { - const server = await newMcpServer({ - stainlessApiKey: mcpOptions.stainlessApiKey, - customInstructionsPath: mcpOptions.customInstructionsPath, - }); - - await initMcpServer({ server, mcpOptions, stainlessApiKey: mcpOptions.stainlessApiKey }); - - const transport = new StdioServerTransport(); - await server.connect(transport); - getLogger().info('MCP Server running on stdio'); -}; diff --git a/packages/mcp-server/src/types.ts b/packages/mcp-server/src/types.ts deleted file mode 100644 index dd1e4dee..00000000 --- a/packages/mcp-server/src/types.ts +++ /dev/null @@ -1,126 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import ContextDev from 'context.dev'; -import { Tool } from '@modelcontextprotocol/sdk/types.js'; - -type TextContentBlock = { - type: 'text'; - text: string; -}; - -type ImageContentBlock = { - type: 'image'; - data: string; - mimeType: string; -}; - -type AudioContentBlock = { - type: 'audio'; - data: string; - mimeType: string; -}; - -type ResourceContentBlock = { - type: 'resource'; - resource: - | { - uri: string; - mimeType: string; - text: string; - } - | { - uri: string; - mimeType: string; - blob: string; - }; -}; - -export type ContentBlock = TextContentBlock | ImageContentBlock | AudioContentBlock | ResourceContentBlock; - -export type ToolCallResult = { - content: ContentBlock[]; - isError?: boolean; -}; - -export type McpRequestContext = { - client: ContextDev; - stainlessApiKey?: string | undefined; - upstreamClientEnvs?: Record | undefined; - mcpSessionId?: string | undefined; - mcpClientInfo?: { name: string; version: string } | undefined; -}; - -export type HandlerFunction = ({ - reqContext, - args, -}: { - reqContext: McpRequestContext; - args: Record | undefined; -}) => Promise; - -export function asTextContentResult(result: unknown): ToolCallResult { - return { - content: [ - { - type: 'text', - text: JSON.stringify(result, null, 2), - }, - ], - }; -} - -export async function asBinaryContentResult(response: Response): Promise { - const blob = await response.blob(); - const mimeType = blob.type; - const data = Buffer.from(await blob.arrayBuffer()).toString('base64'); - if (mimeType.startsWith('image/')) { - return { - content: [{ type: 'image', mimeType, data }], - }; - } else if (mimeType.startsWith('audio/')) { - return { - content: [{ type: 'audio', mimeType, data }], - }; - } else { - return { - content: [ - { - type: 'resource', - resource: { - // We must give a URI, even though this isn't actually an MCP resource. - uri: 'resource://tool-response', - mimeType, - blob: data, - }, - }, - ], - }; - } -} - -export function asErrorResult(message: string): ToolCallResult { - return { - content: [ - { - type: 'text', - text: message, - }, - ], - isError: true, - }; -} - -export type Metadata = { - resource: string; - operation: 'read' | 'write'; - tags: string[]; - httpMethod?: string; - httpPath?: string; - operationId?: string; -}; - -export type McpTool = { - metadata: Metadata; - tool: Tool; - handler: HandlerFunction; -}; diff --git a/packages/mcp-server/src/util.ts b/packages/mcp-server/src/util.ts deleted file mode 100644 index 069a2b47..00000000 --- a/packages/mcp-server/src/util.ts +++ /dev/null @@ -1,25 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -export const readEnv = (env: string): string | undefined => { - if (typeof (globalThis as any).process !== 'undefined') { - return (globalThis as any).process.env?.[env]?.trim() || undefined; - } else if (typeof (globalThis as any).Deno !== 'undefined') { - return (globalThis as any).Deno.env?.get?.(env)?.trim() || undefined; - } - return; -}; - -export const readEnvOrError = (env: string): string => { - let envValue = readEnv(env); - if (envValue === undefined) { - throw new Error(`Environment variable ${env} is not set`); - } - return envValue; -}; - -export const requireValue = (value: T | undefined, description: string): T => { - if (value === undefined) { - throw new Error(`Missing required value: ${description}`); - } - return value; -}; diff --git a/packages/mcp-server/tests/options.test.ts b/packages/mcp-server/tests/options.test.ts deleted file mode 100644 index 17306295..00000000 --- a/packages/mcp-server/tests/options.test.ts +++ /dev/null @@ -1,32 +0,0 @@ -import { parseCLIOptions } from '../src/options'; - -// Mock process.argv -const mockArgv = (args: string[]) => { - const originalArgv = process.argv; - process.argv = ['node', 'test.js', ...args]; - return () => { - process.argv = originalArgv; - }; -}; - -describe('parseCLIOptions', () => { - it('default parsing should be stdio', () => { - const cleanup = mockArgv([]); - - const result = parseCLIOptions(); - - expect(result.transport).toBe('stdio'); - - cleanup(); - }); - - it('using http transport with a port', () => { - const cleanup = mockArgv(['--transport=http', '--port=2222']); - - const result = parseCLIOptions(); - - expect(result.transport).toBe('http'); - expect(result.port).toBe(2222); - cleanup(); - }); -}); diff --git a/packages/mcp-server/tsc-multi.json b/packages/mcp-server/tsc-multi.json deleted file mode 100644 index 4facad5a..00000000 --- a/packages/mcp-server/tsc-multi.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "targets": [ - { "extname": ".js", "module": "commonjs" }, - { "extname": ".mjs", "module": "esnext" } - ], - "projects": ["tsconfig.build.json"] -} diff --git a/packages/mcp-server/tsconfig.build.json b/packages/mcp-server/tsconfig.build.json deleted file mode 100644 index 28285988..00000000 --- a/packages/mcp-server/tsconfig.build.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "extends": "./tsconfig.json", - "include": ["dist/src"], - "exclude": [], - "compilerOptions": { - "rootDir": "./dist/src", - "paths": { - "context.dev-mcp/*": ["./dist/src/*"], - "context.dev-mcp": ["./dist/src/index.ts"] - }, - "noEmit": false, - "declaration": true, - "declarationMap": true, - "outDir": "dist", - "pretty": true, - "sourceMap": true - } -} diff --git a/packages/mcp-server/tsconfig.dist-src.json b/packages/mcp-server/tsconfig.dist-src.json deleted file mode 100644 index e9f2d70b..00000000 --- a/packages/mcp-server/tsconfig.dist-src.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - // this config is included in the published src directory to prevent TS errors - // from appearing when users go to source, and VSCode opens the source .ts file - // via declaration maps - "include": ["index.ts"], - "compilerOptions": { - "target": "es2015", - "lib": ["DOM"], - "moduleResolution": "node" - } -} diff --git a/packages/mcp-server/tsconfig.json b/packages/mcp-server/tsconfig.json deleted file mode 100644 index dbbee1a6..00000000 --- a/packages/mcp-server/tsconfig.json +++ /dev/null @@ -1,36 +0,0 @@ -{ - "include": ["src", "tests", "examples"], - "exclude": [], - "compilerOptions": { - "target": "es2022", - "lib": ["es2022"], - "module": "commonjs", - "moduleResolution": "node", - "esModuleInterop": true, - "paths": { - "context.dev-mcp/*": ["./src/*"], - "context.dev-mcp": ["./src/index.ts"] - }, - "noEmit": true, - - "resolveJsonModule": true, - - "forceConsistentCasingInFileNames": true, - - "strict": true, - "noImplicitAny": true, - "strictNullChecks": true, - "strictFunctionTypes": true, - "strictBindCallApply": true, - "strictPropertyInitialization": true, - "noImplicitThis": true, - "noImplicitReturns": true, - "alwaysStrict": true, - "exactOptionalPropertyTypes": true, - "noUncheckedIndexedAccess": true, - "noImplicitOverride": true, - "noPropertyAccessFromIndexSignature": true, - - "skipLibCheck": true - } -} diff --git a/packages/mcp-server/yarn.lock b/packages/mcp-server/yarn.lock deleted file mode 100644 index c6b17b02..00000000 --- a/packages/mcp-server/yarn.lock +++ /dev/null @@ -1,4169 +0,0 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. -# yarn lockfile v1 - - -"@anthropic-ai/mcpb@^2.1.2": - version "2.1.2" - resolved "https://registry.yarnpkg.com/@anthropic-ai/mcpb/-/mcpb-2.1.2.tgz#cf02801929734b8810961f22e2eb72758c27d527" - integrity sha512-goRbBC8ySo7SWb7tRzr+tL6FxDc4JPTRCdgfD2omba7freofvjq5rom1lBnYHZHo6Mizs1jAHJeN53aZbDoy8A== - dependencies: - "@inquirer/prompts" "^6.0.1" - commander "^13.1.0" - fflate "^0.8.2" - galactus "^1.0.0" - ignore "^7.0.5" - node-forge "^1.3.2" - pretty-bytes "^5.6.0" - zod "^3.25.67" - zod-to-json-schema "^3.24.6" - -"@babel/code-frame@^7.0.0", "@babel/code-frame@^7.12.13", "@babel/code-frame@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/code-frame/-/code-frame-7.28.6.tgz#72499312ec58b1e2245ba4a4f550c132be4982f7" - integrity sha512-JYgintcMjRiCvS8mMECzaEn+m3PfoQiyqukOMCCVQtoJGYJw8j/8LBJEiqkHLkfwCcs74E3pbAUFNg7d9VNJ+Q== - dependencies: - "@babel/helper-validator-identifier" "^7.28.5" - js-tokens "^4.0.0" - picocolors "^1.1.1" - -"@babel/compat-data@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/compat-data/-/compat-data-7.28.6.tgz#103f466803fa0f059e82ccac271475470570d74c" - integrity sha512-2lfu57JtzctfIrcGMz992hyLlByuzgIk58+hhGCxjKZ3rWI82NnVLjXcaTqkI2NvlcvOskZaiZ5kjUALo3Lpxg== - -"@babel/core@^7.11.6", "@babel/core@^7.12.3", "@babel/core@^7.23.9": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/core/-/core-7.28.6.tgz#531bf883a1126e53501ba46eb3bb414047af507f" - integrity sha512-H3mcG6ZDLTlYfaSNi0iOKkigqMFvkTKlGUYlD8GW7nNOYRrevuA46iTypPyv+06V3fEmvvazfntkBU34L0azAw== - dependencies: - "@babel/code-frame" "^7.28.6" - "@babel/generator" "^7.28.6" - "@babel/helper-compilation-targets" "^7.28.6" - "@babel/helper-module-transforms" "^7.28.6" - "@babel/helpers" "^7.28.6" - "@babel/parser" "^7.28.6" - "@babel/template" "^7.28.6" - "@babel/traverse" "^7.28.6" - "@babel/types" "^7.28.6" - "@jridgewell/remapping" "^2.3.5" - convert-source-map "^2.0.0" - debug "^4.1.0" - gensync "^1.0.0-beta.2" - json5 "^2.2.3" - semver "^6.3.1" - -"@babel/generator@^7.28.6", "@babel/generator@^7.7.2": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/generator/-/generator-7.28.6.tgz#48dcc65d98fcc8626a48f72b62e263d25fc3c3f1" - integrity sha512-lOoVRwADj8hjf7al89tvQ2a1lf53Z+7tiXMgpZJL3maQPDxh0DgLMN62B2MKUOFcoodBHLMbDM6WAbKgNy5Suw== - dependencies: - "@babel/parser" "^7.28.6" - "@babel/types" "^7.28.6" - "@jridgewell/gen-mapping" "^0.3.12" - "@jridgewell/trace-mapping" "^0.3.28" - jsesc "^3.0.2" - -"@babel/helper-compilation-targets@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/helper-compilation-targets/-/helper-compilation-targets-7.28.6.tgz#32c4a3f41f12ed1532179b108a4d746e105c2b25" - integrity sha512-JYtls3hqi15fcx5GaSNL7SCTJ2MNmjrkHXg4FSpOA/grxK8KwyZ5bubHsCq8FXCkua6xhuaaBit+3b7+VZRfcA== - dependencies: - "@babel/compat-data" "^7.28.6" - "@babel/helper-validator-option" "^7.27.1" - browserslist "^4.24.0" - lru-cache "^5.1.1" - semver "^6.3.1" - -"@babel/helper-globals@^7.28.0": - version "7.28.0" - resolved "https://registry.yarnpkg.com/@babel/helper-globals/-/helper-globals-7.28.0.tgz#b9430df2aa4e17bc28665eadeae8aa1d985e6674" - integrity sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw== - -"@babel/helper-module-imports@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/helper-module-imports/-/helper-module-imports-7.28.6.tgz#60632cbd6ffb70b22823187201116762a03e2d5c" - integrity sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw== - dependencies: - "@babel/traverse" "^7.28.6" - "@babel/types" "^7.28.6" - -"@babel/helper-module-transforms@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/helper-module-transforms/-/helper-module-transforms-7.28.6.tgz#9312d9d9e56edc35aeb6e95c25d4106b50b9eb1e" - integrity sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA== - dependencies: - "@babel/helper-module-imports" "^7.28.6" - "@babel/helper-validator-identifier" "^7.28.5" - "@babel/traverse" "^7.28.6" - -"@babel/helper-plugin-utils@^7.0.0", "@babel/helper-plugin-utils@^7.10.4", "@babel/helper-plugin-utils@^7.12.13", "@babel/helper-plugin-utils@^7.14.5", "@babel/helper-plugin-utils@^7.28.6", "@babel/helper-plugin-utils@^7.8.0": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/helper-plugin-utils/-/helper-plugin-utils-7.28.6.tgz#6f13ea251b68c8532e985fd532f28741a8af9ac8" - integrity sha512-S9gzZ/bz83GRysI7gAD4wPT/AI3uCnY+9xn+Mx/KPs2JwHJIz1W8PZkg2cqyt3RNOBM8ejcXhV6y8Og7ly/Dug== - -"@babel/helper-string-parser@^7.27.1": - version "7.27.1" - resolved "https://registry.yarnpkg.com/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz#54da796097ab19ce67ed9f88b47bb2ec49367687" - integrity sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA== - -"@babel/helper-validator-identifier@^7.28.5": - version "7.28.5" - resolved "https://registry.yarnpkg.com/@babel/helper-validator-identifier/-/helper-validator-identifier-7.28.5.tgz#010b6938fab7cb7df74aa2bbc06aa503b8fe5fb4" - integrity sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q== - -"@babel/helper-validator-option@^7.27.1": - version "7.27.1" - resolved "https://registry.yarnpkg.com/@babel/helper-validator-option/-/helper-validator-option-7.27.1.tgz#fa52f5b1e7db1ab049445b421c4471303897702f" - integrity sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg== - -"@babel/helpers@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/helpers/-/helpers-7.28.6.tgz#fca903a313ae675617936e8998b814c415cbf5d7" - integrity sha512-xOBvwq86HHdB7WUDTfKfT/Vuxh7gElQ+Sfti2Cy6yIWNW05P8iUslOVcZ4/sKbE+/jQaukQAdz/gf3724kYdqw== - dependencies: - "@babel/template" "^7.28.6" - "@babel/types" "^7.28.6" - -"@babel/parser@^7.1.0", "@babel/parser@^7.14.7", "@babel/parser@^7.20.7", "@babel/parser@^7.23.9", "@babel/parser@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/parser/-/parser-7.28.6.tgz#f01a8885b7fa1e56dd8a155130226cd698ef13fd" - integrity sha512-TeR9zWR18BvbfPmGbLampPMW+uW1NZnJlRuuHso8i87QZNq2JRF9i6RgxRqtEq+wQGsS19NNTWr2duhnE49mfQ== - dependencies: - "@babel/types" "^7.28.6" - -"@babel/plugin-syntax-async-generators@^7.8.4": - version "7.8.4" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-async-generators/-/plugin-syntax-async-generators-7.8.4.tgz#a983fb1aeb2ec3f6ed042a210f640e90e786fe0d" - integrity sha512-tycmZxkGfZaxhMRbXlPXuVFpdWlXpir2W4AMhSJgRKzk/eDlIXOhb2LHWoLpDF7TEHylV5zNhykX6KAgHJmTNw== - dependencies: - "@babel/helper-plugin-utils" "^7.8.0" - -"@babel/plugin-syntax-bigint@^7.8.3": - version "7.8.3" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-bigint/-/plugin-syntax-bigint-7.8.3.tgz#4c9a6f669f5d0cdf1b90a1671e9a146be5300cea" - integrity sha512-wnTnFlG+YxQm3vDxpGE57Pj0srRU4sHE/mDkt1qv2YJJSeUAec2ma4WLUnUPeKjyrfntVwe/N6dCXpU+zL3Npg== - dependencies: - "@babel/helper-plugin-utils" "^7.8.0" - -"@babel/plugin-syntax-class-properties@^7.12.13": - version "7.12.13" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-class-properties/-/plugin-syntax-class-properties-7.12.13.tgz#b5c987274c4a3a82b89714796931a6b53544ae10" - integrity sha512-fm4idjKla0YahUNgFNLCB0qySdsoPiZP3iQE3rky0mBUtMZ23yDJ9SJdg6dXTSDnulOVqiF3Hgr9nbXvXTQZYA== - dependencies: - "@babel/helper-plugin-utils" "^7.12.13" - -"@babel/plugin-syntax-class-static-block@^7.14.5": - version "7.14.5" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-class-static-block/-/plugin-syntax-class-static-block-7.14.5.tgz#195df89b146b4b78b3bf897fd7a257c84659d406" - integrity sha512-b+YyPmr6ldyNnM6sqYeMWE+bgJcJpO6yS4QD7ymxgH34GBPNDM/THBh8iunyvKIZztiwLH4CJZ0RxTk9emgpjw== - dependencies: - "@babel/helper-plugin-utils" "^7.14.5" - -"@babel/plugin-syntax-import-attributes@^7.24.7": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-import-attributes/-/plugin-syntax-import-attributes-7.28.6.tgz#b71d5914665f60124e133696f17cd7669062c503" - integrity sha512-jiLC0ma9XkQT3TKJ9uYvlakm66Pamywo+qwL+oL8HJOvc6TWdZXVfhqJr8CCzbSGUAbDOzlGHJC1U+vRfLQDvw== - dependencies: - "@babel/helper-plugin-utils" "^7.28.6" - -"@babel/plugin-syntax-import-meta@^7.10.4": - version "7.10.4" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-import-meta/-/plugin-syntax-import-meta-7.10.4.tgz#ee601348c370fa334d2207be158777496521fd51" - integrity sha512-Yqfm+XDx0+Prh3VSeEQCPU81yC+JWZ2pDPFSS4ZdpfZhp4MkFMaDC1UqseovEKwSUpnIL7+vK+Clp7bfh0iD7g== - dependencies: - "@babel/helper-plugin-utils" "^7.10.4" - -"@babel/plugin-syntax-json-strings@^7.8.3": - version "7.8.3" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-json-strings/-/plugin-syntax-json-strings-7.8.3.tgz#01ca21b668cd8218c9e640cb6dd88c5412b2c96a" - integrity sha512-lY6kdGpWHvjoe2vk4WrAapEuBR69EMxZl+RoGRhrFGNYVK8mOPAW8VfbT/ZgrFbXlDNiiaxQnAtgVCZ6jv30EA== - dependencies: - "@babel/helper-plugin-utils" "^7.8.0" - -"@babel/plugin-syntax-jsx@^7.7.2": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-jsx/-/plugin-syntax-jsx-7.28.6.tgz#f8ca28bbd84883b5fea0e447c635b81ba73997ee" - integrity sha512-wgEmr06G6sIpqr8YDwA2dSRTE3bJ+V0IfpzfSY3Lfgd7YWOaAdlykvJi13ZKBt8cZHfgH1IXN+CL656W3uUa4w== - dependencies: - "@babel/helper-plugin-utils" "^7.28.6" - -"@babel/plugin-syntax-logical-assignment-operators@^7.10.4": - version "7.10.4" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-logical-assignment-operators/-/plugin-syntax-logical-assignment-operators-7.10.4.tgz#ca91ef46303530448b906652bac2e9fe9941f699" - integrity sha512-d8waShlpFDinQ5MtvGU9xDAOzKH47+FFoney2baFIoMr952hKOLp1HR7VszoZvOsV/4+RRszNY7D17ba0te0ig== - dependencies: - "@babel/helper-plugin-utils" "^7.10.4" - -"@babel/plugin-syntax-nullish-coalescing-operator@^7.8.3": - version "7.8.3" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-nullish-coalescing-operator/-/plugin-syntax-nullish-coalescing-operator-7.8.3.tgz#167ed70368886081f74b5c36c65a88c03b66d1a9" - integrity sha512-aSff4zPII1u2QD7y+F8oDsz19ew4IGEJg9SVW+bqwpwtfFleiQDMdzA/R+UlWDzfnHFCxxleFT0PMIrR36XLNQ== - dependencies: - "@babel/helper-plugin-utils" "^7.8.0" - -"@babel/plugin-syntax-numeric-separator@^7.10.4": - version "7.10.4" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-numeric-separator/-/plugin-syntax-numeric-separator-7.10.4.tgz#b9b070b3e33570cd9fd07ba7fa91c0dd37b9af97" - integrity sha512-9H6YdfkcK/uOnY/K7/aA2xpzaAgkQn37yzWUMRK7OaPOqOpGS1+n0H5hxT9AUw9EsSjPW8SVyMJwYRtWs3X3ug== - dependencies: - "@babel/helper-plugin-utils" "^7.10.4" - -"@babel/plugin-syntax-object-rest-spread@^7.8.3": - version "7.8.3" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-object-rest-spread/-/plugin-syntax-object-rest-spread-7.8.3.tgz#60e225edcbd98a640332a2e72dd3e66f1af55871" - integrity sha512-XoqMijGZb9y3y2XskN+P1wUGiVwWZ5JmoDRwx5+3GmEplNyVM2s2Dg8ILFQm8rWM48orGy5YpI5Bl8U1y7ydlA== - dependencies: - "@babel/helper-plugin-utils" "^7.8.0" - -"@babel/plugin-syntax-optional-catch-binding@^7.8.3": - version "7.8.3" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-optional-catch-binding/-/plugin-syntax-optional-catch-binding-7.8.3.tgz#6111a265bcfb020eb9efd0fdfd7d26402b9ed6c1" - integrity sha512-6VPD0Pc1lpTqw0aKoeRTMiB+kWhAoT24PA+ksWSBrFtl5SIRVpZlwN3NNPQjehA2E/91FV3RjLWoVTglWcSV3Q== - dependencies: - "@babel/helper-plugin-utils" "^7.8.0" - -"@babel/plugin-syntax-optional-chaining@^7.8.3": - version "7.8.3" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-optional-chaining/-/plugin-syntax-optional-chaining-7.8.3.tgz#4f69c2ab95167e0180cd5336613f8c5788f7d48a" - integrity sha512-KoK9ErH1MBlCPxV0VANkXW2/dw4vlbGDrFgz8bmUsBGYkFRcbRwMh6cIJubdPrkxRwuGdtCk0v/wPTKbQgBjkg== - dependencies: - "@babel/helper-plugin-utils" "^7.8.0" - -"@babel/plugin-syntax-private-property-in-object@^7.14.5": - version "7.14.5" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-private-property-in-object/-/plugin-syntax-private-property-in-object-7.14.5.tgz#0dc6671ec0ea22b6e94a1114f857970cd39de1ad" - integrity sha512-0wVnp9dxJ72ZUJDV27ZfbSj6iHLoytYZmh3rFcxNnvsJF3ktkzLDZPy/mA17HGsaQT3/DQsWYX1f1QGWkCoVUg== - dependencies: - "@babel/helper-plugin-utils" "^7.14.5" - -"@babel/plugin-syntax-top-level-await@^7.14.5": - version "7.14.5" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-top-level-await/-/plugin-syntax-top-level-await-7.14.5.tgz#c1cfdadc35a646240001f06138247b741c34d94c" - integrity sha512-hx++upLv5U1rgYfwe1xBQUhRmU41NEvpUvrp8jkrSCdvGSnM5/qdRMtylJ6PG5OFkBaHkbTAKTnd3/YyESRHFw== - dependencies: - "@babel/helper-plugin-utils" "^7.14.5" - -"@babel/plugin-syntax-typescript@^7.7.2": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-typescript/-/plugin-syntax-typescript-7.28.6.tgz#c7b2ddf1d0a811145b1de800d1abd146af92e3a2" - integrity sha512-+nDNmQye7nlnuuHDboPbGm00Vqg3oO8niRRL27/4LYHUsHYh0zJ1xWOz0uRwNFmM1Avzk8wZbc6rdiYhomzv/A== - dependencies: - "@babel/helper-plugin-utils" "^7.28.6" - -"@babel/template@^7.28.6", "@babel/template@^7.3.3": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/template/-/template-7.28.6.tgz#0e7e56ecedb78aeef66ce7972b082fce76a23e57" - integrity sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ== - dependencies: - "@babel/code-frame" "^7.28.6" - "@babel/parser" "^7.28.6" - "@babel/types" "^7.28.6" - -"@babel/traverse@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/traverse/-/traverse-7.28.6.tgz#871ddc79a80599a5030c53b1cc48cbe3a5583c2e" - integrity sha512-fgWX62k02qtjqdSNTAGxmKYY/7FSL9WAS1o2Hu5+I5m9T0yxZzr4cnrfXQ/MX0rIifthCSs6FKTlzYbJcPtMNg== - dependencies: - "@babel/code-frame" "^7.28.6" - "@babel/generator" "^7.28.6" - "@babel/helper-globals" "^7.28.0" - "@babel/parser" "^7.28.6" - "@babel/template" "^7.28.6" - "@babel/types" "^7.28.6" - debug "^4.3.1" - -"@babel/types@^7.0.0", "@babel/types@^7.20.7", "@babel/types@^7.28.2", "@babel/types@^7.28.6", "@babel/types@^7.3.3": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/types/-/types-7.28.6.tgz#c3e9377f1b155005bcc4c46020e7e394e13089df" - integrity sha512-0ZrskXVEHSWIqZM/sQZ4EV3jZJXRkio/WCxaqKZP1g//CEWEPSfeZFcms4XeKBCHU0ZKnIkdJeU/kF+eRp5lBg== - dependencies: - "@babel/helper-string-parser" "^7.27.1" - "@babel/helper-validator-identifier" "^7.28.5" - -"@bcoe/v8-coverage@^0.2.3": - version "0.2.3" - resolved "https://registry.yarnpkg.com/@bcoe/v8-coverage/-/v8-coverage-0.2.3.tgz#75a2e8b51cb758a7553d6804a5932d7aace75c39" - integrity sha512-0hYQ8SB4Db5zvZB4axdMHGwEaQjkZzFjQiN9LVYvIFB2nSUHW9tYpxWriPrWDASIxiaXax83REcLxuSdnGPZtw== - -"@cloudflare/cabidela@^0.2.4": - version "0.2.4" - resolved "https://registry.yarnpkg.com/@cloudflare/cabidela/-/cabidela-0.2.4.tgz#9a3e9212e636a24d796a8f16741c24885b326a1a" - integrity sha512-u/1OwwqfcMvjmUFOcb6QtFzVVGpncHJxwl254wjzp0JC5CUlBkV6r5BbRrHI5ZYJEAgu8NeeorirxngmMFPZjQ== - -"@cspotcode/source-map-support@^0.8.0": - version "0.8.1" - resolved "https://registry.yarnpkg.com/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz#00629c35a688e05a88b1cda684fb9d5e73f000a1" - integrity sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw== - dependencies: - "@jridgewell/trace-mapping" "0.3.9" - -"@eslint-community/eslint-utils@^4.4.0", "@eslint-community/eslint-utils@^4.8.0": - version "4.9.1" - resolved "https://registry.yarnpkg.com/@eslint-community/eslint-utils/-/eslint-utils-4.9.1.tgz#4e90af67bc51ddee6cdef5284edf572ec376b595" - integrity sha512-phrYmNiYppR7znFEdqgfWHXR6NCkZEK7hwWDHZUjit/2/U0r6XvkDl0SYnoM51Hq7FhCGdLDT6zxCCOY1hexsQ== - dependencies: - eslint-visitor-keys "^3.4.3" - -"@eslint-community/regexpp@^4.10.0", "@eslint-community/regexpp@^4.12.1": - version "4.12.2" - resolved "https://registry.yarnpkg.com/@eslint-community/regexpp/-/regexpp-4.12.2.tgz#bccdf615bcf7b6e8db830ec0b8d21c9a25de597b" - integrity sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew== - -"@eslint/config-array@^0.21.2": - version "0.21.2" - resolved "https://registry.yarnpkg.com/@eslint/config-array/-/config-array-0.21.2.tgz#f29e22057ad5316cf23836cee9a34c81fffcb7e6" - integrity sha512-nJl2KGTlrf9GjLimgIru+V/mzgSK0ABCDQRvxw5BjURL7WfH5uoWmizbH7QB6MmnMBd8cIC9uceWnezL1VZWWw== - dependencies: - "@eslint/object-schema" "^2.1.7" - debug "^4.3.1" - minimatch "^3.1.5" - -"@eslint/config-helpers@^0.4.2": - version "0.4.2" - resolved "https://registry.yarnpkg.com/@eslint/config-helpers/-/config-helpers-0.4.2.tgz#1bd006ceeb7e2e55b2b773ab318d300e1a66aeda" - integrity sha512-gBrxN88gOIf3R7ja5K9slwNayVcZgK6SOUORm2uBzTeIEfeVaIhOpCtTox3P6R7o2jLFwLFTLnC7kU/RGcYEgw== - dependencies: - "@eslint/core" "^0.17.0" - -"@eslint/core@^0.17.0": - version "0.17.0" - resolved "https://registry.yarnpkg.com/@eslint/core/-/core-0.17.0.tgz#77225820413d9617509da9342190a2019e78761c" - integrity sha512-yL/sLrpmtDaFEiUj1osRP4TI2MDz1AddJL+jZ7KSqvBuliN4xqYY54IfdN8qD8Toa6g1iloph1fxQNkjOxrrpQ== - dependencies: - "@types/json-schema" "^7.0.15" - -"@eslint/eslintrc@^3.3.5": - version "3.3.5" - resolved "https://registry.yarnpkg.com/@eslint/eslintrc/-/eslintrc-3.3.5.tgz#c131793cfc1a7b96f24a83e0a8bbd4b881558c60" - integrity sha512-4IlJx0X0qftVsN5E+/vGujTRIFtwuLbNsVUe7TO6zYPDR1O6nFwvwhIKEKSrl6dZchmYBITazxKoUYOjdtjlRg== - dependencies: - ajv "^6.14.0" - debug "^4.3.2" - espree "^10.0.1" - globals "^14.0.0" - ignore "^5.2.0" - import-fresh "^3.2.1" - js-yaml "^4.1.1" - minimatch "^3.1.5" - strip-json-comments "^3.1.1" - -"@eslint/js@9.39.4": - version "9.39.4" - resolved "https://registry.yarnpkg.com/@eslint/js/-/js-9.39.4.tgz#a3f83bfc6fd9bf33a853dfacd0b49b398eb596c1" - integrity sha512-nE7DEIchvtiFTwBw4Lfbu59PG+kCofhjsKaCWzxTpt4lfRjRMqG6uMBzKXuEcyXhOHoUp9riAm7/aWYGhXZ9cw== - -"@eslint/object-schema@^2.1.7": - version "2.1.7" - resolved "https://registry.yarnpkg.com/@eslint/object-schema/-/object-schema-2.1.7.tgz#6e2126a1347e86a4dedf8706ec67ff8e107ebbad" - integrity sha512-VtAOaymWVfZcmZbp6E2mympDIHvyjXs/12LqWYjVw6qjrfF+VK+fyG33kChz3nnK+SU5/NeHOqrTEHS8sXO3OA== - -"@eslint/plugin-kit@^0.4.1": - version "0.4.1" - resolved "https://registry.yarnpkg.com/@eslint/plugin-kit/-/plugin-kit-0.4.1.tgz#9779e3fd9b7ee33571a57435cf4335a1794a6cb2" - integrity sha512-43/qtrDUokr7LJqoF2c3+RInu/t4zfrpYdoSDfYyhg52rwLV6TnOvdG4fXm7IkSB3wErkcmJS9iEhjVtOSEjjA== - dependencies: - "@eslint/core" "^0.17.0" - levn "^0.4.1" - -"@hono/node-server@^1.19.10", "@hono/node-server@^1.19.9": - version "1.19.11" - resolved "https://registry.yarnpkg.com/@hono/node-server/-/node-server-1.19.11.tgz#dc419f0826dd2504e9fc86ad289d5636a0444e2f" - integrity sha512-dr8/3zEaB+p0D2n/IUrlPF1HZm586qgJNXK1a9fhg/PzdtkK7Ksd5l312tJX2yBuALqDYBlG20QEbayqPyxn+g== - -"@humanfs/core@^0.19.1": - version "0.19.1" - resolved "https://registry.yarnpkg.com/@humanfs/core/-/core-0.19.1.tgz#17c55ca7d426733fe3c561906b8173c336b40a77" - integrity sha512-5DyQ4+1JEUzejeK1JGICcideyfUbGixgS9jNgex5nqkW+cY7WZhxBigmieN5Qnw9ZosSNVC9KQKyb+GUaGyKUA== - -"@humanfs/node@^0.16.6": - version "0.16.7" - resolved "https://registry.yarnpkg.com/@humanfs/node/-/node-0.16.7.tgz#822cb7b3a12c5a240a24f621b5a2413e27a45f26" - integrity sha512-/zUx+yOsIrG4Y43Eh2peDeKCxlRt/gET6aHfaKpuq267qXdYDFViVHfMaLyygZOnl0kGWxFIgsBy8QFuTLUXEQ== - dependencies: - "@humanfs/core" "^0.19.1" - "@humanwhocodes/retry" "^0.4.0" - -"@humanwhocodes/module-importer@^1.0.1": - version "1.0.1" - resolved "https://registry.yarnpkg.com/@humanwhocodes/module-importer/-/module-importer-1.0.1.tgz#af5b2691a22b44be847b0ca81641c5fb6ad0172c" - integrity sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA== - -"@humanwhocodes/retry@^0.4.0", "@humanwhocodes/retry@^0.4.2": - version "0.4.3" - resolved "https://registry.yarnpkg.com/@humanwhocodes/retry/-/retry-0.4.3.tgz#c2b9d2e374ee62c586d3adbea87199b1d7a7a6ba" - integrity sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ== - -"@inquirer/checkbox@^3.0.1": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/checkbox/-/checkbox-3.0.1.tgz#0a57f704265f78c36e17f07e421b98efb4b9867b" - integrity sha512-0hm2nrToWUdD6/UHnel/UKGdk1//ke5zGUpHIvk5ZWmaKezlGxZkOJXNSWsdxO/rEqTkbB3lNC2J6nBElV2aAQ== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/figures" "^1.0.6" - "@inquirer/type" "^2.0.0" - ansi-escapes "^4.3.2" - yoctocolors-cjs "^2.1.2" - -"@inquirer/confirm@^4.0.1": - version "4.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/confirm/-/confirm-4.0.1.tgz#9106d6bffa0b2fdd0e4f60319b6f04f2e06e6e25" - integrity sha512-46yL28o2NJ9doViqOy0VDcoTzng7rAb6yPQKU7VDLqkmbCaH4JqK4yk4XqlzNWy9PVC5pG1ZUXPBQv+VqnYs2w== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/type" "^2.0.0" - -"@inquirer/core@^9.2.1": - version "9.2.1" - resolved "https://registry.yarnpkg.com/@inquirer/core/-/core-9.2.1.tgz#677c49dee399c9063f31e0c93f0f37bddc67add1" - integrity sha512-F2VBt7W/mwqEU4bL0RnHNZmC/OxzNx9cOYxHqnXX3MP6ruYvZUZAW9imgN9+h/uBT/oP8Gh888J2OZSbjSeWcg== - dependencies: - "@inquirer/figures" "^1.0.6" - "@inquirer/type" "^2.0.0" - "@types/mute-stream" "^0.0.4" - "@types/node" "^22.5.5" - "@types/wrap-ansi" "^3.0.0" - ansi-escapes "^4.3.2" - cli-width "^4.1.0" - mute-stream "^1.0.0" - signal-exit "^4.1.0" - strip-ansi "^6.0.1" - wrap-ansi "^6.2.0" - yoctocolors-cjs "^2.1.2" - -"@inquirer/editor@^3.0.1": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/editor/-/editor-3.0.1.tgz#d109f21e050af6b960725388cb1c04214ed7c7bc" - integrity sha512-VA96GPFaSOVudjKFraokEEmUQg/Lub6OXvbIEZU1SDCmBzRkHGhxoFAVaF30nyiB4m5cEbDgiI2QRacXZ2hw9Q== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/type" "^2.0.0" - external-editor "^3.1.0" - -"@inquirer/expand@^3.0.1": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/expand/-/expand-3.0.1.tgz#aed9183cac4d12811be47a4a895ea8e82a17e22c" - integrity sha512-ToG8d6RIbnVpbdPdiN7BCxZGiHOTomOX94C2FaT5KOHupV40tKEDozp12res6cMIfRKrXLJyexAZhWVHgbALSQ== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/type" "^2.0.0" - yoctocolors-cjs "^2.1.2" - -"@inquirer/figures@^1.0.6": - version "1.0.15" - resolved "https://registry.yarnpkg.com/@inquirer/figures/-/figures-1.0.15.tgz#dbb49ed80df11df74268023b496ac5d9acd22b3a" - integrity sha512-t2IEY+unGHOzAaVM5Xx6DEWKeXlDDcNPeDyUpsRc6CUhBfU3VQOEl+Vssh7VNp1dR8MdUJBWhuObjXCsVpjN5g== - -"@inquirer/input@^3.0.1": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/input/-/input-3.0.1.tgz#de63d49e516487388508d42049deb70f2cb5f28e" - integrity sha512-BDuPBmpvi8eMCxqC5iacloWqv+5tQSJlUafYWUe31ow1BVXjW2a5qe3dh4X/Z25Wp22RwvcaLCc2siHobEOfzg== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/type" "^2.0.0" - -"@inquirer/number@^2.0.1": - version "2.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/number/-/number-2.0.1.tgz#b9863080d02ab7dc2e56e16433d83abea0f2a980" - integrity sha512-QpR8jPhRjSmlr/mD2cw3IR8HRO7lSVOnqUvQa8scv1Lsr3xoAMMworcYW3J13z3ppjBFBD2ef1Ci6AE5Qn8goQ== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/type" "^2.0.0" - -"@inquirer/password@^3.0.1": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/password/-/password-3.0.1.tgz#2a9a9143591088336bbd573bcb05d5bf080dbf87" - integrity sha512-haoeEPUisD1NeE2IanLOiFr4wcTXGWrBOyAyPZi1FfLJuXOzNmxCJPgUrGYKVh+Y8hfGJenIfz5Wb/DkE9KkMQ== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/type" "^2.0.0" - ansi-escapes "^4.3.2" - -"@inquirer/prompts@^6.0.1": - version "6.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/prompts/-/prompts-6.0.1.tgz#43f5c0ed35c5ebfe52f1d43d46da2d363d950071" - integrity sha512-yl43JD/86CIj3Mz5mvvLJqAOfIup7ncxfJ0Btnl0/v5TouVUyeEdcpknfgc+yMevS/48oH9WAkkw93m7otLb/A== - dependencies: - "@inquirer/checkbox" "^3.0.1" - "@inquirer/confirm" "^4.0.1" - "@inquirer/editor" "^3.0.1" - "@inquirer/expand" "^3.0.1" - "@inquirer/input" "^3.0.1" - "@inquirer/number" "^2.0.1" - "@inquirer/password" "^3.0.1" - "@inquirer/rawlist" "^3.0.1" - "@inquirer/search" "^2.0.1" - "@inquirer/select" "^3.0.1" - -"@inquirer/rawlist@^3.0.1": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/rawlist/-/rawlist-3.0.1.tgz#729def358419cc929045f264131878ed379e0af3" - integrity sha512-VgRtFIwZInUzTiPLSfDXK5jLrnpkuSOh1ctfaoygKAdPqjcjKYmGh6sCY1pb0aGnCGsmhUxoqLDUAU0ud+lGXQ== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/type" "^2.0.0" - yoctocolors-cjs "^2.1.2" - -"@inquirer/search@^2.0.1": - version "2.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/search/-/search-2.0.1.tgz#69b774a0a826de2e27b48981d01bc5ad81e73721" - integrity sha512-r5hBKZk3g5MkIzLVoSgE4evypGqtOannnB3PKTG9NRZxyFRKcfzrdxXXPcoJQsxJPzvdSU2Rn7pB7lw0GCmGAg== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/figures" "^1.0.6" - "@inquirer/type" "^2.0.0" - yoctocolors-cjs "^2.1.2" - -"@inquirer/select@^3.0.1": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/select/-/select-3.0.1.tgz#1df9ed27fb85a5f526d559ac5ce7cc4e9dc4e7ec" - integrity sha512-lUDGUxPhdWMkN/fHy1Lk7pF3nK1fh/gqeyWXmctefhxLYxlDsc7vsPBEpxrfVGDsVdyYJsiJoD4bJ1b623cV1Q== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/figures" "^1.0.6" - "@inquirer/type" "^2.0.0" - ansi-escapes "^4.3.2" - yoctocolors-cjs "^2.1.2" - -"@inquirer/type@^2.0.0": - version "2.0.0" - resolved "https://registry.yarnpkg.com/@inquirer/type/-/type-2.0.0.tgz#08fa513dca2cb6264fe1b0a2fabade051444e3f6" - integrity sha512-XvJRx+2KR3YXyYtPUUy+qd9i7p+GO9Ko6VIIpWlBrpWwXDv8WLFeHTxz35CfQFUiBMLXlGHhGzys7lqit9gWag== - dependencies: - mute-stream "^1.0.0" - -"@istanbuljs/load-nyc-config@^1.0.0": - version "1.1.0" - resolved "https://registry.yarnpkg.com/@istanbuljs/load-nyc-config/-/load-nyc-config-1.1.0.tgz#fd3db1d59ecf7cf121e80650bb86712f9b55eced" - integrity sha512-VjeHSlIzpv/NyD3N0YuHfXOPDIixcA1q2ZV98wsMqcYlPmv2n3Yb2lYP9XMElnaFVXg5A7YLTeLu6V84uQDjmQ== - dependencies: - camelcase "^5.3.1" - find-up "^4.1.0" - get-package-type "^0.1.0" - js-yaml "^3.13.1" - resolve-from "^5.0.0" - -"@istanbuljs/schema@^0.1.2", "@istanbuljs/schema@^0.1.3": - version "0.1.3" - resolved "https://registry.yarnpkg.com/@istanbuljs/schema/-/schema-0.1.3.tgz#e45e384e4b8ec16bce2fd903af78450f6bf7ec98" - integrity sha512-ZXRY4jNvVgSVQ8DL3LTcakaAtXwTVUxE81hslsyD2AtoXW/wVob10HkOJ1X/pAlcI7D+2YoZKg5do8G/w6RYgA== - -"@jest/console@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/console/-/console-29.7.0.tgz#cd4822dbdb84529265c5a2bdb529a3c9cc950ffc" - integrity sha512-5Ni4CU7XHQi32IJ398EEP4RrB8eV09sXP2ROqD4bksHrnTree52PsxvX8tpL8LvTZ3pFzXyPbNQReSN41CAhOg== - dependencies: - "@jest/types" "^29.6.3" - "@types/node" "*" - chalk "^4.0.0" - jest-message-util "^29.7.0" - jest-util "^29.7.0" - slash "^3.0.0" - -"@jest/core@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/core/-/core-29.7.0.tgz#b6cccc239f30ff36609658c5a5e2291757ce448f" - integrity sha512-n7aeXWKMnGtDA48y8TLWJPJmLmmZ642Ceo78cYWEpiD7FzDgmNDV/GCVRorPABdXLJZ/9wzzgZAlHjXjxDHGsg== - dependencies: - "@jest/console" "^29.7.0" - "@jest/reporters" "^29.7.0" - "@jest/test-result" "^29.7.0" - "@jest/transform" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/node" "*" - ansi-escapes "^4.2.1" - chalk "^4.0.0" - ci-info "^3.2.0" - exit "^0.1.2" - graceful-fs "^4.2.9" - jest-changed-files "^29.7.0" - jest-config "^29.7.0" - jest-haste-map "^29.7.0" - jest-message-util "^29.7.0" - jest-regex-util "^29.6.3" - jest-resolve "^29.7.0" - jest-resolve-dependencies "^29.7.0" - jest-runner "^29.7.0" - jest-runtime "^29.7.0" - jest-snapshot "^29.7.0" - jest-util "^29.7.0" - jest-validate "^29.7.0" - jest-watcher "^29.7.0" - micromatch "^4.0.4" - pretty-format "^29.7.0" - slash "^3.0.0" - strip-ansi "^6.0.0" - -"@jest/environment@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/environment/-/environment-29.7.0.tgz#24d61f54ff1f786f3cd4073b4b94416383baf2a7" - integrity sha512-aQIfHDq33ExsN4jP1NWGXhxgQ/wixs60gDiKO+XVMd8Mn0NWPWgc34ZQDTb2jKaUWQ7MuwoitXAsN2XVXNMpAw== - dependencies: - "@jest/fake-timers" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/node" "*" - jest-mock "^29.7.0" - -"@jest/expect-utils@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/expect-utils/-/expect-utils-29.7.0.tgz#023efe5d26a8a70f21677d0a1afc0f0a44e3a1c6" - integrity sha512-GlsNBWiFQFCVi9QVSx7f5AgMeLxe9YCCs5PuP2O2LdjDAA8Jh9eX7lA1Jq/xdXw3Wb3hyvlFNfZIfcRetSzYcA== - dependencies: - jest-get-type "^29.6.3" - -"@jest/expect@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/expect/-/expect-29.7.0.tgz#76a3edb0cb753b70dfbfe23283510d3d45432bf2" - integrity sha512-8uMeAMycttpva3P1lBHB8VciS9V0XAr3GymPpipdyQXbBcuhkLQOSe8E/p92RyAdToS6ZD1tFkX+CkhoECE0dQ== - dependencies: - expect "^29.7.0" - jest-snapshot "^29.7.0" - -"@jest/fake-timers@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/fake-timers/-/fake-timers-29.7.0.tgz#fd91bf1fffb16d7d0d24a426ab1a47a49881a565" - integrity sha512-q4DH1Ha4TTFPdxLsqDXK1d3+ioSL7yL5oCMJZgDYm6i+6CygW5E5xVr/D1HdsGxjt1ZWSfUAs9OxSB/BNelWrQ== - dependencies: - "@jest/types" "^29.6.3" - "@sinonjs/fake-timers" "^10.0.2" - "@types/node" "*" - jest-message-util "^29.7.0" - jest-mock "^29.7.0" - jest-util "^29.7.0" - -"@jest/globals@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/globals/-/globals-29.7.0.tgz#8d9290f9ec47ff772607fa864ca1d5a2efae1d4d" - integrity sha512-mpiz3dutLbkW2MNFubUGUEVLkTGiqW6yLVTA+JbP6fI6J5iL9Y0Nlg8k95pcF8ctKwCS7WVxteBs29hhfAotzQ== - dependencies: - "@jest/environment" "^29.7.0" - "@jest/expect" "^29.7.0" - "@jest/types" "^29.6.3" - jest-mock "^29.7.0" - -"@jest/reporters@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/reporters/-/reporters-29.7.0.tgz#04b262ecb3b8faa83b0b3d321623972393e8f4c7" - integrity sha512-DApq0KJbJOEzAFYjHADNNxAE3KbhxQB1y5Kplb5Waqw6zVbuWatSnMjE5gs8FUgEPmNsnZA3NCWl9NG0ia04Pg== - dependencies: - "@bcoe/v8-coverage" "^0.2.3" - "@jest/console" "^29.7.0" - "@jest/test-result" "^29.7.0" - "@jest/transform" "^29.7.0" - "@jest/types" "^29.6.3" - "@jridgewell/trace-mapping" "^0.3.18" - "@types/node" "*" - chalk "^4.0.0" - collect-v8-coverage "^1.0.0" - exit "^0.1.2" - glob "^7.1.3" - graceful-fs "^4.2.9" - istanbul-lib-coverage "^3.0.0" - istanbul-lib-instrument "^6.0.0" - istanbul-lib-report "^3.0.0" - istanbul-lib-source-maps "^4.0.0" - istanbul-reports "^3.1.3" - jest-message-util "^29.7.0" - jest-util "^29.7.0" - jest-worker "^29.7.0" - slash "^3.0.0" - string-length "^4.0.1" - strip-ansi "^6.0.0" - v8-to-istanbul "^9.0.1" - -"@jest/schemas@^29.6.3": - version "29.6.3" - resolved "https://registry.yarnpkg.com/@jest/schemas/-/schemas-29.6.3.tgz#430b5ce8a4e0044a7e3819663305a7b3091c8e03" - integrity sha512-mo5j5X+jIZmJQveBKeS/clAueipV7KgiX1vMgCxam1RNYiqE1w62n0/tJJnHtjW8ZHcQco5gY85jA3mi0L+nSA== - dependencies: - "@sinclair/typebox" "^0.27.8" - -"@jest/source-map@^29.6.3": - version "29.6.3" - resolved "https://registry.yarnpkg.com/@jest/source-map/-/source-map-29.6.3.tgz#d90ba772095cf37a34a5eb9413f1b562a08554c4" - integrity sha512-MHjT95QuipcPrpLM+8JMSzFx6eHp5Bm+4XeFDJlwsvVBjmKNiIAvasGK2fxz2WbGRlnvqehFbh07MMa7n3YJnw== - dependencies: - "@jridgewell/trace-mapping" "^0.3.18" - callsites "^3.0.0" - graceful-fs "^4.2.9" - -"@jest/test-result@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/test-result/-/test-result-29.7.0.tgz#8db9a80aa1a097bb2262572686734baed9b1657c" - integrity sha512-Fdx+tv6x1zlkJPcWXmMDAG2HBnaR9XPSd5aDWQVsfrZmLVT3lU1cwyxLgRmXR9yrq4NBoEm9BMsfgFzTQAbJYA== - dependencies: - "@jest/console" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/istanbul-lib-coverage" "^2.0.0" - collect-v8-coverage "^1.0.0" - -"@jest/test-sequencer@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/test-sequencer/-/test-sequencer-29.7.0.tgz#6cef977ce1d39834a3aea887a1726628a6f072ce" - integrity sha512-GQwJ5WZVrKnOJuiYiAF52UNUJXgTZx1NHjFSEB0qEMmSZKAkdMoIzw/Cj6x6NF4AvV23AUqDpFzQkN/eYCYTxw== - dependencies: - "@jest/test-result" "^29.7.0" - graceful-fs "^4.2.9" - jest-haste-map "^29.7.0" - slash "^3.0.0" - -"@jest/transform@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/transform/-/transform-29.7.0.tgz#df2dd9c346c7d7768b8a06639994640c642e284c" - integrity sha512-ok/BTPFzFKVMwO5eOHRrvnBVHdRy9IrsrW1GpMaQ9MCnilNLXQKmAX8s1YXDFaai9xJpac2ySzV0YeRRECr2Vw== - dependencies: - "@babel/core" "^7.11.6" - "@jest/types" "^29.6.3" - "@jridgewell/trace-mapping" "^0.3.18" - babel-plugin-istanbul "^6.1.1" - chalk "^4.0.0" - convert-source-map "^2.0.0" - fast-json-stable-stringify "^2.1.0" - graceful-fs "^4.2.9" - jest-haste-map "^29.7.0" - jest-regex-util "^29.6.3" - jest-util "^29.7.0" - micromatch "^4.0.4" - pirates "^4.0.4" - slash "^3.0.0" - write-file-atomic "^4.0.2" - -"@jest/types@^29.6.3": - version "29.6.3" - resolved "https://registry.yarnpkg.com/@jest/types/-/types-29.6.3.tgz#1131f8cf634e7e84c5e77bab12f052af585fba59" - integrity sha512-u3UPsIilWKOM3F9CXtrG8LEJmNxwoCQC/XVj4IKYXvvpx7QIi/Kg1LI5uDmDpKlac62NUtX7eLjRh+jVZcLOzw== - dependencies: - "@jest/schemas" "^29.6.3" - "@types/istanbul-lib-coverage" "^2.0.0" - "@types/istanbul-reports" "^3.0.0" - "@types/node" "*" - "@types/yargs" "^17.0.8" - chalk "^4.0.0" - -"@jridgewell/gen-mapping@^0.3.12", "@jridgewell/gen-mapping@^0.3.5": - version "0.3.13" - resolved "https://registry.yarnpkg.com/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz#6342a19f44347518c93e43b1ac69deb3c4656a1f" - integrity sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA== - dependencies: - "@jridgewell/sourcemap-codec" "^1.5.0" - "@jridgewell/trace-mapping" "^0.3.24" - -"@jridgewell/remapping@^2.3.5": - version "2.3.5" - resolved "https://registry.yarnpkg.com/@jridgewell/remapping/-/remapping-2.3.5.tgz#375c476d1972947851ba1e15ae8f123047445aa1" - integrity sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ== - dependencies: - "@jridgewell/gen-mapping" "^0.3.5" - "@jridgewell/trace-mapping" "^0.3.24" - -"@jridgewell/resolve-uri@^3.0.3", "@jridgewell/resolve-uri@^3.1.0": - version "3.1.2" - resolved "https://registry.yarnpkg.com/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz#7a0ee601f60f99a20c7c7c5ff0c80388c1189bd6" - integrity sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw== - -"@jridgewell/sourcemap-codec@^1.4.10", "@jridgewell/sourcemap-codec@^1.4.14", "@jridgewell/sourcemap-codec@^1.5.0": - version "1.5.5" - resolved "https://registry.yarnpkg.com/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz#6912b00d2c631c0d15ce1a7ab57cd657f2a8f8ba" - integrity sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og== - -"@jridgewell/trace-mapping@0.3.9": - version "0.3.9" - resolved "https://registry.yarnpkg.com/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz#6534fd5933a53ba7cbf3a17615e273a0d1273ff9" - integrity sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ== - dependencies: - "@jridgewell/resolve-uri" "^3.0.3" - "@jridgewell/sourcemap-codec" "^1.4.10" - -"@jridgewell/trace-mapping@^0.3.12", "@jridgewell/trace-mapping@^0.3.18", "@jridgewell/trace-mapping@^0.3.24", "@jridgewell/trace-mapping@^0.3.28": - version "0.3.31" - resolved "https://registry.yarnpkg.com/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz#db15d6781c931f3a251a3dac39501c98a6082fd0" - integrity sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw== - dependencies: - "@jridgewell/resolve-uri" "^3.1.0" - "@jridgewell/sourcemap-codec" "^1.4.14" - -"@modelcontextprotocol/sdk@^1.27.1": - version "1.27.1" - resolved "https://registry.yarnpkg.com/@modelcontextprotocol/sdk/-/sdk-1.27.1.tgz#a602cf823bf8a68e13e7112f50aeb02b09fb83b9" - integrity sha512-sr6GbP+4edBwFndLbM60gf07z0FQ79gaExpnsjMGePXqFcSSb7t6iscpjk9DhFhwd+mTEQrzNafGP8/iGGFYaA== - dependencies: - "@hono/node-server" "^1.19.9" - ajv "^8.17.1" - ajv-formats "^3.0.1" - content-type "^1.0.5" - cors "^2.8.5" - cross-spawn "^7.0.5" - eventsource "^3.0.2" - eventsource-parser "^3.0.0" - express "^5.2.1" - express-rate-limit "^8.2.1" - hono "^4.11.4" - jose "^6.1.3" - json-schema-typed "^8.0.2" - pkce-challenge "^5.0.0" - raw-body "^3.0.0" - zod "^3.25 || ^4.0" - zod-to-json-schema "^3.25.1" - -"@nodelib/fs.scandir@2.1.5": - version "2.1.5" - resolved "https://registry.yarnpkg.com/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz#7619c2eb21b25483f6d167548b4cfd5a7488c3d5" - integrity sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g== - dependencies: - "@nodelib/fs.stat" "2.0.5" - run-parallel "^1.1.9" - -"@nodelib/fs.stat@2.0.5", "@nodelib/fs.stat@^2.0.2": - version "2.0.5" - resolved "https://registry.yarnpkg.com/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz#5bd262af94e9d25bd1e71b05deed44876a222e8b" - integrity sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A== - -"@nodelib/fs.walk@^1.2.3": - version "1.2.8" - resolved "https://registry.yarnpkg.com/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz#e95737e8bb6746ddedf69c556953494f196fe69a" - integrity sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg== - dependencies: - "@nodelib/fs.scandir" "2.1.5" - fastq "^1.6.0" - -"@pinojs/redact@^0.4.0": - version "0.4.0" - resolved "https://registry.yarnpkg.com/@pinojs/redact/-/redact-0.4.0.tgz#c3de060dd12640dcc838516aa2a6803cc7b2e9d6" - integrity sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg== - -"@pkgr/core@^0.2.9": - version "0.2.9" - resolved "https://registry.yarnpkg.com/@pkgr/core/-/core-0.2.9.tgz#d229a7b7f9dac167a156992ef23c7f023653f53b" - integrity sha512-QNqXyfVS2wm9hweSYD2O7F0G06uurj9kZ96TRQE5Y9hU7+tgdZwIkbAKc5Ocy1HxEY2kuDQa6cQ1WRs/O5LFKA== - -"@sinclair/typebox@^0.27.8": - version "0.27.8" - resolved "https://registry.yarnpkg.com/@sinclair/typebox/-/typebox-0.27.8.tgz#6667fac16c436b5434a387a34dedb013198f6e6e" - integrity sha512-+Fj43pSMwJs4KRrH/938Uf+uAELIgVBmQzg/q1YG10djyfA3TnrU8N8XzqCh/okZdszqBQTZf96idMfE5lnwTA== - -"@sinonjs/commons@^3.0.0": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@sinonjs/commons/-/commons-3.0.1.tgz#1029357e44ca901a615585f6d27738dbc89084cd" - integrity sha512-K3mCHKQ9sVh8o1C9cxkwxaOmXoAMlDxC1mYyHrjqOWEcBjYr76t96zL2zlj5dUGZ3HSw240X1qgH3Mjf1yJWpQ== - dependencies: - type-detect "4.0.8" - -"@sinonjs/fake-timers@^10.0.2": - version "10.3.0" - resolved "https://registry.yarnpkg.com/@sinonjs/fake-timers/-/fake-timers-10.3.0.tgz#55fdff1ecab9f354019129daf4df0dd4d923ea66" - integrity sha512-V4BG07kuYSUkTCSBHG8G8TNhM+F19jXFWnQtzj+we8DrkpSBCee9Z3Ms8yiGer/dlmhe35/Xdgyo3/0rQKg7YA== - dependencies: - "@sinonjs/commons" "^3.0.0" - -"@ts-morph/common@~0.20.0": - version "0.20.0" - resolved "https://registry.yarnpkg.com/@ts-morph/common/-/common-0.20.0.tgz#3f161996b085ba4519731e4d24c35f6cba5b80af" - integrity sha512-7uKjByfbPpwuzkstL3L5MQyuXPSKdoNG93Fmi2JoDcTf3pEP731JdRFAduRVkOs8oqxPsXKA+ScrWkdQ8t/I+Q== - dependencies: - fast-glob "^3.2.12" - minimatch "^7.4.3" - mkdirp "^2.1.6" - path-browserify "^1.0.1" - -"@tsconfig/node10@^1.0.7": - version "1.0.12" - resolved "https://registry.yarnpkg.com/@tsconfig/node10/-/node10-1.0.12.tgz#be57ceac1e4692b41be9de6be8c32a106636dba4" - integrity sha512-UCYBaeFvM11aU2y3YPZ//O5Rhj+xKyzy7mvcIoAjASbigy8mHMryP5cK7dgjlz2hWxh1g5pLw084E0a/wlUSFQ== - -"@tsconfig/node12@^1.0.7": - version "1.0.11" - resolved "https://registry.yarnpkg.com/@tsconfig/node12/-/node12-1.0.11.tgz#ee3def1f27d9ed66dac6e46a295cffb0152e058d" - integrity sha512-cqefuRsh12pWyGsIoBKJA9luFu3mRxCA+ORZvA4ktLSzIuCUtWVxGIuXigEwO5/ywWFMZ2QEGKWvkZG1zDMTag== - -"@tsconfig/node14@^1.0.0": - version "1.0.3" - resolved "https://registry.yarnpkg.com/@tsconfig/node14/-/node14-1.0.3.tgz#e4386316284f00b98435bf40f72f75a09dabf6c1" - integrity sha512-ysT8mhdixWK6Hw3i1V2AeRqZ5WfXg1G43mqoYlM2nc6388Fq5jcXyr5mRsqViLx/GJYdoL0bfXD8nmF+Zn/Iow== - -"@tsconfig/node16@^1.0.2": - version "1.0.4" - resolved "https://registry.yarnpkg.com/@tsconfig/node16/-/node16-1.0.4.tgz#0b92dcc0cc1c81f6f306a381f28e31b1a56536e9" - integrity sha512-vxhUy4J8lyeyinH7Azl1pdd43GJhZH/tP2weN8TntQblOY+A0XbT8DJk1/oCPuOOyg/Ja757rG0CgHcWC8OfMA== - -"@types/babel__core@^7.1.14": - version "7.20.5" - resolved "https://registry.yarnpkg.com/@types/babel__core/-/babel__core-7.20.5.tgz#3df15f27ba85319caa07ba08d0721889bb39c017" - integrity sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA== - dependencies: - "@babel/parser" "^7.20.7" - "@babel/types" "^7.20.7" - "@types/babel__generator" "*" - "@types/babel__template" "*" - "@types/babel__traverse" "*" - -"@types/babel__generator@*": - version "7.27.0" - resolved "https://registry.yarnpkg.com/@types/babel__generator/-/babel__generator-7.27.0.tgz#b5819294c51179957afaec341442f9341e4108a9" - integrity sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg== - dependencies: - "@babel/types" "^7.0.0" - -"@types/babel__template@*": - version "7.4.4" - resolved "https://registry.yarnpkg.com/@types/babel__template/-/babel__template-7.4.4.tgz#5672513701c1b2199bc6dad636a9d7491586766f" - integrity sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A== - dependencies: - "@babel/parser" "^7.1.0" - "@babel/types" "^7.0.0" - -"@types/babel__traverse@*", "@types/babel__traverse@^7.0.6": - version "7.28.0" - resolved "https://registry.yarnpkg.com/@types/babel__traverse/-/babel__traverse-7.28.0.tgz#07d713d6cce0d265c9849db0cbe62d3f61f36f74" - integrity sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q== - dependencies: - "@babel/types" "^7.28.2" - -"@types/body-parser@*": - version "1.19.6" - resolved "https://registry.yarnpkg.com/@types/body-parser/-/body-parser-1.19.6.tgz#1859bebb8fd7dac9918a45d54c1971ab8b5af474" - integrity sha512-HLFeCYgz89uk22N5Qg3dvGvsv46B8GLvKKo1zKG4NybA8U2DiEO3w9lqGg29t/tfLRJpJ6iQxnVw4OnB7MoM9g== - dependencies: - "@types/connect" "*" - "@types/node" "*" - -"@types/connect@*": - version "3.4.38" - resolved "https://registry.yarnpkg.com/@types/connect/-/connect-3.4.38.tgz#5ba7f3bc4fbbdeaff8dded952e5ff2cc53f8d858" - integrity sha512-K6uROf1LD88uDQqJCktA4yzL1YYAK6NgfsI0v/mTgyPKWsX1CnJ0XPSDhViejru1GcRkLWb8RlzFYJRqGUbaug== - dependencies: - "@types/node" "*" - -"@types/cookie-parser@^1.4.10": - version "1.4.10" - resolved "https://registry.yarnpkg.com/@types/cookie-parser/-/cookie-parser-1.4.10.tgz#a045272a383a30597a01955d4f9c790018f214e4" - integrity sha512-B4xqkqfZ8Wek+rCOeRxsjMS9OgvzebEzzLYw7NHYuvzb7IdxOkI0ZHGgeEBX4PUM7QGVvNSK60T3OvWj3YfBRg== - -"@types/cors@^2.8.19": - version "2.8.19" - resolved "https://registry.yarnpkg.com/@types/cors/-/cors-2.8.19.tgz#d93ea2673fd8c9f697367f5eeefc2bbfa94f0342" - integrity sha512-mFNylyeyqN93lfe/9CSxOGREz8cpzAhH+E93xJ4xWQf62V8sQ/24reV2nyzUWM6H6Xji+GGHpkbLe7pVoUEskg== - dependencies: - "@types/node" "*" - -"@types/estree@^1.0.6": - version "1.0.8" - resolved "https://registry.yarnpkg.com/@types/estree/-/estree-1.0.8.tgz#958b91c991b1867ced318bedea0e215ee050726e" - integrity sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w== - -"@types/express-serve-static-core@^5.0.0": - version "5.1.1" - resolved "https://registry.yarnpkg.com/@types/express-serve-static-core/-/express-serve-static-core-5.1.1.tgz#1a77faffee9572d39124933259be2523837d7eaa" - integrity sha512-v4zIMr/cX7/d2BpAEX3KNKL/JrT1s43s96lLvvdTmza1oEvDudCqK9aF/djc/SWgy8Yh0h30TZx5VpzqFCxk5A== - dependencies: - "@types/node" "*" - "@types/qs" "*" - "@types/range-parser" "*" - "@types/send" "*" - -"@types/express@^5.0.3": - version "5.0.6" - resolved "https://registry.yarnpkg.com/@types/express/-/express-5.0.6.tgz#2d724b2c990dcb8c8444063f3580a903f6d500cc" - integrity sha512-sKYVuV7Sv9fbPIt/442koC7+IIwK5olP1KWeD88e/idgoJqDm3JV/YUiPwkoKK92ylff2MGxSz1CSjsXelx0YA== - dependencies: - "@types/body-parser" "*" - "@types/express-serve-static-core" "^5.0.0" - "@types/serve-static" "^2" - -"@types/graceful-fs@^4.1.3": - version "4.1.9" - resolved "https://registry.yarnpkg.com/@types/graceful-fs/-/graceful-fs-4.1.9.tgz#2a06bc0f68a20ab37b3e36aa238be6abdf49e8b4" - integrity sha512-olP3sd1qOEe5dXTSaFvQG+02VdRXcdytWLAZsAq1PecU8uqQAhkrnbli7DagjtXKW/Bl7YJbUsa8MPcuc8LHEQ== - dependencies: - "@types/node" "*" - -"@types/http-errors@*": - version "2.0.5" - resolved "https://registry.yarnpkg.com/@types/http-errors/-/http-errors-2.0.5.tgz#5b749ab2b16ba113423feb1a64a95dcd30398472" - integrity sha512-r8Tayk8HJnX0FztbZN7oVqGccWgw98T/0neJphO91KkmOzug1KkofZURD4UaD5uH8AqcFLfdPErnBod0u71/qg== - -"@types/istanbul-lib-coverage@*", "@types/istanbul-lib-coverage@^2.0.0", "@types/istanbul-lib-coverage@^2.0.1": - version "2.0.6" - resolved "https://registry.yarnpkg.com/@types/istanbul-lib-coverage/-/istanbul-lib-coverage-2.0.6.tgz#7739c232a1fee9b4d3ce8985f314c0c6d33549d7" - integrity sha512-2QF/t/auWm0lsy8XtKVPG19v3sSOQlJe/YHZgfjb/KBBHOGSV+J2q/S671rcq9uTBrLAXmZpqJiaQbMT+zNU1w== - -"@types/istanbul-lib-report@*": - version "3.0.3" - resolved "https://registry.yarnpkg.com/@types/istanbul-lib-report/-/istanbul-lib-report-3.0.3.tgz#53047614ae72e19fc0401d872de3ae2b4ce350bf" - integrity sha512-NQn7AHQnk/RSLOxrBbGyJM/aVQ+pjj5HCgasFxc0K/KhoATfQ/47AyUl15I2yBUpihjmas+a+VJBOqecrFH+uA== - dependencies: - "@types/istanbul-lib-coverage" "*" - -"@types/istanbul-reports@^3.0.0": - version "3.0.4" - resolved "https://registry.yarnpkg.com/@types/istanbul-reports/-/istanbul-reports-3.0.4.tgz#0f03e3d2f670fbdac586e34b433783070cc16f54" - integrity sha512-pk2B1NWalF9toCRu6gjBzR69syFjP4Od8WRAX+0mmf9lAjCRicLOWc+ZrxZHx/0XRjotgkF9t6iaMJ+aXcOdZQ== - dependencies: - "@types/istanbul-lib-report" "*" - -"@types/jest@^29.4.0": - version "29.5.14" - resolved "https://registry.yarnpkg.com/@types/jest/-/jest-29.5.14.tgz#2b910912fa1d6856cadcd0c1f95af7df1d6049e5" - integrity sha512-ZN+4sdnLUbo8EVvVc2ao0GFW6oVrQRPn4K2lglySj7APvSrgzxHiNNK99us4WDMi57xxA2yggblIAMNhXOotLQ== - dependencies: - expect "^29.0.0" - pretty-format "^29.0.0" - -"@types/json-schema@^7.0.15": - version "7.0.15" - resolved "https://registry.yarnpkg.com/@types/json-schema/-/json-schema-7.0.15.tgz#596a1747233694d50f6ad8a7869fcb6f56cf5841" - integrity sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA== - -"@types/mute-stream@^0.0.4": - version "0.0.4" - resolved "https://registry.yarnpkg.com/@types/mute-stream/-/mute-stream-0.0.4.tgz#77208e56a08767af6c5e1237be8888e2f255c478" - integrity sha512-CPM9nzrCPPJHQNA9keH9CVkVI+WR5kMa+7XEs5jcGQ0VoAGnLv242w8lIVgwAEfmE4oufJRaTc9PNLQl0ioAow== - dependencies: - "@types/node" "*" - -"@types/node@*": - version "25.0.8" - resolved "https://registry.yarnpkg.com/@types/node/-/node-25.0.8.tgz#e54e00f94fe1db2497b3e42d292b8376a2678c8d" - integrity sha512-powIePYMmC3ibL0UJ2i2s0WIbq6cg6UyVFQxSCpaPxxzAaziRfimGivjdF943sSGV6RADVbk0Nvlm5P/FB44Zg== - dependencies: - undici-types "~7.16.0" - -"@types/node@^22.5.5": - version "22.19.6" - resolved "https://registry.yarnpkg.com/@types/node/-/node-22.19.6.tgz#0e9d80ebcd2dfce03265768c17a1212d4eb07e82" - integrity sha512-qm+G8HuG6hOHQigsi7VGuLjUVu6TtBo/F05zvX04Mw2uCg9Dv0Qxy3Qw7j41SidlTcl5D/5yg0SEZqOB+EqZnQ== - dependencies: - undici-types "~6.21.0" - -"@types/qs@*", "@types/qs@^6.14.0": - version "6.14.0" - resolved "https://registry.yarnpkg.com/@types/qs/-/qs-6.14.0.tgz#d8b60cecf62f2db0fb68e5e006077b9178b85de5" - integrity sha512-eOunJqu0K1923aExK6y8p6fsihYEn/BYuQ4g0CxAAgFc4b/ZLN4CrsRZ55srTdqoiLzU2B2evC+apEIxprEzkQ== - -"@types/range-parser@*": - version "1.2.7" - resolved "https://registry.yarnpkg.com/@types/range-parser/-/range-parser-1.2.7.tgz#50ae4353eaaddc04044279812f52c8c65857dbcb" - integrity sha512-hKormJbkJqzQGhziax5PItDUTMAM9uE2XXQmM37dyd4hVM+5aVl7oVxMVUiVQn2oCQFN/LKCZdvSM0pFRqbSmQ== - -"@types/send@*": - version "1.2.1" - resolved "https://registry.yarnpkg.com/@types/send/-/send-1.2.1.tgz#6a784e45543c18c774c049bff6d3dbaf045c9c74" - integrity sha512-arsCikDvlU99zl1g69TcAB3mzZPpxgw0UQnaHeC1Nwb015xp8bknZv5rIfri9xTOcMuaVgvabfIRA7PSZVuZIQ== - dependencies: - "@types/node" "*" - -"@types/serve-static@^2": - version "2.2.0" - resolved "https://registry.yarnpkg.com/@types/serve-static/-/serve-static-2.2.0.tgz#d4a447503ead0d1671132d1ab6bd58b805d8de6a" - integrity sha512-8mam4H1NHLtu7nmtalF7eyBH14QyOASmcxHhSfEoRyr0nP/YdoesEtU+uSRvMe96TW/HPTtkoKqQLl53N7UXMQ== - dependencies: - "@types/http-errors" "*" - "@types/node" "*" - -"@types/stack-utils@^2.0.0": - version "2.0.3" - resolved "https://registry.yarnpkg.com/@types/stack-utils/-/stack-utils-2.0.3.tgz#6209321eb2c1712a7e7466422b8cb1fc0d9dd5d8" - integrity sha512-9aEbYZ3TbYMznPdcdr3SmIrLXwC/AKZXQeCf9Pgao5CKb8CyHuEX5jzWPTkvregvhRJHcpRO6BFoGW9ycaOkYw== - -"@types/wrap-ansi@^3.0.0": - version "3.0.0" - resolved "https://registry.yarnpkg.com/@types/wrap-ansi/-/wrap-ansi-3.0.0.tgz#18b97a972f94f60a679fd5c796d96421b9abb9fd" - integrity sha512-ltIpx+kM7g/MLRZfkbL7EsCEjfzCcScLpkg37eXEtx5kmrAKBkTJwd1GIAjDSL8wTpM6Hzn5YO4pSb91BEwu1g== - -"@types/yargs-parser@*": - version "21.0.3" - resolved "https://registry.yarnpkg.com/@types/yargs-parser/-/yargs-parser-21.0.3.tgz#815e30b786d2e8f0dcd85fd5bcf5e1a04d008f15" - integrity sha512-I4q9QU9MQv4oEOz4tAHJtNz1cwuLxn2F3xcc2iV5WdqLPpUnj30aUuxt1mAxYTG+oe8CZMV/+6rU4S4gRDzqtQ== - -"@types/yargs@^17.0.8": - version "17.0.35" - resolved "https://registry.yarnpkg.com/@types/yargs/-/yargs-17.0.35.tgz#07013e46aa4d7d7d50a49e15604c1c5340d4eb24" - integrity sha512-qUHkeCyQFxMXg79wQfTtfndEC+N9ZZg76HJftDJp+qH2tV7Gj4OJi7l+PiWwJ+pWtW8GwSmqsDj/oymhrTWXjg== - dependencies: - "@types/yargs-parser" "*" - -"@typescript-eslint/eslint-plugin@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.31.1.tgz#62f1befe59647524994e89de4516d8dcba7a850a" - integrity sha512-oUlH4h1ABavI4F0Xnl8/fOtML/eu8nI2A1nYd+f+55XI0BLu+RIqKoCiZKNo6DtqZBEQm5aNKA20G3Z5w3R6GQ== - dependencies: - "@eslint-community/regexpp" "^4.10.0" - "@typescript-eslint/scope-manager" "8.31.1" - "@typescript-eslint/type-utils" "8.31.1" - "@typescript-eslint/utils" "8.31.1" - "@typescript-eslint/visitor-keys" "8.31.1" - graphemer "^1.4.0" - ignore "^5.3.1" - natural-compare "^1.4.0" - ts-api-utils "^2.0.1" - -"@typescript-eslint/parser@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/parser/-/parser-8.31.1.tgz#e9b0ccf30d37dde724ee4d15f4dbc195995cce1b" - integrity sha512-oU/OtYVydhXnumd0BobL9rkJg7wFJ9bFFPmSmB/bf/XWN85hlViji59ko6bSKBXyseT9V8l+CN1nwmlbiN0G7Q== - dependencies: - "@typescript-eslint/scope-manager" "8.31.1" - "@typescript-eslint/types" "8.31.1" - "@typescript-eslint/typescript-estree" "8.31.1" - "@typescript-eslint/visitor-keys" "8.31.1" - debug "^4.3.4" - -"@typescript-eslint/scope-manager@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/scope-manager/-/scope-manager-8.31.1.tgz#1eb52e76878f545e4add142e0d8e3e97e7aa443b" - integrity sha512-BMNLOElPxrtNQMIsFHE+3P0Yf1z0dJqV9zLdDxN/xLlWMlXK/ApEsVEKzpizg9oal8bAT5Sc7+ocal7AC1HCVw== - dependencies: - "@typescript-eslint/types" "8.31.1" - "@typescript-eslint/visitor-keys" "8.31.1" - -"@typescript-eslint/type-utils@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/type-utils/-/type-utils-8.31.1.tgz#be0f438fb24b03568e282a0aed85f776409f970c" - integrity sha512-fNaT/m9n0+dpSp8G/iOQ05GoHYXbxw81x+yvr7TArTuZuCA6VVKbqWYVZrV5dVagpDTtj/O8k5HBEE/p/HM5LA== - dependencies: - "@typescript-eslint/typescript-estree" "8.31.1" - "@typescript-eslint/utils" "8.31.1" - debug "^4.3.4" - ts-api-utils "^2.0.1" - -"@typescript-eslint/types@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/types/-/types-8.31.1.tgz#478ed6f7e8aee1be7b63a60212b6bffe1423b5d4" - integrity sha512-SfepaEFUDQYRoA70DD9GtytljBePSj17qPxFHA/h3eg6lPTqGJ5mWOtbXCk1YrVU1cTJRd14nhaXWFu0l2troQ== - -"@typescript-eslint/typescript-estree@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/typescript-estree/-/typescript-estree-8.31.1.tgz#37792fe7ef4d3021c7580067c8f1ae66daabacdf" - integrity sha512-kaA0ueLe2v7KunYOyWYtlf/QhhZb7+qh4Yw6Ni5kgukMIG+iP773tjgBiLWIXYumWCwEq3nLW+TUywEp8uEeag== - dependencies: - "@typescript-eslint/types" "8.31.1" - "@typescript-eslint/visitor-keys" "8.31.1" - debug "^4.3.4" - fast-glob "^3.3.2" - is-glob "^4.0.3" - minimatch "^9.0.4" - semver "^7.6.0" - ts-api-utils "^2.0.1" - -"@typescript-eslint/utils@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/utils/-/utils-8.31.1.tgz#5628ea0393598a0b2f143d0fc6d019f0dee9dd14" - integrity sha512-2DSI4SNfF5T4oRveQ4nUrSjUqjMND0nLq9rEkz0gfGr3tg0S5KB6DhwR+WZPCjzkZl3cH+4x2ce3EsL50FubjQ== - dependencies: - "@eslint-community/eslint-utils" "^4.4.0" - "@typescript-eslint/scope-manager" "8.31.1" - "@typescript-eslint/types" "8.31.1" - "@typescript-eslint/typescript-estree" "8.31.1" - -"@typescript-eslint/visitor-keys@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/visitor-keys/-/visitor-keys-8.31.1.tgz#6742b0e3ba1e0c1e35bdaf78c03e759eb8dd8e75" - integrity sha512-I+/rgqOVBn6f0o7NDTmAPWWC6NuqhV174lfYvAm9fUaWeiefLdux9/YI3/nLugEn9L8fcSi0XmpKi/r5u0nmpw== - dependencies: - "@typescript-eslint/types" "8.31.1" - eslint-visitor-keys "^4.2.0" - -"@valtown/deno-http-worker@^0.0.21": - version "0.0.21" - resolved "https://registry.yarnpkg.com/@valtown/deno-http-worker/-/deno-http-worker-0.0.21.tgz#9ce3b5c1d0db211fe7ea8297881fe551838474ad" - integrity sha512-16kFuUykann75lNytnXXIQlmpzreZjzdyT27ebT3yNGCS3kKaS1iZYWHc3Si9An54Cphwr4qEcviChQkEeJBlA== - -accepts@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/accepts/-/accepts-2.0.0.tgz#bbcf4ba5075467f3f2131eab3cffc73c2f5d7895" - integrity sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng== - dependencies: - mime-types "^3.0.0" - negotiator "^1.0.0" - -acorn-jsx@^5.3.2: - version "5.3.2" - resolved "https://registry.yarnpkg.com/acorn-jsx/-/acorn-jsx-5.3.2.tgz#7ed5bb55908b3b2f1bc55c6af1653bada7f07937" - integrity sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ== - -acorn-walk@^8.1.1: - version "8.3.4" - resolved "https://registry.yarnpkg.com/acorn-walk/-/acorn-walk-8.3.4.tgz#794dd169c3977edf4ba4ea47583587c5866236b7" - integrity sha512-ueEepnujpqee2o5aIYnvHU6C0A42MNdsIDeqy5BydrkuC5R1ZuUFnm27EeFJGoEHJQgn3uleRvmTXaJgfXbt4g== - dependencies: - acorn "^8.11.0" - -acorn@^8.11.0, acorn@^8.4.1: - version "8.15.0" - resolved "https://registry.yarnpkg.com/acorn/-/acorn-8.15.0.tgz#a360898bc415edaac46c8241f6383975b930b816" - integrity sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg== - -acorn@^8.15.0: - version "8.16.0" - resolved "https://registry.yarnpkg.com/acorn/-/acorn-8.16.0.tgz#4ce79c89be40afe7afe8f3adb902a1f1ce9ac08a" - integrity sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw== - -aggregate-error@^3.0.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/aggregate-error/-/aggregate-error-3.1.0.tgz#92670ff50f5359bdb7a3e0d40d0ec30c5737687a" - integrity sha512-4I7Td01quW/RpocfNayFdFVk1qSuoh0E7JrbRJ16nH01HhKFQ88INq9Sd+nd72zqRySlr9BmDA8xlEJ6vJMrYA== - dependencies: - clean-stack "^2.0.0" - indent-string "^4.0.0" - -ajv-formats@^3.0.1: - version "3.0.1" - resolved "https://registry.yarnpkg.com/ajv-formats/-/ajv-formats-3.0.1.tgz#3d5dc762bca17679c3c2ea7e90ad6b7532309578" - integrity sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ== - dependencies: - ajv "^8.0.0" - -ajv@^6.14.0: - version "6.14.0" - resolved "https://registry.yarnpkg.com/ajv/-/ajv-6.14.0.tgz#fd067713e228210636ebb08c60bd3765d6dbe73a" - integrity sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw== - dependencies: - fast-deep-equal "^3.1.1" - fast-json-stable-stringify "^2.0.0" - json-schema-traverse "^0.4.1" - uri-js "^4.2.2" - -ajv@^8.0.0, ajv@^8.17.1: - version "8.17.1" - resolved "https://registry.yarnpkg.com/ajv/-/ajv-8.17.1.tgz#37d9a5c776af6bc92d7f4f9510eba4c0a60d11a6" - integrity sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g== - dependencies: - fast-deep-equal "^3.1.3" - fast-uri "^3.0.1" - json-schema-traverse "^1.0.0" - require-from-string "^2.0.2" - -ajv@^8.18.0: - version "8.18.0" - resolved "https://registry.yarnpkg.com/ajv/-/ajv-8.18.0.tgz#8864186b6738d003eb3a933172bb3833e10cefbc" - integrity sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A== - dependencies: - fast-deep-equal "^3.1.3" - fast-uri "^3.0.1" - json-schema-traverse "^1.0.0" - require-from-string "^2.0.2" - -ansi-escapes@^4.2.1, ansi-escapes@^4.3.2: - version "4.3.2" - resolved "https://registry.yarnpkg.com/ansi-escapes/-/ansi-escapes-4.3.2.tgz#6b2291d1db7d98b6521d5f1efa42d0f3a9feb65e" - integrity sha512-gKXj5ALrKWQLsYG9jlTRmR/xKluxHV+Z9QEwNIgCfM1/uwPMCuzVVnh5mwTd+OuBZcwSIMbqssNWRm1lE51QaQ== - dependencies: - type-fest "^0.21.3" - -ansi-regex@^5.0.1: - version "5.0.1" - resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-5.0.1.tgz#082cb2c89c9fe8659a311a53bd6a4dc5301db304" - integrity sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ== - -ansi-styles@^4.0.0, ansi-styles@^4.1.0: - version "4.3.0" - resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-4.3.0.tgz#edd803628ae71c04c85ae7a0906edad34b648937" - integrity sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg== - dependencies: - color-convert "^2.0.1" - -ansi-styles@^5.0.0: - version "5.2.0" - resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-5.2.0.tgz#07449690ad45777d1924ac2abb2fc8895dba836b" - integrity sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA== - -anymatch@^3.0.3: - version "3.1.3" - resolved "https://registry.yarnpkg.com/anymatch/-/anymatch-3.1.3.tgz#790c58b19ba1720a84205b57c618d5ad8524973e" - integrity sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw== - dependencies: - normalize-path "^3.0.0" - picomatch "^2.0.4" - -arg@^4.1.0: - version "4.1.3" - resolved "https://registry.yarnpkg.com/arg/-/arg-4.1.3.tgz#269fc7ad5b8e42cb63c896d5666017261c144089" - integrity sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA== - -argparse@^1.0.7: - version "1.0.10" - resolved "https://registry.yarnpkg.com/argparse/-/argparse-1.0.10.tgz#bcd6791ea5ae09725e17e5ad988134cd40b3d911" - integrity sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg== - dependencies: - sprintf-js "~1.0.2" - -argparse@^2.0.1: - version "2.0.1" - resolved "https://registry.yarnpkg.com/argparse/-/argparse-2.0.1.tgz#246f50f3ca78a3240f6c997e8a9bd1eac49e4b38" - integrity sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q== - -atomic-sleep@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/atomic-sleep/-/atomic-sleep-1.0.0.tgz#eb85b77a601fc932cfe432c5acd364a9e2c9075b" - integrity sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ== - -babel-jest@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/babel-jest/-/babel-jest-29.7.0.tgz#f4369919225b684c56085998ac63dbd05be020d5" - integrity sha512-BrvGY3xZSwEcCzKvKsCi2GgHqDqsYkOP4/by5xCgIwGXQxIEh+8ew3gmrE1y7XRR6LHZIj6yLYnUi/mm2KXKBg== - dependencies: - "@jest/transform" "^29.7.0" - "@types/babel__core" "^7.1.14" - babel-plugin-istanbul "^6.1.1" - babel-preset-jest "^29.6.3" - chalk "^4.0.0" - graceful-fs "^4.2.9" - slash "^3.0.0" - -babel-plugin-istanbul@^6.1.1: - version "6.1.1" - resolved "https://registry.yarnpkg.com/babel-plugin-istanbul/-/babel-plugin-istanbul-6.1.1.tgz#fa88ec59232fd9b4e36dbbc540a8ec9a9b47da73" - integrity sha512-Y1IQok9821cC9onCx5otgFfRm7Lm+I+wwxOx738M/WLPZ9Q42m4IG5W0FNX8WLL2gYMZo3JkuXIH2DOpWM+qwA== - dependencies: - "@babel/helper-plugin-utils" "^7.0.0" - "@istanbuljs/load-nyc-config" "^1.0.0" - "@istanbuljs/schema" "^0.1.2" - istanbul-lib-instrument "^5.0.4" - test-exclude "^6.0.0" - -babel-plugin-jest-hoist@^29.6.3: - version "29.6.3" - resolved "https://registry.yarnpkg.com/babel-plugin-jest-hoist/-/babel-plugin-jest-hoist-29.6.3.tgz#aadbe943464182a8922c3c927c3067ff40d24626" - integrity sha512-ESAc/RJvGTFEzRwOTT4+lNDk/GNHMkKbNzsvT0qKRfDyyYTskxB5rnU2njIDYVxXCBHHEI1c0YwHob3WaYujOg== - dependencies: - "@babel/template" "^7.3.3" - "@babel/types" "^7.3.3" - "@types/babel__core" "^7.1.14" - "@types/babel__traverse" "^7.0.6" - -babel-preset-current-node-syntax@^1.0.0: - version "1.2.0" - resolved "https://registry.yarnpkg.com/babel-preset-current-node-syntax/-/babel-preset-current-node-syntax-1.2.0.tgz#20730d6cdc7dda5d89401cab10ac6a32067acde6" - integrity sha512-E/VlAEzRrsLEb2+dv8yp3bo4scof3l9nR4lrld+Iy5NyVqgVYUJnDAmunkhPMisRI32Qc4iRiz425d8vM++2fg== - dependencies: - "@babel/plugin-syntax-async-generators" "^7.8.4" - "@babel/plugin-syntax-bigint" "^7.8.3" - "@babel/plugin-syntax-class-properties" "^7.12.13" - "@babel/plugin-syntax-class-static-block" "^7.14.5" - "@babel/plugin-syntax-import-attributes" "^7.24.7" - "@babel/plugin-syntax-import-meta" "^7.10.4" - "@babel/plugin-syntax-json-strings" "^7.8.3" - "@babel/plugin-syntax-logical-assignment-operators" "^7.10.4" - "@babel/plugin-syntax-nullish-coalescing-operator" "^7.8.3" - "@babel/plugin-syntax-numeric-separator" "^7.10.4" - "@babel/plugin-syntax-object-rest-spread" "^7.8.3" - "@babel/plugin-syntax-optional-catch-binding" "^7.8.3" - "@babel/plugin-syntax-optional-chaining" "^7.8.3" - "@babel/plugin-syntax-private-property-in-object" "^7.14.5" - "@babel/plugin-syntax-top-level-await" "^7.14.5" - -babel-preset-jest@^29.6.3: - version "29.6.3" - resolved "https://registry.yarnpkg.com/babel-preset-jest/-/babel-preset-jest-29.6.3.tgz#fa05fa510e7d493896d7b0dd2033601c840f171c" - integrity sha512-0B3bhxR6snWXJZtR/RliHTDPRgn1sNHOR0yVtq/IiQFyuOVjFS+wuio/R4gSNkyYmKmJB4wGZv2NZanmKmTnNA== - dependencies: - babel-plugin-jest-hoist "^29.6.3" - babel-preset-current-node-syntax "^1.0.0" - -balanced-match@^1.0.0: - version "1.0.2" - resolved "https://registry.yarnpkg.com/balanced-match/-/balanced-match-1.0.2.tgz#e83e3a7e3f300b34cb9d87f615fa0cbf357690ee" - integrity sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw== - -baseline-browser-mapping@^2.9.0: - version "2.9.14" - resolved "https://registry.yarnpkg.com/baseline-browser-mapping/-/baseline-browser-mapping-2.9.14.tgz#3b6af0bc032445bca04de58caa9a87cfe921cbb3" - integrity sha512-B0xUquLkiGLgHhpPBqvl7GWegWBUNuujQ6kXd/r1U38ElPT6Ok8KZ8e+FpUGEc2ZoRQUzq/aUnaKFc/svWUGSg== - -body-parser@^2.2.1: - version "2.2.2" - resolved "https://registry.yarnpkg.com/body-parser/-/body-parser-2.2.2.tgz#1a32cdb966beaf68de50a9dfbe5b58f83cb8890c" - integrity sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA== - dependencies: - bytes "^3.1.2" - content-type "^1.0.5" - debug "^4.4.3" - http-errors "^2.0.0" - iconv-lite "^0.7.0" - on-finished "^2.4.1" - qs "^6.14.1" - raw-body "^3.0.1" - type-is "^2.0.1" - -brace-expansion@^1.1.7: - version "1.1.12" - resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-1.1.12.tgz#ab9b454466e5a8cc3a187beaad580412a9c5b843" - integrity sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg== - dependencies: - balanced-match "^1.0.0" - concat-map "0.0.1" - -brace-expansion@^2.0.1: - version "2.0.2" - resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.0.2.tgz#54fc53237a613d854c7bd37463aad17df87214e7" - integrity sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ== - dependencies: - balanced-match "^1.0.0" - -braces@^3.0.3: - version "3.0.3" - resolved "https://registry.yarnpkg.com/braces/-/braces-3.0.3.tgz#490332f40919452272d55a8480adc0c441358789" - integrity sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA== - dependencies: - fill-range "^7.1.1" - -browserslist@^4.24.0: - version "4.28.1" - resolved "https://registry.yarnpkg.com/browserslist/-/browserslist-4.28.1.tgz#7f534594628c53c63101079e27e40de490456a95" - integrity sha512-ZC5Bd0LgJXgwGqUknZY/vkUQ04r8NXnJZ3yYi4vDmSiZmC/pdSN0NbNRPxZpbtO4uAfDUAFffO8IZoM3Gj8IkA== - dependencies: - baseline-browser-mapping "^2.9.0" - caniuse-lite "^1.0.30001759" - electron-to-chromium "^1.5.263" - node-releases "^2.0.27" - update-browserslist-db "^1.2.0" - -bs-logger@^0.2.6: - version "0.2.6" - resolved "https://registry.yarnpkg.com/bs-logger/-/bs-logger-0.2.6.tgz#eb7d365307a72cf974cc6cda76b68354ad336bd8" - integrity sha512-pd8DCoxmbgc7hyPKOvxtqNcjYoOsABPQdcCUjGp3d42VR2CX1ORhk2A87oqqu5R1kk+76nsxZupkmyd+MVtCog== - dependencies: - fast-json-stable-stringify "2.x" - -bser@2.1.1: - version "2.1.1" - resolved "https://registry.yarnpkg.com/bser/-/bser-2.1.1.tgz#e6787da20ece9d07998533cfd9de6f5c38f4bc05" - integrity sha512-gQxTNE/GAfIIrmHLUE3oJyp5FO6HRBfhjnw4/wMmA63ZGDJnWBmgY/lyQBpnDUkGmAhbSe39tx2d/iTOAfglwQ== - dependencies: - node-int64 "^0.4.0" - -buffer-from@^1.0.0: - version "1.1.2" - resolved "https://registry.yarnpkg.com/buffer-from/-/buffer-from-1.1.2.tgz#2b146a6fd72e80b4f55d255f35ed59a3a9a41bd5" - integrity sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ== - -bytes@^3.1.2, bytes@~3.1.2: - version "3.1.2" - resolved "https://registry.yarnpkg.com/bytes/-/bytes-3.1.2.tgz#8b0beeb98605adf1b128fa4386403c009e0221a5" - integrity sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg== - -call-bind-apply-helpers@^1.0.1, call-bind-apply-helpers@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz#4b5428c222be985d79c3d82657479dbe0b59b2d6" - integrity sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ== - dependencies: - es-errors "^1.3.0" - function-bind "^1.1.2" - -call-bound@^1.0.2: - version "1.0.4" - resolved "https://registry.yarnpkg.com/call-bound/-/call-bound-1.0.4.tgz#238de935d2a2a692928c538c7ccfa91067fd062a" - integrity sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg== - dependencies: - call-bind-apply-helpers "^1.0.2" - get-intrinsic "^1.3.0" - -callsites@^3.0.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/callsites/-/callsites-3.1.0.tgz#b3630abd8943432f54b3f0519238e33cd7df2f73" - integrity sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ== - -camelcase@^5.3.1: - version "5.3.1" - resolved "https://registry.yarnpkg.com/camelcase/-/camelcase-5.3.1.tgz#e3c9b31569e106811df242f715725a1f4c494320" - integrity sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg== - -camelcase@^6.2.0: - version "6.3.0" - resolved "https://registry.yarnpkg.com/camelcase/-/camelcase-6.3.0.tgz#5685b95eb209ac9c0c177467778c9c84df58ba9a" - integrity sha512-Gmy6FhYlCY7uOElZUSbxo2UCDH8owEk996gkbrpsgGtrJLM3J7jGxl9Ic7Qwwj4ivOE5AWZWRMecDdF7hqGjFA== - -caniuse-lite@^1.0.30001759: - version "1.0.30001764" - resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001764.tgz#03206c56469f236103b90f9ae10bcb8b9e1f6005" - integrity sha512-9JGuzl2M+vPL+pz70gtMF9sHdMFbY9FJaQBi186cHKH3pSzDvzoUJUPV6fqiKIMyXbud9ZLg4F3Yza1vJ1+93g== - -chalk@^4.0.0: - version "4.1.2" - resolved "https://registry.yarnpkg.com/chalk/-/chalk-4.1.2.tgz#aac4e2b7734a740867aeb16bf02aad556a1e7a01" - integrity sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA== - dependencies: - ansi-styles "^4.1.0" - supports-color "^7.1.0" - -char-regex@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/char-regex/-/char-regex-1.0.2.tgz#d744358226217f981ed58f479b1d6bcc29545dcf" - integrity sha512-kWWXztvZ5SBQV+eRgKFeh8q5sLuZY2+8WUIzlxWVTg+oGwY14qylx1KbKzHd8P6ZYkAg0xyIDU9JMHhyJMZ1jw== - -chardet@^0.7.0: - version "0.7.0" - resolved "https://registry.yarnpkg.com/chardet/-/chardet-0.7.0.tgz#90094849f0937f2eedc2425d0d28a9e5f0cbad9e" - integrity sha512-mT8iDcrh03qDGRRmoA2hmBJnxpllMR+0/0qlzjqZES6NdiWDcZkCNAk4rPFZ9Q85r27unkiNNg8ZOiwZXBHwcA== - -ci-info@^3.2.0: - version "3.9.0" - resolved "https://registry.yarnpkg.com/ci-info/-/ci-info-3.9.0.tgz#4279a62028a7b1f262f3473fc9605f5e218c59b4" - integrity sha512-NIxF55hv4nSqQswkAeiOi1r83xy8JldOFDTWiug55KBu9Jnblncd2U6ViHmYgHf01TPZS77NJBhBMKdWj9HQMQ== - -cjs-module-lexer@^1.0.0: - version "1.4.3" - resolved "https://registry.yarnpkg.com/cjs-module-lexer/-/cjs-module-lexer-1.4.3.tgz#0f79731eb8cfe1ec72acd4066efac9d61991b00d" - integrity sha512-9z8TZaGM1pfswYeXrUpzPrkx8UnWYdhJclsiYMm6x/w5+nN+8Tf/LnAgfLGQCm59qAOxU8WwHEq2vNwF6i4j+Q== - -clean-stack@^2.0.0: - version "2.2.0" - resolved "https://registry.yarnpkg.com/clean-stack/-/clean-stack-2.2.0.tgz#ee8472dbb129e727b31e8a10a427dee9dfe4008b" - integrity sha512-4diC9HaTE+KRAMWhDhrGOECgWZxoevMc5TlkObMqNSsVU62PYzXZ/SMTjzyGAFF1YusgxGcSWTEXBhp0CPwQ1A== - -cli-width@^4.1.0: - version "4.1.0" - resolved "https://registry.yarnpkg.com/cli-width/-/cli-width-4.1.0.tgz#42daac41d3c254ef38ad8ac037672130173691c5" - integrity sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ== - -cliui@^8.0.1: - version "8.0.1" - resolved "https://registry.yarnpkg.com/cliui/-/cliui-8.0.1.tgz#0c04b075db02cbfe60dc8e6cf2f5486b1a3608aa" - integrity sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ== - dependencies: - string-width "^4.2.0" - strip-ansi "^6.0.1" - wrap-ansi "^7.0.0" - -co@^4.6.0: - version "4.6.0" - resolved "https://registry.yarnpkg.com/co/-/co-4.6.0.tgz#6ea6bdf3d853ae54ccb8e47bfa0bf3f9031fb184" - integrity sha512-QVb0dM5HvG+uaxitm8wONl7jltx8dqhfU33DcqtOZcLSVIKSDDLDi7+0LbAKiyI8hD9u42m2YxXSkMGWThaecQ== - -code-block-writer@^12.0.0: - version "12.0.0" - resolved "https://registry.yarnpkg.com/code-block-writer/-/code-block-writer-12.0.0.tgz#4dd58946eb4234105aff7f0035977b2afdc2a770" - integrity sha512-q4dMFMlXtKR3XNBHyMHt/3pwYNA69EDk00lloMOaaUMKPUXBw6lpXtbu3MMVG6/uOihGnRDOlkyqsONEUj60+w== - -collect-v8-coverage@^1.0.0: - version "1.0.3" - resolved "https://registry.yarnpkg.com/collect-v8-coverage/-/collect-v8-coverage-1.0.3.tgz#cc1f01eb8d02298cbc9a437c74c70ab4e5210b80" - integrity sha512-1L5aqIkwPfiodaMgQunkF1zRhNqifHBmtbbbxcr6yVxxBnliw4TDOW6NxpO8DJLgJ16OT+Y4ztZqP6p/FtXnAw== - -color-convert@^2.0.1: - version "2.0.1" - resolved "https://registry.yarnpkg.com/color-convert/-/color-convert-2.0.1.tgz#72d3a68d598c9bdb3af2ad1e84f21d896abd4de3" - integrity sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ== - dependencies: - color-name "~1.1.4" - -color-name@~1.1.4: - version "1.1.4" - resolved "https://registry.yarnpkg.com/color-name/-/color-name-1.1.4.tgz#c2a09a87acbde69543de6f63fa3995c826c536a2" - integrity sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA== - -colorette@^2.0.7: - version "2.0.20" - resolved "https://registry.yarnpkg.com/colorette/-/colorette-2.0.20.tgz#9eb793e6833067f7235902fcd3b09917a000a95a" - integrity sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w== - -commander@^13.1.0: - version "13.1.0" - resolved "https://registry.yarnpkg.com/commander/-/commander-13.1.0.tgz#776167db68c78f38dcce1f9b8d7b8b9a488abf46" - integrity sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw== - -concat-map@0.0.1: - version "0.0.1" - resolved "https://registry.yarnpkg.com/concat-map/-/concat-map-0.0.1.tgz#d8a96bd77fd68df7793a73036a3ba0d5405d477b" - integrity sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg== - -content-disposition@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/content-disposition/-/content-disposition-1.0.1.tgz#a8b7bbeb2904befdfb6787e5c0c086959f605f9b" - integrity sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q== - -content-type@^1.0.5: - version "1.0.5" - resolved "https://registry.yarnpkg.com/content-type/-/content-type-1.0.5.tgz#8b773162656d1d1086784c8f23a54ce6d73d7918" - integrity sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA== - -convert-source-map@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/convert-source-map/-/convert-source-map-2.0.0.tgz#4b560f649fc4e918dd0ab75cf4961e8bc882d82a" - integrity sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg== - -cookie-parser@^1.4.6: - version "1.4.7" - resolved "https://registry.yarnpkg.com/cookie-parser/-/cookie-parser-1.4.7.tgz#e2125635dfd766888ffe90d60c286404fa0e7b26" - integrity sha512-nGUvgXnotP3BsjiLX2ypbQnWoGUPIIfHQNZkkC668ntrzGWEZVW70HDEB1qnNGMicPje6EttlIgzo51YSwNQGw== - dependencies: - cookie "0.7.2" - cookie-signature "1.0.6" - -cookie-signature@1.0.6: - version "1.0.6" - resolved "https://registry.yarnpkg.com/cookie-signature/-/cookie-signature-1.0.6.tgz#e303a882b342cc3ee8ca513a79999734dab3ae2c" - integrity sha512-QADzlaHc8icV8I7vbaJXJwod9HWYp8uCqf1xa4OfNu1T7JVxQIrUgOWtHdNDtPiywmFbiS12VjotIXLrKM3orQ== - -cookie-signature@^1.2.1: - version "1.2.2" - resolved "https://registry.yarnpkg.com/cookie-signature/-/cookie-signature-1.2.2.tgz#57c7fc3cc293acab9fec54d73e15690ebe4a1793" - integrity sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg== - -cookie@0.7.2, cookie@^0.7.1: - version "0.7.2" - resolved "https://registry.yarnpkg.com/cookie/-/cookie-0.7.2.tgz#556369c472a2ba910f2979891b526b3436237ed7" - integrity sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w== - -cors@^2.8.5: - version "2.8.5" - resolved "https://registry.yarnpkg.com/cors/-/cors-2.8.5.tgz#eac11da51592dd86b9f06f6e7ac293b3df875d29" - integrity sha512-KIHbLJqu73RGr/hnbrO9uBeixNGuvSQjul/jdFvS/KFSIH1hWVd1ng7zOHx+YrEfInLG7q4n6GHQ9cDtxv/P6g== - dependencies: - object-assign "^4" - vary "^1" - -create-jest@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/create-jest/-/create-jest-29.7.0.tgz#a355c5b3cb1e1af02ba177fe7afd7feee49a5320" - integrity sha512-Adz2bdH0Vq3F53KEMJOoftQFutWCukm6J24wbPWRO4k1kMY7gS7ds/uoJkNuV8wDCtWWnuwGcJwpWcih+zEW1Q== - dependencies: - "@jest/types" "^29.6.3" - chalk "^4.0.0" - exit "^0.1.2" - graceful-fs "^4.2.9" - jest-config "^29.7.0" - jest-util "^29.7.0" - prompts "^2.0.1" - -create-require@^1.1.0: - version "1.1.1" - resolved "https://registry.yarnpkg.com/create-require/-/create-require-1.1.1.tgz#c1d7e8f1e5f6cfc9ff65f9cd352d37348756c333" - integrity sha512-dcKFX3jn0MpIaXjisoRvexIJVEKzaq7z2rZKxf+MSr9TkdmHmsU4m2lcLojrj/FHl8mk5VxMmYA+ftRkP/3oKQ== - -cross-spawn@^7.0.3, cross-spawn@^7.0.5, cross-spawn@^7.0.6: - version "7.0.6" - resolved "https://registry.yarnpkg.com/cross-spawn/-/cross-spawn-7.0.6.tgz#8a58fe78f00dcd70c370451759dfbfaf03e8ee9f" - integrity sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA== - dependencies: - path-key "^3.1.0" - shebang-command "^2.0.0" - which "^2.0.1" - -dateformat@^4.6.3: - version "4.6.3" - resolved "https://registry.yarnpkg.com/dateformat/-/dateformat-4.6.3.tgz#556fa6497e5217fedb78821424f8a1c22fa3f4b5" - integrity sha512-2P0p0pFGzHS5EMnhdxQi7aJN+iMheud0UhG4dlE1DLAlvL8JHjJJTX/CSm4JXwV0Ka5nGk3zC5mcb5bUQUxxMA== - -debug@^4.1.0, debug@^4.1.1, debug@^4.3.1, debug@^4.3.2, debug@^4.3.4, debug@^4.3.7, debug@^4.4.0, debug@^4.4.3: - version "4.4.3" - resolved "https://registry.yarnpkg.com/debug/-/debug-4.4.3.tgz#c6ae432d9bd9662582fce08709b038c58e9e3d6a" - integrity sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA== - dependencies: - ms "^2.1.3" - -dedent@^1.0.0: - version "1.7.1" - resolved "https://registry.yarnpkg.com/dedent/-/dedent-1.7.1.tgz#364661eea3d73f3faba7089214420ec2f8f13e15" - integrity sha512-9JmrhGZpOlEgOLdQgSm0zxFaYoQon408V1v49aqTWuXENVlnCuY9JBZcXZiCsZQWDjTm5Qf/nIvAy77mXDAjEg== - -deep-is@^0.1.3: - version "0.1.4" - resolved "https://registry.yarnpkg.com/deep-is/-/deep-is-0.1.4.tgz#a6f2dce612fadd2ef1f519b73551f17e85199831" - integrity sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ== - -deepmerge@^4.2.2: - version "4.3.1" - resolved "https://registry.yarnpkg.com/deepmerge/-/deepmerge-4.3.1.tgz#44b5f2147cd3b00d4b56137685966f26fd25dd4a" - integrity sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A== - -depd@^2.0.0, depd@~2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/depd/-/depd-2.0.0.tgz#b696163cc757560d09cf22cc8fad1571b79e76df" - integrity sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw== - -detect-newline@^3.0.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/detect-newline/-/detect-newline-3.1.0.tgz#576f5dfc63ae1a192ff192d8ad3af6308991b651" - integrity sha512-TLz+x/vEXm/Y7P7wn1EJFNLxYpUD4TgMosxY6fAVJUnJMbupHBOncxyWUG9OpTaH9EBD7uFI5LfEgmMOc54DsA== - -diff-sequences@^29.6.3: - version "29.6.3" - resolved "https://registry.yarnpkg.com/diff-sequences/-/diff-sequences-29.6.3.tgz#4deaf894d11407c51efc8418012f9e70b84ea921" - integrity sha512-EjePK1srD3P08o2j4f0ExnylqRs5B9tJjcp9t1krH2qRi8CCdsYfwe9JgSLurFBWwq4uOlipzfk5fHNvwFKr8Q== - -diff@^4.0.1: - version "4.0.2" - resolved "https://registry.yarnpkg.com/diff/-/diff-4.0.2.tgz#60f3aecb89d5fae520c11aa19efc2bb982aade7d" - integrity sha512-58lmxKSA4BNyLz+HHMUzlOEpg09FV+ev6ZMe3vJihgdxzgcwZ8VoEEPmALCZG9LmqfVoNMMKpttIYTVG6uDY7A== - -dunder-proto@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/dunder-proto/-/dunder-proto-1.0.1.tgz#d7ae667e1dc83482f8b70fd0f6eefc50da30f58a" - integrity sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A== - dependencies: - call-bind-apply-helpers "^1.0.1" - es-errors "^1.3.0" - gopd "^1.2.0" - -ee-first@1.1.1: - version "1.1.1" - resolved "https://registry.yarnpkg.com/ee-first/-/ee-first-1.1.1.tgz#590c61156b0ae2f4f0255732a158b266bc56b21d" - integrity sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow== - -electron-to-chromium@^1.5.263: - version "1.5.267" - resolved "https://registry.yarnpkg.com/electron-to-chromium/-/electron-to-chromium-1.5.267.tgz#5d84f2df8cdb6bfe7e873706bb21bd4bfb574dc7" - integrity sha512-0Drusm6MVRXSOJpGbaSVgcQsuB4hEkMpHXaVstcPmhu5LIedxs1xNK/nIxmQIU/RPC0+1/o0AVZfBTkTNJOdUw== - -emittery@^0.13.1: - version "0.13.1" - resolved "https://registry.yarnpkg.com/emittery/-/emittery-0.13.1.tgz#c04b8c3457490e0847ae51fced3af52d338e3dad" - integrity sha512-DeWwawk6r5yR9jFgnDKYt4sLS0LmHJJi3ZOnb5/JdbYwj3nW+FxQnHIjhBKz8YLC7oRNPVM9NQ47I3CVx34eqQ== - -emoji-regex@^8.0.0: - version "8.0.0" - resolved "https://registry.yarnpkg.com/emoji-regex/-/emoji-regex-8.0.0.tgz#e818fd69ce5ccfcb404594f842963bf53164cc37" - integrity sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A== - -encodeurl@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/encodeurl/-/encodeurl-2.0.0.tgz#7b8ea898077d7e409d3ac45474ea38eaf0857a58" - integrity sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg== - -end-of-stream@^1.1.0: - version "1.4.5" - resolved "https://registry.yarnpkg.com/end-of-stream/-/end-of-stream-1.4.5.tgz#7344d711dea40e0b74abc2ed49778743ccedb08c" - integrity sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg== - dependencies: - once "^1.4.0" - -error-ex@^1.3.1: - version "1.3.4" - resolved "https://registry.yarnpkg.com/error-ex/-/error-ex-1.3.4.tgz#b3a8d8bb6f92eecc1629e3e27d3c8607a8a32414" - integrity sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ== - dependencies: - is-arrayish "^0.2.1" - -es-define-property@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/es-define-property/-/es-define-property-1.0.1.tgz#983eb2f9a6724e9303f61addf011c72e09e0b0fa" - integrity sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g== - -es-errors@^1.3.0: - version "1.3.0" - resolved "https://registry.yarnpkg.com/es-errors/-/es-errors-1.3.0.tgz#05f75a25dab98e4fb1dcd5e1472c0546d5057c8f" - integrity sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw== - -es-object-atoms@^1.0.0, es-object-atoms@^1.1.1: - version "1.1.1" - resolved "https://registry.yarnpkg.com/es-object-atoms/-/es-object-atoms-1.1.1.tgz#1c4f2c4837327597ce69d2ca190a7fdd172338c1" - integrity sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA== - dependencies: - es-errors "^1.3.0" - -escalade@^3.1.1, escalade@^3.2.0: - version "3.2.0" - resolved "https://registry.yarnpkg.com/escalade/-/escalade-3.2.0.tgz#011a3f69856ba189dffa7dc8fcce99d2a87903e5" - integrity sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA== - -escape-html@^1.0.3: - version "1.0.3" - resolved "https://registry.yarnpkg.com/escape-html/-/escape-html-1.0.3.tgz#0258eae4d3d0c0974de1c169188ef0051d1d1988" - integrity sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow== - -escape-string-regexp@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz#a30304e99daa32e23b2fd20f51babd07cffca344" - integrity sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w== - -escape-string-regexp@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz#14ba83a5d373e3d311e5afca29cf5bfad965bf34" - integrity sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA== - -eslint-plugin-prettier@^5.4.1: - version "5.5.5" - resolved "https://registry.yarnpkg.com/eslint-plugin-prettier/-/eslint-plugin-prettier-5.5.5.tgz#9eae11593faa108859c26f9a9c367d619a0769c0" - integrity sha512-hscXkbqUZ2sPithAuLm5MXL+Wph+U7wHngPBv9OMWwlP8iaflyxpjTYZkmdgB4/vPIhemRlBEoLrH7UC1n7aUw== - dependencies: - prettier-linter-helpers "^1.0.1" - synckit "^0.11.12" - -eslint-plugin-unused-imports@^4.1.4: - version "4.4.1" - resolved "https://registry.yarnpkg.com/eslint-plugin-unused-imports/-/eslint-plugin-unused-imports-4.4.1.tgz#a831f0a2937d7631eba30cb87091ab7d3a5da0e1" - integrity sha512-oZGYUz1X3sRMGUB+0cZyK2VcvRX5lm/vB56PgNNcU+7ficUCKm66oZWKUubXWnOuPjQ8PvmXtCViXBMONPe7tQ== - -eslint-scope@^8.4.0: - version "8.4.0" - resolved "https://registry.yarnpkg.com/eslint-scope/-/eslint-scope-8.4.0.tgz#88e646a207fad61436ffa39eb505147200655c82" - integrity sha512-sNXOfKCn74rt8RICKMvJS7XKV/Xk9kA7DyJr8mJik3S7Cwgy3qlkkmyS2uQB3jiJg6VNdZd/pDBJu0nvG2NlTg== - dependencies: - esrecurse "^4.3.0" - estraverse "^5.2.0" - -eslint-visitor-keys@^3.4.3: - version "3.4.3" - resolved "https://registry.yarnpkg.com/eslint-visitor-keys/-/eslint-visitor-keys-3.4.3.tgz#0cd72fe8550e3c2eae156a96a4dddcd1c8ac5800" - integrity sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag== - -eslint-visitor-keys@^4.2.0, eslint-visitor-keys@^4.2.1: - version "4.2.1" - resolved "https://registry.yarnpkg.com/eslint-visitor-keys/-/eslint-visitor-keys-4.2.1.tgz#4cfea60fe7dd0ad8e816e1ed026c1d5251b512c1" - integrity sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ== - -eslint@^9.39.1: - version "9.39.4" - resolved "https://registry.yarnpkg.com/eslint/-/eslint-9.39.4.tgz#855da1b2e2ad66dc5991195f35e262bcec8117b5" - integrity sha512-XoMjdBOwe/esVgEvLmNsD3IRHkm7fbKIUGvrleloJXUZgDHig2IPWNniv+GwjyJXzuNqVjlr5+4yVUZjycJwfQ== - dependencies: - "@eslint-community/eslint-utils" "^4.8.0" - "@eslint-community/regexpp" "^4.12.1" - "@eslint/config-array" "^0.21.2" - "@eslint/config-helpers" "^0.4.2" - "@eslint/core" "^0.17.0" - "@eslint/eslintrc" "^3.3.5" - "@eslint/js" "9.39.4" - "@eslint/plugin-kit" "^0.4.1" - "@humanfs/node" "^0.16.6" - "@humanwhocodes/module-importer" "^1.0.1" - "@humanwhocodes/retry" "^0.4.2" - "@types/estree" "^1.0.6" - ajv "^6.14.0" - chalk "^4.0.0" - cross-spawn "^7.0.6" - debug "^4.3.2" - escape-string-regexp "^4.0.0" - eslint-scope "^8.4.0" - eslint-visitor-keys "^4.2.1" - espree "^10.4.0" - esquery "^1.5.0" - esutils "^2.0.2" - fast-deep-equal "^3.1.3" - file-entry-cache "^8.0.0" - find-up "^5.0.0" - glob-parent "^6.0.2" - ignore "^5.2.0" - imurmurhash "^0.1.4" - is-glob "^4.0.0" - json-stable-stringify-without-jsonify "^1.0.1" - lodash.merge "^4.6.2" - minimatch "^3.1.5" - natural-compare "^1.4.0" - optionator "^0.9.3" - -espree@^10.0.1, espree@^10.4.0: - version "10.4.0" - resolved "https://registry.yarnpkg.com/espree/-/espree-10.4.0.tgz#d54f4949d4629005a1fa168d937c3ff1f7e2a837" - integrity sha512-j6PAQ2uUr79PZhBjP5C5fhl8e39FmRnOjsD5lGnWrFU8i2G776tBK7+nP8KuQUTTyAZUwfQqXAgrVH5MbH9CYQ== - dependencies: - acorn "^8.15.0" - acorn-jsx "^5.3.2" - eslint-visitor-keys "^4.2.1" - -esprima@^4.0.0: - version "4.0.1" - resolved "https://registry.yarnpkg.com/esprima/-/esprima-4.0.1.tgz#13b04cdb3e6c5d19df91ab6987a8695619b0aa71" - integrity sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A== - -esquery@^1.5.0: - version "1.7.0" - resolved "https://registry.yarnpkg.com/esquery/-/esquery-1.7.0.tgz#08d048f261f0ddedb5bae95f46809463d9c9496d" - integrity sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g== - dependencies: - estraverse "^5.1.0" - -esrecurse@^4.3.0: - version "4.3.0" - resolved "https://registry.yarnpkg.com/esrecurse/-/esrecurse-4.3.0.tgz#7ad7964d679abb28bee72cec63758b1c5d2c9921" - integrity sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag== - dependencies: - estraverse "^5.2.0" - -estraverse@^5.1.0, estraverse@^5.2.0: - version "5.3.0" - resolved "https://registry.yarnpkg.com/estraverse/-/estraverse-5.3.0.tgz#2eea5290702f26ab8fe5370370ff86c965d21123" - integrity sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA== - -esutils@^2.0.2: - version "2.0.3" - resolved "https://registry.yarnpkg.com/esutils/-/esutils-2.0.3.tgz#74d2eb4de0b8da1293711910d50775b9b710ef64" - integrity sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g== - -etag@^1.8.1: - version "1.8.1" - resolved "https://registry.yarnpkg.com/etag/-/etag-1.8.1.tgz#41ae2eeb65efa62268aebfea83ac7d79299b0887" - integrity sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg== - -eventsource-parser@^3.0.0, eventsource-parser@^3.0.1: - version "3.0.6" - resolved "https://registry.yarnpkg.com/eventsource-parser/-/eventsource-parser-3.0.6.tgz#292e165e34cacbc936c3c92719ef326d4aeb4e90" - integrity sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg== - -eventsource@^3.0.2: - version "3.0.7" - resolved "https://registry.yarnpkg.com/eventsource/-/eventsource-3.0.7.tgz#1157622e2f5377bb6aef2114372728ba0c156989" - integrity sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA== - dependencies: - eventsource-parser "^3.0.1" - -execa@^5.0.0: - version "5.1.1" - resolved "https://registry.yarnpkg.com/execa/-/execa-5.1.1.tgz#f80ad9cbf4298f7bd1d4c9555c21e93741c411dd" - integrity sha512-8uSpZZocAZRBAPIEINJj3Lo9HyGitllczc27Eh5YYojjMFMn8yHMDMaUHE2Jqfq05D/wucwI4JGURyXt1vchyg== - dependencies: - cross-spawn "^7.0.3" - get-stream "^6.0.0" - human-signals "^2.1.0" - is-stream "^2.0.0" - merge-stream "^2.0.0" - npm-run-path "^4.0.1" - onetime "^5.1.2" - signal-exit "^3.0.3" - strip-final-newline "^2.0.0" - -exit@^0.1.2: - version "0.1.2" - resolved "https://registry.yarnpkg.com/exit/-/exit-0.1.2.tgz#0632638f8d877cc82107d30a0fff1a17cba1cd0c" - integrity sha512-Zk/eNKV2zbjpKzrsQ+n1G6poVbErQxJ0LBOJXaKZ1EViLzH+hrLu9cdXI4zw9dBQJslwBEpbQ2P1oS7nDxs6jQ== - -expect@^29.0.0, expect@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/expect/-/expect-29.7.0.tgz#578874590dcb3214514084c08115d8aee61e11bc" - integrity sha512-2Zks0hf1VLFYI1kbh0I5jP3KHHyCHpkfyHBzsSXRFgl/Bg9mWYfMW8oD+PdMPlEwy5HNsR9JutYy6pMeOh61nw== - dependencies: - "@jest/expect-utils" "^29.7.0" - jest-get-type "^29.6.3" - jest-matcher-utils "^29.7.0" - jest-message-util "^29.7.0" - jest-util "^29.7.0" - -express-rate-limit@^8.2.1: - version "8.3.1" - resolved "https://registry.yarnpkg.com/express-rate-limit/-/express-rate-limit-8.3.1.tgz#0aaba098eadd40f6737f30a98e6b16fa1a29edfb" - integrity sha512-D1dKN+cmyPWuvB+G2SREQDzPY1agpBIcTa9sJxOPMCNeH3gwzhqJRDWCXW3gg0y//+LQ/8j52JbMROWyrKdMdw== - dependencies: - ip-address "10.1.0" - -express@^5.1.0, express@^5.2.1: - version "5.2.1" - resolved "https://registry.yarnpkg.com/express/-/express-5.2.1.tgz#8f21d15b6d327f92b4794ecf8cb08a72f956ac04" - integrity sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw== - dependencies: - accepts "^2.0.0" - body-parser "^2.2.1" - content-disposition "^1.0.0" - content-type "^1.0.5" - cookie "^0.7.1" - cookie-signature "^1.2.1" - debug "^4.4.0" - depd "^2.0.0" - encodeurl "^2.0.0" - escape-html "^1.0.3" - etag "^1.8.1" - finalhandler "^2.1.0" - fresh "^2.0.0" - http-errors "^2.0.0" - merge-descriptors "^2.0.0" - mime-types "^3.0.0" - on-finished "^2.4.1" - once "^1.4.0" - parseurl "^1.3.3" - proxy-addr "^2.0.7" - qs "^6.14.0" - range-parser "^1.2.1" - router "^2.2.0" - send "^1.1.0" - serve-static "^2.2.0" - statuses "^2.0.1" - type-is "^2.0.1" - vary "^1.1.2" - -external-editor@^3.1.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/external-editor/-/external-editor-3.1.0.tgz#cb03f740befae03ea4d283caed2741a83f335495" - integrity sha512-hMQ4CX1p1izmuLYyZqLMO/qGNw10wSv9QDCPfzXfyFrOaCSSoRfqE1Kf1s5an66J5JZC62NewG+mK49jOCtQew== - dependencies: - chardet "^0.7.0" - iconv-lite "^0.4.24" - tmp "^0.0.33" - -fast-copy@^4.0.0: - version "4.0.2" - resolved "https://registry.yarnpkg.com/fast-copy/-/fast-copy-4.0.2.tgz#57f14115e1edbec274f69090072a480aa29cbedd" - integrity sha512-ybA6PDXIXOXivLJK/z9e+Otk7ve13I4ckBvGO5I2RRmBU1gMHLVDJYEuJYhGwez7YNlYji2M2DvVU+a9mSFDlw== - -fast-deep-equal@^3.1.1, fast-deep-equal@^3.1.3: - version "3.1.3" - resolved "https://registry.yarnpkg.com/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz#3a7d56b559d6cbc3eb512325244e619a65c6c525" - integrity sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q== - -fast-diff@^1.1.2: - version "1.3.0" - resolved "https://registry.yarnpkg.com/fast-diff/-/fast-diff-1.3.0.tgz#ece407fa550a64d638536cd727e129c61616e0f0" - integrity sha512-VxPP4NqbUjj6MaAOafWeUn2cXWLcCtljklUtZf0Ind4XQ+QPtmA0b18zZy0jIQx+ExRVCR/ZQpBmik5lXshNsw== - -fast-glob@^3.2.12, fast-glob@^3.3.2: - version "3.3.3" - resolved "https://registry.yarnpkg.com/fast-glob/-/fast-glob-3.3.3.tgz#d06d585ce8dba90a16b0505c543c3ccfb3aeb818" - integrity sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg== - dependencies: - "@nodelib/fs.stat" "^2.0.2" - "@nodelib/fs.walk" "^1.2.3" - glob-parent "^5.1.2" - merge2 "^1.3.0" - micromatch "^4.0.8" - -fast-json-stable-stringify@2.x, fast-json-stable-stringify@^2.0.0, fast-json-stable-stringify@^2.1.0: - version "2.1.0" - resolved "https://registry.yarnpkg.com/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz#874bf69c6f404c2b5d99c481341399fd55892633" - integrity sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw== - -fast-levenshtein@^2.0.6: - version "2.0.6" - resolved "https://registry.yarnpkg.com/fast-levenshtein/-/fast-levenshtein-2.0.6.tgz#3d8a5c66883a16a30ca8643e851f19baa7797917" - integrity sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw== - -fast-safe-stringify@^2.1.1: - version "2.1.1" - resolved "https://registry.yarnpkg.com/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz#c406a83b6e70d9e35ce3b30a81141df30aeba884" - integrity sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA== - -fast-uri@^3.0.1: - version "3.1.0" - resolved "https://registry.yarnpkg.com/fast-uri/-/fast-uri-3.1.0.tgz#66eecff6c764c0df9b762e62ca7edcfb53b4edfa" - integrity sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA== - -fastq@^1.6.0: - version "1.20.1" - resolved "https://registry.yarnpkg.com/fastq/-/fastq-1.20.1.tgz#ca750a10dc925bc8b18839fd203e3ef4b3ced675" - integrity sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw== - dependencies: - reusify "^1.0.4" - -fb-watchman@^2.0.0: - version "2.0.2" - resolved "https://registry.yarnpkg.com/fb-watchman/-/fb-watchman-2.0.2.tgz#e9524ee6b5c77e9e5001af0f85f3adbb8623255c" - integrity sha512-p5161BqbuCaSnB8jIbzQHOlpgsPmK5rJVDfDKO91Axs5NC1uu3HRQm6wt9cd9/+GtQQIO53JdGXXoyDpTAsgYA== - dependencies: - bser "2.1.1" - -fflate@^0.8.2: - version "0.8.2" - resolved "https://registry.yarnpkg.com/fflate/-/fflate-0.8.2.tgz#fc8631f5347812ad6028bbe4a2308b2792aa1dea" - integrity sha512-cPJU47OaAoCbg0pBvzsgpTPhmhqI5eJjh/JIu8tPj5q+T7iLvW/JAYUqmE7KOB4R1ZyEhzBaIQpQpardBF5z8A== - -file-entry-cache@^8.0.0: - version "8.0.0" - resolved "https://registry.yarnpkg.com/file-entry-cache/-/file-entry-cache-8.0.0.tgz#7787bddcf1131bffb92636c69457bbc0edd6d81f" - integrity sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ== - dependencies: - flat-cache "^4.0.0" - -fill-range@^7.1.1: - version "7.1.1" - resolved "https://registry.yarnpkg.com/fill-range/-/fill-range-7.1.1.tgz#44265d3cac07e3ea7dc247516380643754a05292" - integrity sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg== - dependencies: - to-regex-range "^5.0.1" - -finalhandler@^2.1.0: - version "2.1.1" - resolved "https://registry.yarnpkg.com/finalhandler/-/finalhandler-2.1.1.tgz#a2c517a6559852bcdb06d1f8bd7f51b68fad8099" - integrity sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA== - dependencies: - debug "^4.4.0" - encodeurl "^2.0.0" - escape-html "^1.0.3" - on-finished "^2.4.1" - parseurl "^1.3.3" - statuses "^2.0.1" - -find-up@^4.0.0, find-up@^4.1.0: - version "4.1.0" - resolved "https://registry.yarnpkg.com/find-up/-/find-up-4.1.0.tgz#97afe7d6cdc0bc5928584b7c8d7b16e8a9aa5d19" - integrity sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw== - dependencies: - locate-path "^5.0.0" - path-exists "^4.0.0" - -find-up@^5.0.0: - version "5.0.0" - resolved "https://registry.yarnpkg.com/find-up/-/find-up-5.0.0.tgz#4c92819ecb7083561e4f4a240a86be5198f536fc" - integrity sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng== - dependencies: - locate-path "^6.0.0" - path-exists "^4.0.0" - -flat-cache@^4.0.0: - version "4.0.1" - resolved "https://registry.yarnpkg.com/flat-cache/-/flat-cache-4.0.1.tgz#0ece39fcb14ee012f4b0410bd33dd9c1f011127c" - integrity sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw== - dependencies: - flatted "^3.2.9" - keyv "^4.5.4" - -flatted@^3.2.9: - version "3.3.3" - resolved "https://registry.yarnpkg.com/flatted/-/flatted-3.3.3.tgz#67c8fad95454a7c7abebf74bb78ee74a44023358" - integrity sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg== - -flora-colossus@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/flora-colossus/-/flora-colossus-2.0.0.tgz#af1e85db0a8256ef05f3fb531c1235236c97220a" - integrity sha512-dz4HxH6pOvbUzZpZ/yXhafjbR2I8cenK5xL0KtBFb7U2ADsR+OwXifnxZjij/pZWF775uSCMzWVd+jDik2H2IA== - dependencies: - debug "^4.3.4" - fs-extra "^10.1.0" - -forwarded@0.2.0: - version "0.2.0" - resolved "https://registry.yarnpkg.com/forwarded/-/forwarded-0.2.0.tgz#2269936428aad4c15c7ebe9779a84bf0b2a81811" - integrity sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow== - -fresh@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/fresh/-/fresh-2.0.0.tgz#8dd7df6a1b3a1b3a5cf186c05a5dd267622635a4" - integrity sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A== - -fs-extra@^10.1.0: - version "10.1.0" - resolved "https://registry.yarnpkg.com/fs-extra/-/fs-extra-10.1.0.tgz#02873cfbc4084dde127eaa5f9905eef2325d1abf" - integrity sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ== - dependencies: - graceful-fs "^4.2.0" - jsonfile "^6.0.1" - universalify "^2.0.0" - -fs.realpath@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/fs.realpath/-/fs.realpath-1.0.0.tgz#1504ad2523158caa40db4a2787cb01411994ea4f" - integrity sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw== - -fsevents@^2.3.2: - version "2.3.3" - resolved "https://registry.yarnpkg.com/fsevents/-/fsevents-2.3.3.tgz#cac6407785d03675a2a5e1a5305c697b347d90d6" - integrity sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw== - -function-bind@^1.1.2: - version "1.1.2" - resolved "https://registry.yarnpkg.com/function-bind/-/function-bind-1.1.2.tgz#2c02d864d97f3ea6c8830c464cbd11ab6eab7a1c" - integrity sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA== - -fuse.js@^7.1.0: - version "7.1.0" - resolved "https://registry.yarnpkg.com/fuse.js/-/fuse.js-7.1.0.tgz#306228b4befeee11e05b027087c2744158527d09" - integrity sha512-trLf4SzuuUxfusZADLINj+dE8clK1frKdmqiJNb1Es75fmI5oY6X2mxLVUciLLjxqw/xr72Dhy+lER6dGd02FQ== - -galactus@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/galactus/-/galactus-1.0.0.tgz#c2615182afa0c6d0859b92e56ae36d052827db7e" - integrity sha512-R1fam6D4CyKQGNlvJne4dkNF+PvUUl7TAJInvTGa9fti9qAv95quQz29GXapA4d8Ec266mJJxFVh82M4GIIGDQ== - dependencies: - debug "^4.3.4" - flora-colossus "^2.0.0" - fs-extra "^10.1.0" - -gensync@^1.0.0-beta.2: - version "1.0.0-beta.2" - resolved "https://registry.yarnpkg.com/gensync/-/gensync-1.0.0-beta.2.tgz#32a6ee76c3d7f52d46b2b1ae5d93fea8580a25e0" - integrity sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg== - -get-caller-file@^2.0.5: - version "2.0.5" - resolved "https://registry.yarnpkg.com/get-caller-file/-/get-caller-file-2.0.5.tgz#4f94412a82db32f36e3b0b9741f8a97feb031f7e" - integrity sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg== - -get-intrinsic@^1.2.5, get-intrinsic@^1.3.0: - version "1.3.0" - resolved "https://registry.yarnpkg.com/get-intrinsic/-/get-intrinsic-1.3.0.tgz#743f0e3b6964a93a5491ed1bffaae054d7f98d01" - integrity sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ== - dependencies: - call-bind-apply-helpers "^1.0.2" - es-define-property "^1.0.1" - es-errors "^1.3.0" - es-object-atoms "^1.1.1" - function-bind "^1.1.2" - get-proto "^1.0.1" - gopd "^1.2.0" - has-symbols "^1.1.0" - hasown "^2.0.2" - math-intrinsics "^1.1.0" - -get-package-type@^0.1.0: - version "0.1.0" - resolved "https://registry.yarnpkg.com/get-package-type/-/get-package-type-0.1.0.tgz#8de2d803cff44df3bc6c456e6668b36c3926e11a" - integrity sha512-pjzuKtY64GYfWizNAJ0fr9VqttZkNiK2iS430LtIHzjBEr6bX8Am2zm4sW4Ro5wjWW5cAlRL1qAMTcXbjNAO2Q== - -get-proto@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/get-proto/-/get-proto-1.0.1.tgz#150b3f2743869ef3e851ec0c49d15b1d14d00ee1" - integrity sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g== - dependencies: - dunder-proto "^1.0.1" - es-object-atoms "^1.0.0" - -get-stdin@^8.0.0: - version "8.0.0" - resolved "https://registry.yarnpkg.com/get-stdin/-/get-stdin-8.0.0.tgz#cbad6a73feb75f6eeb22ba9e01f89aa28aa97a53" - integrity sha512-sY22aA6xchAzprjyqmSEQv4UbAAzRN0L2dQB0NlN5acTTK9Don6nhoc3eAbUnpZiCANAMfd/+40kVdKfFygohg== - -get-stream@^6.0.0: - version "6.0.1" - resolved "https://registry.yarnpkg.com/get-stream/-/get-stream-6.0.1.tgz#a262d8eef67aced57c2852ad6167526a43cbf7b7" - integrity sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg== - -glob-parent@^5.1.2: - version "5.1.2" - resolved "https://registry.yarnpkg.com/glob-parent/-/glob-parent-5.1.2.tgz#869832c58034fe68a4093c17dc15e8340d8401c4" - integrity sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow== - dependencies: - is-glob "^4.0.1" - -glob-parent@^6.0.2: - version "6.0.2" - resolved "https://registry.yarnpkg.com/glob-parent/-/glob-parent-6.0.2.tgz#6d237d99083950c79290f24c7642a3de9a28f9e3" - integrity sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A== - dependencies: - is-glob "^4.0.3" - -glob@^7.1.3, glob@^7.1.4: - version "7.2.3" - resolved "https://registry.yarnpkg.com/glob/-/glob-7.2.3.tgz#b8df0fb802bbfa8e89bd1d938b4e16578ed44f2b" - integrity sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q== - dependencies: - fs.realpath "^1.0.0" - inflight "^1.0.4" - inherits "2" - minimatch "^3.1.1" - once "^1.3.0" - path-is-absolute "^1.0.0" - -globals@^14.0.0: - version "14.0.0" - resolved "https://registry.yarnpkg.com/globals/-/globals-14.0.0.tgz#898d7413c29babcf6bafe56fcadded858ada724e" - integrity sha512-oahGvuMGQlPw/ivIYBjVSrWAfWLBeku5tpPE2fOPLi+WHffIWbuh2tCjhyQhTBPMf5E9jDEH4FOmTYgYwbKwtQ== - -gopd@^1.2.0: - version "1.2.0" - resolved "https://registry.yarnpkg.com/gopd/-/gopd-1.2.0.tgz#89f56b8217bdbc8802bd299df6d7f1081d7e51a1" - integrity sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg== - -graceful-fs@^4.1.6, graceful-fs@^4.2.0, graceful-fs@^4.2.9: - version "4.2.11" - resolved "https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-4.2.11.tgz#4183e4e8bf08bb6e05bbb2f7d2e0c8f712ca40e3" - integrity sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ== - -graphemer@^1.4.0: - version "1.4.0" - resolved "https://registry.yarnpkg.com/graphemer/-/graphemer-1.4.0.tgz#fb2f1d55e0e3a1849aeffc90c4fa0dd53a0e66c6" - integrity sha512-EtKwoO6kxCL9WO5xipiHTZlSzBm7WLT627TqC/uVRd0HKmq8NXyebnNYxDoBi7wt8eTWrUrKXCOVaFq9x1kgag== - -handlebars@^4.7.8: - version "4.7.8" - resolved "https://registry.yarnpkg.com/handlebars/-/handlebars-4.7.8.tgz#41c42c18b1be2365439188c77c6afae71c0cd9e9" - integrity sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ== - dependencies: - minimist "^1.2.5" - neo-async "^2.6.2" - source-map "^0.6.1" - wordwrap "^1.0.0" - optionalDependencies: - uglify-js "^3.1.4" - -has-flag@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/has-flag/-/has-flag-4.0.0.tgz#944771fd9c81c81265c4d6941860da06bb59479b" - integrity sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ== - -has-symbols@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/has-symbols/-/has-symbols-1.1.0.tgz#fc9c6a783a084951d0b971fe1018de813707a338" - integrity sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ== - -hasown@^2.0.2: - version "2.0.2" - resolved "https://registry.yarnpkg.com/hasown/-/hasown-2.0.2.tgz#003eaf91be7adc372e84ec59dc37252cedb80003" - integrity sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ== - dependencies: - function-bind "^1.1.2" - -help-me@^5.0.0: - version "5.0.0" - resolved "https://registry.yarnpkg.com/help-me/-/help-me-5.0.0.tgz#b1ebe63b967b74060027c2ac61f9be12d354a6f6" - integrity sha512-7xgomUX6ADmcYzFik0HzAxh/73YlKR9bmFzf51CZwR+b6YtzU2m0u49hQCqV6SvlqIqsaxovfwdvbnsw3b/zpg== - -hono@^4.11.4, hono@^4.12.4: - version "4.12.7" - resolved "https://registry.yarnpkg.com/hono/-/hono-4.12.7.tgz#ca000956e965c2b3d791e43540498e616d6c6442" - integrity sha512-jq9l1DM0zVIvsm3lv9Nw9nlJnMNPOcAtsbsgiUhWcFzPE99Gvo6yRTlszSLLYacMeQ6quHD6hMfId8crVHvexw== - -html-escaper@^2.0.0: - version "2.0.2" - resolved "https://registry.yarnpkg.com/html-escaper/-/html-escaper-2.0.2.tgz#dfd60027da36a36dfcbe236262c00a5822681453" - integrity sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg== - -http-errors@^2.0.0, http-errors@^2.0.1, http-errors@~2.0.1: - version "2.0.1" - resolved "https://registry.yarnpkg.com/http-errors/-/http-errors-2.0.1.tgz#36d2f65bc909c8790018dd36fb4d93da6caae06b" - integrity sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ== - dependencies: - depd "~2.0.0" - inherits "~2.0.4" - setprototypeof "~1.2.0" - statuses "~2.0.2" - toidentifier "~1.0.1" - -human-signals@^2.1.0: - version "2.1.0" - resolved "https://registry.yarnpkg.com/human-signals/-/human-signals-2.1.0.tgz#dc91fcba42e4d06e4abaed33b3e7a3c02f514ea0" - integrity sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw== - -iconv-lite@^0.4.24: - version "0.4.24" - resolved "https://registry.yarnpkg.com/iconv-lite/-/iconv-lite-0.4.24.tgz#2022b4b25fbddc21d2f524974a474aafe733908b" - integrity sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA== - dependencies: - safer-buffer ">= 2.1.2 < 3" - -iconv-lite@^0.7.0, iconv-lite@~0.7.0: - version "0.7.2" - resolved "https://registry.yarnpkg.com/iconv-lite/-/iconv-lite-0.7.2.tgz#d0bdeac3f12b4835b7359c2ad89c422a4d1cc72e" - integrity sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw== - dependencies: - safer-buffer ">= 2.1.2 < 3.0.0" - -ignore@^5.2.0, ignore@^5.3.1: - version "5.3.2" - resolved "https://registry.yarnpkg.com/ignore/-/ignore-5.3.2.tgz#3cd40e729f3643fd87cb04e50bf0eb722bc596f5" - integrity sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g== - -ignore@^7.0.5: - version "7.0.5" - resolved "https://registry.yarnpkg.com/ignore/-/ignore-7.0.5.tgz#4cb5f6cd7d4c7ab0365738c7aea888baa6d7efd9" - integrity sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg== - -import-fresh@^3.2.1: - version "3.3.1" - resolved "https://registry.yarnpkg.com/import-fresh/-/import-fresh-3.3.1.tgz#9cecb56503c0ada1f2741dbbd6546e4b13b57ccf" - integrity sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ== - dependencies: - parent-module "^1.0.0" - resolve-from "^4.0.0" - -import-local@^3.0.2: - version "3.2.0" - resolved "https://registry.yarnpkg.com/import-local/-/import-local-3.2.0.tgz#c3d5c745798c02a6f8b897726aba5100186ee260" - integrity sha512-2SPlun1JUPWoM6t3F0dw0FkCF/jWY8kttcY4f599GLTSjh2OCuuhdTkJQsEcZzBqbXZGKMK2OqW1oZsjtf/gQA== - dependencies: - pkg-dir "^4.2.0" - resolve-cwd "^3.0.0" - -imurmurhash@^0.1.4: - version "0.1.4" - resolved "https://registry.yarnpkg.com/imurmurhash/-/imurmurhash-0.1.4.tgz#9218b9b2b928a238b13dc4fb6b6d576f231453ea" - integrity sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA== - -indent-string@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/indent-string/-/indent-string-4.0.0.tgz#624f8f4497d619b2d9768531d58f4122854d7251" - integrity sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg== - -inflight@^1.0.4: - version "1.0.6" - resolved "https://registry.yarnpkg.com/inflight/-/inflight-1.0.6.tgz#49bd6331d7d02d0c09bc910a1075ba8165b56df9" - integrity sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA== - dependencies: - once "^1.3.0" - wrappy "1" - -inherits@2, inherits@^2.0.3, inherits@~2.0.4: - version "2.0.4" - resolved "https://registry.yarnpkg.com/inherits/-/inherits-2.0.4.tgz#0fa2c64f932917c3433a0ded55363aae37416b7c" - integrity sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ== - -ip-address@10.1.0: - version "10.1.0" - resolved "https://registry.yarnpkg.com/ip-address/-/ip-address-10.1.0.tgz#d8dcffb34d0e02eb241427444a6e23f5b0595aa4" - integrity sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q== - -ipaddr.js@1.9.1: - version "1.9.1" - resolved "https://registry.yarnpkg.com/ipaddr.js/-/ipaddr.js-1.9.1.tgz#bff38543eeb8984825079ff3a2a8e6cbd46781b3" - integrity sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g== - -is-arrayish@^0.2.1: - version "0.2.1" - resolved "https://registry.yarnpkg.com/is-arrayish/-/is-arrayish-0.2.1.tgz#77c99840527aa8ecb1a8ba697b80645a7a926a9d" - integrity sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg== - -is-core-module@^2.16.1: - version "2.16.1" - resolved "https://registry.yarnpkg.com/is-core-module/-/is-core-module-2.16.1.tgz#2a98801a849f43e2add644fbb6bc6229b19a4ef4" - integrity sha512-UfoeMA6fIJ8wTYFEUjelnaGI67v6+N7qXJEvQuIGa99l4xsCruSYOVSQ0uPANn4dAzm8lkYPaKLrrijLq7x23w== - dependencies: - hasown "^2.0.2" - -is-extglob@^2.1.1: - version "2.1.1" - resolved "https://registry.yarnpkg.com/is-extglob/-/is-extglob-2.1.1.tgz#a88c02535791f02ed37c76a1b9ea9773c833f8c2" - integrity sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ== - -is-fullwidth-code-point@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz#f116f8064fe90b3f7844a38997c0b75051269f1d" - integrity sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg== - -is-generator-fn@^2.0.0: - version "2.1.0" - resolved "https://registry.yarnpkg.com/is-generator-fn/-/is-generator-fn-2.1.0.tgz#7d140adc389aaf3011a8f2a2a4cfa6faadffb118" - integrity sha512-cTIB4yPYL/Grw0EaSzASzg6bBy9gqCofvWN8okThAYIxKJZC+udlRAmGbM0XLeniEJSs8uEgHPGuHSe1XsOLSQ== - -is-glob@^4.0.0, is-glob@^4.0.1, is-glob@^4.0.3: - version "4.0.3" - resolved "https://registry.yarnpkg.com/is-glob/-/is-glob-4.0.3.tgz#64f61e42cbbb2eec2071a9dac0b28ba1e65d5084" - integrity sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg== - dependencies: - is-extglob "^2.1.1" - -is-number@^7.0.0: - version "7.0.0" - resolved "https://registry.yarnpkg.com/is-number/-/is-number-7.0.0.tgz#7535345b896734d5f80c4d06c50955527a14f12b" - integrity sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng== - -is-promise@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/is-promise/-/is-promise-4.0.0.tgz#42ff9f84206c1991d26debf520dd5c01042dd2f3" - integrity sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ== - -is-stream@^2.0.0: - version "2.0.1" - resolved "https://registry.yarnpkg.com/is-stream/-/is-stream-2.0.1.tgz#fac1e3d53b97ad5a9d0ae9cef2389f5810a5c077" - integrity sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg== - -isexe@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/isexe/-/isexe-2.0.0.tgz#e8fbf374dc556ff8947a10dcb0572d633f2cfa10" - integrity sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw== - -istanbul-lib-coverage@^3.0.0, istanbul-lib-coverage@^3.2.0: - version "3.2.2" - resolved "https://registry.yarnpkg.com/istanbul-lib-coverage/-/istanbul-lib-coverage-3.2.2.tgz#2d166c4b0644d43a39f04bf6c2edd1e585f31756" - integrity sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg== - -istanbul-lib-instrument@^5.0.4: - version "5.2.1" - resolved "https://registry.yarnpkg.com/istanbul-lib-instrument/-/istanbul-lib-instrument-5.2.1.tgz#d10c8885c2125574e1c231cacadf955675e1ce3d" - integrity sha512-pzqtp31nLv/XFOzXGuvhCb8qhjmTVo5vjVk19XE4CRlSWz0KoeJ3bw9XsA7nOp9YBf4qHjwBxkDzKcME/J29Yg== - dependencies: - "@babel/core" "^7.12.3" - "@babel/parser" "^7.14.7" - "@istanbuljs/schema" "^0.1.2" - istanbul-lib-coverage "^3.2.0" - semver "^6.3.0" - -istanbul-lib-instrument@^6.0.0: - version "6.0.3" - resolved "https://registry.yarnpkg.com/istanbul-lib-instrument/-/istanbul-lib-instrument-6.0.3.tgz#fa15401df6c15874bcb2105f773325d78c666765" - integrity sha512-Vtgk7L/R2JHyyGW07spoFlB8/lpjiOLTjMdms6AFMraYt3BaJauod/NGrfnVG/y4Ix1JEuMRPDPEj2ua+zz1/Q== - dependencies: - "@babel/core" "^7.23.9" - "@babel/parser" "^7.23.9" - "@istanbuljs/schema" "^0.1.3" - istanbul-lib-coverage "^3.2.0" - semver "^7.5.4" - -istanbul-lib-report@^3.0.0: - version "3.0.1" - resolved "https://registry.yarnpkg.com/istanbul-lib-report/-/istanbul-lib-report-3.0.1.tgz#908305bac9a5bd175ac6a74489eafd0fc2445a7d" - integrity sha512-GCfE1mtsHGOELCU8e/Z7YWzpmybrx/+dSTfLrvY8qRmaY6zXTKWn6WQIjaAFw069icm6GVMNkgu0NzI4iPZUNw== - dependencies: - istanbul-lib-coverage "^3.0.0" - make-dir "^4.0.0" - supports-color "^7.1.0" - -istanbul-lib-source-maps@^4.0.0: - version "4.0.1" - resolved "https://registry.yarnpkg.com/istanbul-lib-source-maps/-/istanbul-lib-source-maps-4.0.1.tgz#895f3a709fcfba34c6de5a42939022f3e4358551" - integrity sha512-n3s8EwkdFIJCG3BPKBYvskgXGoy88ARzvegkitk60NxRdwltLOTaH7CUiMRXvwYorl0Q712iEjcWB+fK/MrWVw== - dependencies: - debug "^4.1.1" - istanbul-lib-coverage "^3.0.0" - source-map "^0.6.1" - -istanbul-reports@^3.1.3: - version "3.2.0" - resolved "https://registry.yarnpkg.com/istanbul-reports/-/istanbul-reports-3.2.0.tgz#cb4535162b5784aa623cee21a7252cf2c807ac93" - integrity sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA== - dependencies: - html-escaper "^2.0.0" - istanbul-lib-report "^3.0.0" - -jest-changed-files@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-changed-files/-/jest-changed-files-29.7.0.tgz#1c06d07e77c78e1585d020424dedc10d6e17ac3a" - integrity sha512-fEArFiwf1BpQ+4bXSprcDc3/x4HSzL4al2tozwVpDFpsxALjLYdyiIK4e5Vz66GQJIbXJ82+35PtysofptNX2w== - dependencies: - execa "^5.0.0" - jest-util "^29.7.0" - p-limit "^3.1.0" - -jest-circus@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-circus/-/jest-circus-29.7.0.tgz#b6817a45fcc835d8b16d5962d0c026473ee3668a" - integrity sha512-3E1nCMgipcTkCocFwM90XXQab9bS+GMsjdpmPrlelaxwD93Ad8iVEjX/vvHPdLPnFf+L40u+5+iutRdA1N9myw== - dependencies: - "@jest/environment" "^29.7.0" - "@jest/expect" "^29.7.0" - "@jest/test-result" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/node" "*" - chalk "^4.0.0" - co "^4.6.0" - dedent "^1.0.0" - is-generator-fn "^2.0.0" - jest-each "^29.7.0" - jest-matcher-utils "^29.7.0" - jest-message-util "^29.7.0" - jest-runtime "^29.7.0" - jest-snapshot "^29.7.0" - jest-util "^29.7.0" - p-limit "^3.1.0" - pretty-format "^29.7.0" - pure-rand "^6.0.0" - slash "^3.0.0" - stack-utils "^2.0.3" - -jest-cli@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-cli/-/jest-cli-29.7.0.tgz#5592c940798e0cae677eec169264f2d839a37995" - integrity sha512-OVVobw2IubN/GSYsxETi+gOe7Ka59EFMR/twOU3Jb2GnKKeMGJB5SGUUrEz3SFVmJASUdZUzy83sLNNQ2gZslg== - dependencies: - "@jest/core" "^29.7.0" - "@jest/test-result" "^29.7.0" - "@jest/types" "^29.6.3" - chalk "^4.0.0" - create-jest "^29.7.0" - exit "^0.1.2" - import-local "^3.0.2" - jest-config "^29.7.0" - jest-util "^29.7.0" - jest-validate "^29.7.0" - yargs "^17.3.1" - -jest-config@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-config/-/jest-config-29.7.0.tgz#bcbda8806dbcc01b1e316a46bb74085a84b0245f" - integrity sha512-uXbpfeQ7R6TZBqI3/TxCU4q4ttk3u0PJeC+E0zbfSoSjq6bJ7buBPxzQPL0ifrkY4DNu4JUdk0ImlBUYi840eQ== - dependencies: - "@babel/core" "^7.11.6" - "@jest/test-sequencer" "^29.7.0" - "@jest/types" "^29.6.3" - babel-jest "^29.7.0" - chalk "^4.0.0" - ci-info "^3.2.0" - deepmerge "^4.2.2" - glob "^7.1.3" - graceful-fs "^4.2.9" - jest-circus "^29.7.0" - jest-environment-node "^29.7.0" - jest-get-type "^29.6.3" - jest-regex-util "^29.6.3" - jest-resolve "^29.7.0" - jest-runner "^29.7.0" - jest-util "^29.7.0" - jest-validate "^29.7.0" - micromatch "^4.0.4" - parse-json "^5.2.0" - pretty-format "^29.7.0" - slash "^3.0.0" - strip-json-comments "^3.1.1" - -jest-diff@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-diff/-/jest-diff-29.7.0.tgz#017934a66ebb7ecf6f205e84699be10afd70458a" - integrity sha512-LMIgiIrhigmPrs03JHpxUh2yISK3vLFPkAodPeo0+BuF7wA2FoQbkEg1u8gBYBThncu7e1oEDUfIXVuTqLRUjw== - dependencies: - chalk "^4.0.0" - diff-sequences "^29.6.3" - jest-get-type "^29.6.3" - pretty-format "^29.7.0" - -jest-docblock@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-docblock/-/jest-docblock-29.7.0.tgz#8fddb6adc3cdc955c93e2a87f61cfd350d5d119a" - integrity sha512-q617Auw3A612guyaFgsbFeYpNP5t2aoUNLwBUbc/0kD1R4t9ixDbyFTHd1nok4epoVFpr7PmeWHrhvuV3XaJ4g== - dependencies: - detect-newline "^3.0.0" - -jest-each@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-each/-/jest-each-29.7.0.tgz#162a9b3f2328bdd991beaabffbb74745e56577d1" - integrity sha512-gns+Er14+ZrEoC5fhOfYCY1LOHHr0TI+rQUHZS8Ttw2l7gl+80eHc/gFf2Ktkw0+SIACDTeWvpFcv3B04VembQ== - dependencies: - "@jest/types" "^29.6.3" - chalk "^4.0.0" - jest-get-type "^29.6.3" - jest-util "^29.7.0" - pretty-format "^29.7.0" - -jest-environment-node@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-environment-node/-/jest-environment-node-29.7.0.tgz#0b93e111dda8ec120bc8300e6d1fb9576e164376" - integrity sha512-DOSwCRqXirTOyheM+4d5YZOrWcdu0LNZ87ewUoywbcb2XR4wKgqiG8vNeYwhjFMbEkfju7wx2GYH0P2gevGvFw== - dependencies: - "@jest/environment" "^29.7.0" - "@jest/fake-timers" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/node" "*" - jest-mock "^29.7.0" - jest-util "^29.7.0" - -jest-get-type@^29.6.3: - version "29.6.3" - resolved "https://registry.yarnpkg.com/jest-get-type/-/jest-get-type-29.6.3.tgz#36f499fdcea197c1045a127319c0481723908fd1" - integrity sha512-zrteXnqYxfQh7l5FHyL38jL39di8H8rHoecLH3JNxH3BwOrBsNeabdap5e0I23lD4HHI8W5VFBZqG4Eaq5LNcw== - -jest-haste-map@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-haste-map/-/jest-haste-map-29.7.0.tgz#3c2396524482f5a0506376e6c858c3bbcc17b104" - integrity sha512-fP8u2pyfqx0K1rGn1R9pyE0/KTn+G7PxktWidOBTqFPLYX0b9ksaMFkhK5vrS3DVun09pckLdlx90QthlW7AmA== - dependencies: - "@jest/types" "^29.6.3" - "@types/graceful-fs" "^4.1.3" - "@types/node" "*" - anymatch "^3.0.3" - fb-watchman "^2.0.0" - graceful-fs "^4.2.9" - jest-regex-util "^29.6.3" - jest-util "^29.7.0" - jest-worker "^29.7.0" - micromatch "^4.0.4" - walker "^1.0.8" - optionalDependencies: - fsevents "^2.3.2" - -jest-leak-detector@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-leak-detector/-/jest-leak-detector-29.7.0.tgz#5b7ec0dadfdfec0ca383dc9aa016d36b5ea4c728" - integrity sha512-kYA8IJcSYtST2BY9I+SMC32nDpBT3J2NvWJx8+JCuCdl/CR1I4EKUJROiP8XtCcxqgTTBGJNdbB1A8XRKbTetw== - dependencies: - jest-get-type "^29.6.3" - pretty-format "^29.7.0" - -jest-matcher-utils@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-matcher-utils/-/jest-matcher-utils-29.7.0.tgz#ae8fec79ff249fd592ce80e3ee474e83a6c44f12" - integrity sha512-sBkD+Xi9DtcChsI3L3u0+N0opgPYnCRPtGcQYrgXmR+hmt/fYfWAL0xRXYU8eWOdfuLgBe0YCW3AFtnRLagq/g== - dependencies: - chalk "^4.0.0" - jest-diff "^29.7.0" - jest-get-type "^29.6.3" - pretty-format "^29.7.0" - -jest-message-util@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-message-util/-/jest-message-util-29.7.0.tgz#8bc392e204e95dfe7564abbe72a404e28e51f7f3" - integrity sha512-GBEV4GRADeP+qtB2+6u61stea8mGcOT4mCtrYISZwfu9/ISHFJ/5zOMXYbpBE9RsS5+Gb63DW4FgmnKJ79Kf6w== - dependencies: - "@babel/code-frame" "^7.12.13" - "@jest/types" "^29.6.3" - "@types/stack-utils" "^2.0.0" - chalk "^4.0.0" - graceful-fs "^4.2.9" - micromatch "^4.0.4" - pretty-format "^29.7.0" - slash "^3.0.0" - stack-utils "^2.0.3" - -jest-mock@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-mock/-/jest-mock-29.7.0.tgz#4e836cf60e99c6fcfabe9f99d017f3fdd50a6347" - integrity sha512-ITOMZn+UkYS4ZFh83xYAOzWStloNzJFO2s8DWrE4lhtGD+AorgnbkiKERe4wQVBydIGPx059g6riW5Btp6Llnw== - dependencies: - "@jest/types" "^29.6.3" - "@types/node" "*" - jest-util "^29.7.0" - -jest-pnp-resolver@^1.2.2: - version "1.2.3" - resolved "https://registry.yarnpkg.com/jest-pnp-resolver/-/jest-pnp-resolver-1.2.3.tgz#930b1546164d4ad5937d5540e711d4d38d4cad2e" - integrity sha512-+3NpwQEnRoIBtx4fyhblQDPgJI0H1IEIkX7ShLUjPGA7TtUTvI1oiKi3SR4oBR0hQhQR80l4WAe5RrXBwWMA8w== - -jest-regex-util@^29.6.3: - version "29.6.3" - resolved "https://registry.yarnpkg.com/jest-regex-util/-/jest-regex-util-29.6.3.tgz#4a556d9c776af68e1c5f48194f4d0327d24e8a52" - integrity sha512-KJJBsRCyyLNWCNBOvZyRDnAIfUiRJ8v+hOBQYGn8gDyF3UegwiP4gwRR3/SDa42g1YbVycTidUF3rKjyLFDWbg== - -jest-resolve-dependencies@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-resolve-dependencies/-/jest-resolve-dependencies-29.7.0.tgz#1b04f2c095f37fc776ff40803dc92921b1e88428" - integrity sha512-un0zD/6qxJ+S0et7WxeI3H5XSe9lTBBR7bOHCHXkKR6luG5mwDDlIzVQ0V5cZCuoTgEdcdwzTghYkTWfubi+nA== - dependencies: - jest-regex-util "^29.6.3" - jest-snapshot "^29.7.0" - -jest-resolve@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-resolve/-/jest-resolve-29.7.0.tgz#64d6a8992dd26f635ab0c01e5eef4399c6bcbc30" - integrity sha512-IOVhZSrg+UvVAshDSDtHyFCCBUl/Q3AAJv8iZ6ZjnZ74xzvwuzLXid9IIIPgTnY62SJjfuupMKZsZQRsCvxEgA== - dependencies: - chalk "^4.0.0" - graceful-fs "^4.2.9" - jest-haste-map "^29.7.0" - jest-pnp-resolver "^1.2.2" - jest-util "^29.7.0" - jest-validate "^29.7.0" - resolve "^1.20.0" - resolve.exports "^2.0.0" - slash "^3.0.0" - -jest-runner@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-runner/-/jest-runner-29.7.0.tgz#809af072d408a53dcfd2e849a4c976d3132f718e" - integrity sha512-fsc4N6cPCAahybGBfTRcq5wFR6fpLznMg47sY5aDpsoejOcVYFb07AHuSnR0liMcPTgBsA3ZJL6kFOjPdoNipQ== - dependencies: - "@jest/console" "^29.7.0" - "@jest/environment" "^29.7.0" - "@jest/test-result" "^29.7.0" - "@jest/transform" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/node" "*" - chalk "^4.0.0" - emittery "^0.13.1" - graceful-fs "^4.2.9" - jest-docblock "^29.7.0" - jest-environment-node "^29.7.0" - jest-haste-map "^29.7.0" - jest-leak-detector "^29.7.0" - jest-message-util "^29.7.0" - jest-resolve "^29.7.0" - jest-runtime "^29.7.0" - jest-util "^29.7.0" - jest-watcher "^29.7.0" - jest-worker "^29.7.0" - p-limit "^3.1.0" - source-map-support "0.5.13" - -jest-runtime@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-runtime/-/jest-runtime-29.7.0.tgz#efecb3141cf7d3767a3a0cc8f7c9990587d3d817" - integrity sha512-gUnLjgwdGqW7B4LvOIkbKs9WGbn+QLqRQQ9juC6HndeDiezIwhDP+mhMwHWCEcfQ5RUXa6OPnFF8BJh5xegwwQ== - dependencies: - "@jest/environment" "^29.7.0" - "@jest/fake-timers" "^29.7.0" - "@jest/globals" "^29.7.0" - "@jest/source-map" "^29.6.3" - "@jest/test-result" "^29.7.0" - "@jest/transform" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/node" "*" - chalk "^4.0.0" - cjs-module-lexer "^1.0.0" - collect-v8-coverage "^1.0.0" - glob "^7.1.3" - graceful-fs "^4.2.9" - jest-haste-map "^29.7.0" - jest-message-util "^29.7.0" - jest-mock "^29.7.0" - jest-regex-util "^29.6.3" - jest-resolve "^29.7.0" - jest-snapshot "^29.7.0" - jest-util "^29.7.0" - slash "^3.0.0" - strip-bom "^4.0.0" - -jest-snapshot@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-snapshot/-/jest-snapshot-29.7.0.tgz#c2c574c3f51865da1bb329036778a69bf88a6be5" - integrity sha512-Rm0BMWtxBcioHr1/OX5YCP8Uov4riHvKPknOGs804Zg9JGZgmIBkbtlxJC/7Z4msKYVbIJtfU+tKb8xlYNfdkw== - dependencies: - "@babel/core" "^7.11.6" - "@babel/generator" "^7.7.2" - "@babel/plugin-syntax-jsx" "^7.7.2" - "@babel/plugin-syntax-typescript" "^7.7.2" - "@babel/types" "^7.3.3" - "@jest/expect-utils" "^29.7.0" - "@jest/transform" "^29.7.0" - "@jest/types" "^29.6.3" - babel-preset-current-node-syntax "^1.0.0" - chalk "^4.0.0" - expect "^29.7.0" - graceful-fs "^4.2.9" - jest-diff "^29.7.0" - jest-get-type "^29.6.3" - jest-matcher-utils "^29.7.0" - jest-message-util "^29.7.0" - jest-util "^29.7.0" - natural-compare "^1.4.0" - pretty-format "^29.7.0" - semver "^7.5.3" - -jest-util@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-util/-/jest-util-29.7.0.tgz#23c2b62bfb22be82b44de98055802ff3710fc0bc" - integrity sha512-z6EbKajIpqGKU56y5KBUgy1dt1ihhQJgWzUlZHArA/+X2ad7Cb5iF+AK1EWVL/Bo7Rz9uurpqw6SiBCefUbCGA== - dependencies: - "@jest/types" "^29.6.3" - "@types/node" "*" - chalk "^4.0.0" - ci-info "^3.2.0" - graceful-fs "^4.2.9" - picomatch "^2.2.3" - -jest-validate@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-validate/-/jest-validate-29.7.0.tgz#7bf705511c64da591d46b15fce41400d52147d9c" - integrity sha512-ZB7wHqaRGVw/9hST/OuFUReG7M8vKeq0/J2egIGLdvjHCmYqGARhzXmtgi+gVeZ5uXFF219aOc3Ls2yLg27tkw== - dependencies: - "@jest/types" "^29.6.3" - camelcase "^6.2.0" - chalk "^4.0.0" - jest-get-type "^29.6.3" - leven "^3.1.0" - pretty-format "^29.7.0" - -jest-watcher@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-watcher/-/jest-watcher-29.7.0.tgz#7810d30d619c3a62093223ce6bb359ca1b28a2f2" - integrity sha512-49Fg7WXkU3Vl2h6LbLtMQ/HyB6rXSIX7SqvBLQmssRBGN9I0PNvPmAmCWSOY6SOvrjhI/F7/bGAv9RtnsPA03g== - dependencies: - "@jest/test-result" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/node" "*" - ansi-escapes "^4.2.1" - chalk "^4.0.0" - emittery "^0.13.1" - jest-util "^29.7.0" - string-length "^4.0.1" - -jest-worker@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-worker/-/jest-worker-29.7.0.tgz#acad073acbbaeb7262bd5389e1bcf43e10058d4a" - integrity sha512-eIz2msL/EzL9UFTFFx7jBTkeZfku0yUAyZZZmJ93H2TYEiroIx2PQjEXcwYtYl8zXCxb+PAmA2hLIt/6ZEkPHw== - dependencies: - "@types/node" "*" - jest-util "^29.7.0" - merge-stream "^2.0.0" - supports-color "^8.0.0" - -jest@^29.4.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest/-/jest-29.7.0.tgz#994676fc24177f088f1c5e3737f5697204ff2613" - integrity sha512-NIy3oAFp9shda19hy4HK0HRTWKtPJmGdnvywu01nOqNC2vZg+Z+fvJDxpMQA88eb2I9EcafcdjYgsDthnYTvGw== - dependencies: - "@jest/core" "^29.7.0" - "@jest/types" "^29.6.3" - import-local "^3.0.2" - jest-cli "^29.7.0" - -jose@^6.1.3: - version "6.2.1" - resolved "https://registry.yarnpkg.com/jose/-/jose-6.2.1.tgz#7a6b1de83816deaee9055a558e1278a7b2b9ea1b" - integrity sha512-jUaKr1yrbfaImV7R2TN/b3IcZzsw38/chqMpo2XJ7i2F8AfM/lA4G1goC3JVEwg0H7UldTmSt3P68nt31W7/mw== - -joycon@^3.1.1: - version "3.1.1" - resolved "https://registry.yarnpkg.com/joycon/-/joycon-3.1.1.tgz#bce8596d6ae808f8b68168f5fc69280996894f03" - integrity sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw== - -"jq-web@https://github.com/stainless-api/jq-web/releases/download/v0.8.8/jq-web.tar.gz": - version "0.8.8" - resolved "https://github.com/stainless-api/jq-web/releases/download/v0.8.8/jq-web.tar.gz#7849ef64bdfc28f70cbfc9888f886860e96da10d" - -js-tokens@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/js-tokens/-/js-tokens-4.0.0.tgz#19203fb59991df98e3a287050d4647cdeaf32499" - integrity sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ== - -js-yaml@^3.13.1: - version "3.14.2" - resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-3.14.2.tgz#77485ce1dd7f33c061fd1b16ecea23b55fcb04b0" - integrity sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg== - dependencies: - argparse "^1.0.7" - esprima "^4.0.0" - -js-yaml@^4.1.1: - version "4.1.1" - resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-4.1.1.tgz#854c292467705b699476e1a2decc0c8a3458806b" - integrity sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA== - dependencies: - argparse "^2.0.1" - -jsesc@^3.0.2: - version "3.1.0" - resolved "https://registry.yarnpkg.com/jsesc/-/jsesc-3.1.0.tgz#74d335a234f67ed19907fdadfac7ccf9d409825d" - integrity sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA== - -json-buffer@3.0.1: - version "3.0.1" - resolved "https://registry.yarnpkg.com/json-buffer/-/json-buffer-3.0.1.tgz#9338802a30d3b6605fbe0613e094008ca8c05a13" - integrity sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ== - -json-parse-even-better-errors@^2.3.0: - version "2.3.1" - resolved "https://registry.yarnpkg.com/json-parse-even-better-errors/-/json-parse-even-better-errors-2.3.1.tgz#7c47805a94319928e05777405dc12e1f7a4ee02d" - integrity sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w== - -json-schema-traverse@^0.4.1: - version "0.4.1" - resolved "https://registry.yarnpkg.com/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz#69f6a87d9513ab8bb8fe63bdb0979c448e684660" - integrity sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg== - -json-schema-traverse@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz#ae7bcb3656ab77a73ba5c49bf654f38e6b6860e2" - integrity sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug== - -json-schema-typed@^8.0.2: - version "8.0.2" - resolved "https://registry.yarnpkg.com/json-schema-typed/-/json-schema-typed-8.0.2.tgz#e98ee7b1899ff4a184534d1f167c288c66bbeff4" - integrity sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA== - -json-stable-stringify-without-jsonify@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/json-stable-stringify-without-jsonify/-/json-stable-stringify-without-jsonify-1.0.1.tgz#9db7b59496ad3f3cfef30a75142d2d930ad72651" - integrity sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw== - -json5@^2.2.2, json5@^2.2.3: - version "2.2.3" - resolved "https://registry.yarnpkg.com/json5/-/json5-2.2.3.tgz#78cd6f1a19bdc12b73db5ad0c61efd66c1e29283" - integrity sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg== - -jsonfile@^6.0.1: - version "6.2.0" - resolved "https://registry.yarnpkg.com/jsonfile/-/jsonfile-6.2.0.tgz#7c265bd1b65de6977478300087c99f1c84383f62" - integrity sha512-FGuPw30AdOIUTRMC2OMRtQV+jkVj2cfPqSeWXv1NEAJ1qZ5zb1X6z1mFhbfOB/iy3ssJCD+3KuZ8r8C3uVFlAg== - dependencies: - universalify "^2.0.0" - optionalDependencies: - graceful-fs "^4.1.6" - -keyv@^4.5.4: - version "4.5.4" - resolved "https://registry.yarnpkg.com/keyv/-/keyv-4.5.4.tgz#a879a99e29452f942439f2a405e3af8b31d4de93" - integrity sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw== - dependencies: - json-buffer "3.0.1" - -kleur@^3.0.3: - version "3.0.3" - resolved "https://registry.yarnpkg.com/kleur/-/kleur-3.0.3.tgz#a79c9ecc86ee1ce3fa6206d1216c501f147fc07e" - integrity sha512-eTIzlVOSUR+JxdDFepEYcBMtZ9Qqdef+rnzWdRZuMbOywu5tO2w2N7rqjoANZ5k9vywhL6Br1VRjUIgTQx4E8w== - -leven@^3.1.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/leven/-/leven-3.1.0.tgz#77891de834064cccba82ae7842bb6b14a13ed7f2" - integrity sha512-qsda+H8jTaUaN/x5vzW2rzc+8Rw4TAQ/4KjB46IwK5VH+IlVeeeje/EoZRpiXvIqjFgK84QffqPztGI3VBLG1A== - -levn@^0.4.1: - version "0.4.1" - resolved "https://registry.yarnpkg.com/levn/-/levn-0.4.1.tgz#ae4562c007473b932a6200d403268dd2fffc6ade" - integrity sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ== - dependencies: - prelude-ls "^1.2.1" - type-check "~0.4.0" - -lines-and-columns@^1.1.6: - version "1.2.4" - resolved "https://registry.yarnpkg.com/lines-and-columns/-/lines-and-columns-1.2.4.tgz#eca284f75d2965079309dc0ad9255abb2ebc1632" - integrity sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg== - -locate-path@^5.0.0: - version "5.0.0" - resolved "https://registry.yarnpkg.com/locate-path/-/locate-path-5.0.0.tgz#1afba396afd676a6d42504d0a67a3a7eb9f62aa0" - integrity sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g== - dependencies: - p-locate "^4.1.0" - -locate-path@^6.0.0: - version "6.0.0" - resolved "https://registry.yarnpkg.com/locate-path/-/locate-path-6.0.0.tgz#55321eb309febbc59c4801d931a72452a681d286" - integrity sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw== - dependencies: - p-locate "^5.0.0" - -lodash.memoize@^4.1.2: - version "4.1.2" - resolved "https://registry.yarnpkg.com/lodash.memoize/-/lodash.memoize-4.1.2.tgz#bcc6c49a42a2840ed997f323eada5ecd182e0bfe" - integrity sha512-t7j+NzmgnQzTAYXcsHYLgimltOV1MXHtlOWf6GjL9Kj8GK5FInw5JotxvbOs+IvV1/Dzo04/fCGfLVs7aXb4Ag== - -lodash.merge@^4.6.2: - version "4.6.2" - resolved "https://registry.yarnpkg.com/lodash.merge/-/lodash.merge-4.6.2.tgz#558aa53b43b661e1925a0afdfa36a9a1085fe57a" - integrity sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ== - -lru-cache@^5.1.1: - version "5.1.1" - resolved "https://registry.yarnpkg.com/lru-cache/-/lru-cache-5.1.1.tgz#1da27e6710271947695daf6848e847f01d84b920" - integrity sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w== - dependencies: - yallist "^3.0.2" - -make-dir@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/make-dir/-/make-dir-4.0.0.tgz#c3c2307a771277cd9638305f915c29ae741b614e" - integrity sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw== - dependencies: - semver "^7.5.3" - -make-error@^1.1.1, make-error@^1.3.6: - version "1.3.6" - resolved "https://registry.yarnpkg.com/make-error/-/make-error-1.3.6.tgz#2eb2e37ea9b67c4891f684a1394799af484cf7a2" - integrity sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw== - -makeerror@1.0.12: - version "1.0.12" - resolved "https://registry.yarnpkg.com/makeerror/-/makeerror-1.0.12.tgz#3e5dd2079a82e812e983cc6610c4a2cb0eaa801a" - integrity sha512-JmqCvUhmt43madlpFzG4BQzG2Z3m6tvQDNKdClZnO3VbIudJYmxsT0FNJMeiB2+JTSlTQTSbU8QdesVmwJcmLg== - dependencies: - tmpl "1.0.5" - -math-intrinsics@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/math-intrinsics/-/math-intrinsics-1.1.0.tgz#a0dd74be81e2aa5c2f27e65ce283605ee4e2b7f9" - integrity sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g== - -media-typer@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/media-typer/-/media-typer-1.1.0.tgz#6ab74b8f2d3320f2064b2a87a38e7931ff3a5561" - integrity sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw== - -merge-descriptors@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/merge-descriptors/-/merge-descriptors-2.0.0.tgz#ea922f660635a2249ee565e0449f951e6b603808" - integrity sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g== - -merge-stream@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/merge-stream/-/merge-stream-2.0.0.tgz#52823629a14dd00c9770fb6ad47dc6310f2c1f60" - integrity sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w== - -merge2@^1.3.0: - version "1.4.1" - resolved "https://registry.yarnpkg.com/merge2/-/merge2-1.4.1.tgz#4368892f885e907455a6fd7dc55c0c9d404990ae" - integrity sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg== - -micromatch@^4.0.4, micromatch@^4.0.8: - version "4.0.8" - resolved "https://registry.yarnpkg.com/micromatch/-/micromatch-4.0.8.tgz#d66fa18f3a47076789320b9b1af32bd86d9fa202" - integrity sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA== - dependencies: - braces "^3.0.3" - picomatch "^2.3.1" - -mime-db@^1.54.0: - version "1.54.0" - resolved "https://registry.yarnpkg.com/mime-db/-/mime-db-1.54.0.tgz#cddb3ee4f9c64530dff640236661d42cb6a314f5" - integrity sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ== - -mime-types@^3.0.0, mime-types@^3.0.2: - version "3.0.2" - resolved "https://registry.yarnpkg.com/mime-types/-/mime-types-3.0.2.tgz#39002d4182575d5af036ffa118100f2524b2e2ab" - integrity sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A== - dependencies: - mime-db "^1.54.0" - -mimic-fn@^2.1.0: - version "2.1.0" - resolved "https://registry.yarnpkg.com/mimic-fn/-/mimic-fn-2.1.0.tgz#7ed2c2ccccaf84d3ffcb7a69b57711fc2083401b" - integrity sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg== - -minimatch@^3.0.4, minimatch@^3.1.1, minimatch@^3.1.5: - version "3.1.5" - resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-3.1.5.tgz#580c88f8d5445f2bd6aa8f3cadefa0de79fbd69e" - integrity sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w== - dependencies: - brace-expansion "^1.1.7" - -minimatch@^7.4.3: - version "7.4.6" - resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-7.4.6.tgz#845d6f254d8f4a5e4fd6baf44d5f10c8448365fb" - integrity sha512-sBz8G/YjVniEz6lKPNpKxXwazJe4c19fEfV2GDMX6AjFz+MX9uDWIZW8XreVhkFW3fkIdTv/gxWr/Kks5FFAVw== - dependencies: - brace-expansion "^2.0.1" - -minimatch@^9.0.4: - version "9.0.5" - resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-9.0.5.tgz#d74f9dd6b57d83d8e98cfb82133b03978bc929e5" - integrity sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow== - dependencies: - brace-expansion "^2.0.1" - -minimist@^1.2.5, minimist@^1.2.6: - version "1.2.8" - resolved "https://registry.yarnpkg.com/minimist/-/minimist-1.2.8.tgz#c1a464e7693302e082a075cee0c057741ac4772c" - integrity sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA== - -mkdirp@^2.1.6: - version "2.1.6" - resolved "https://registry.yarnpkg.com/mkdirp/-/mkdirp-2.1.6.tgz#964fbcb12b2d8c5d6fbc62a963ac95a273e2cc19" - integrity sha512-+hEnITedc8LAtIP9u3HJDFIdcLV2vXP33sqLLIzkv1Db1zO/1OxbvYf0Y1OC/S/Qo5dxHXepofhmxL02PsKe+A== - -ms@^2.1.3: - version "2.1.3" - resolved "https://registry.yarnpkg.com/ms/-/ms-2.1.3.tgz#574c8138ce1d2b5861f0b44579dbadd60c6615b2" - integrity sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA== - -mute-stream@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/mute-stream/-/mute-stream-1.0.0.tgz#e31bd9fe62f0aed23520aa4324ea6671531e013e" - integrity sha512-avsJQhyd+680gKXyG/sQc0nXaC6rBkPOfyHYcFb9+hdkqQkR9bdnkJ0AMZhke0oesPqIO+mFFJ+IdBc7mst4IA== - -natural-compare@^1.4.0: - version "1.4.0" - resolved "https://registry.yarnpkg.com/natural-compare/-/natural-compare-1.4.0.tgz#4abebfeed7541f2c27acfb29bdbbd15c8d5ba4f7" - integrity sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw== - -negotiator@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/negotiator/-/negotiator-1.0.0.tgz#b6c91bb47172d69f93cfd7c357bbb529019b5f6a" - integrity sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg== - -neo-async@^2.6.2: - version "2.6.2" - resolved "https://registry.yarnpkg.com/neo-async/-/neo-async-2.6.2.tgz#b4aafb93e3aeb2d8174ca53cf163ab7d7308305f" - integrity sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw== - -node-forge@^1.3.2: - version "1.3.3" - resolved "https://registry.yarnpkg.com/node-forge/-/node-forge-1.3.3.tgz#0ad80f6333b3a0045e827ac20b7f735f93716751" - integrity sha512-rLvcdSyRCyouf6jcOIPe/BgwG/d7hKjzMKOas33/pHEr6gbq18IK9zV7DiPvzsz0oBJPme6qr6H6kGZuI9/DZg== - -node-int64@^0.4.0: - version "0.4.0" - resolved "https://registry.yarnpkg.com/node-int64/-/node-int64-0.4.0.tgz#87a9065cdb355d3182d8f94ce11188b825c68a3b" - integrity sha512-O5lz91xSOeoXP6DulyHfllpq+Eg00MWitZIbtPfoSEvqIHdl5gfcY6hYzDWnj0qD5tz52PI08u9qUvSVeUBeHw== - -node-releases@^2.0.27: - version "2.0.27" - resolved "https://registry.yarnpkg.com/node-releases/-/node-releases-2.0.27.tgz#eedca519205cf20f650f61d56b070db111231e4e" - integrity sha512-nmh3lCkYZ3grZvqcCH+fjmQ7X+H0OeZgP40OierEaAptX4XofMh5kwNbWh7lBduUzCcV/8kZ+NDLCwm2iorIlA== - -normalize-path@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/normalize-path/-/normalize-path-3.0.0.tgz#0dcd69ff23a1c9b11fd0978316644a0388216a65" - integrity sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA== - -npm-run-path@^4.0.1: - version "4.0.1" - resolved "https://registry.yarnpkg.com/npm-run-path/-/npm-run-path-4.0.1.tgz#b7ecd1e5ed53da8e37a55e1c2269e0b97ed748ea" - integrity sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw== - dependencies: - path-key "^3.0.0" - -object-assign@^4: - version "4.1.1" - resolved "https://registry.yarnpkg.com/object-assign/-/object-assign-4.1.1.tgz#2109adc7965887cfc05cbbd442cac8bfbb360863" - integrity sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg== - -object-inspect@^1.13.3: - version "1.13.4" - resolved "https://registry.yarnpkg.com/object-inspect/-/object-inspect-1.13.4.tgz#8375265e21bc20d0fa582c22e1b13485d6e00213" - integrity sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew== - -on-exit-leak-free@^2.1.0: - version "2.1.2" - resolved "https://registry.yarnpkg.com/on-exit-leak-free/-/on-exit-leak-free-2.1.2.tgz#fed195c9ebddb7d9e4c3842f93f281ac8dadd3b8" - integrity sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA== - -on-finished@^2.4.1: - version "2.4.1" - resolved "https://registry.yarnpkg.com/on-finished/-/on-finished-2.4.1.tgz#58c8c44116e54845ad57f14ab10b03533184ac3f" - integrity sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg== - dependencies: - ee-first "1.1.1" - -once@^1.3.0, once@^1.3.1, once@^1.4.0: - version "1.4.0" - resolved "https://registry.yarnpkg.com/once/-/once-1.4.0.tgz#583b1aa775961d4b113ac17d9c50baef9dd76bd1" - integrity sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w== - dependencies: - wrappy "1" - -onetime@^5.1.2: - version "5.1.2" - resolved "https://registry.yarnpkg.com/onetime/-/onetime-5.1.2.tgz#d0e96ebb56b07476df1dd9c4806e5237985ca45e" - integrity sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg== - dependencies: - mimic-fn "^2.1.0" - -optionator@^0.9.3: - version "0.9.4" - resolved "https://registry.yarnpkg.com/optionator/-/optionator-0.9.4.tgz#7ea1c1a5d91d764fb282139c88fe11e182a3a734" - integrity sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g== - dependencies: - deep-is "^0.1.3" - fast-levenshtein "^2.0.6" - levn "^0.4.1" - prelude-ls "^1.2.1" - type-check "^0.4.0" - word-wrap "^1.2.5" - -os-tmpdir@~1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/os-tmpdir/-/os-tmpdir-1.0.2.tgz#bbe67406c79aa85c5cfec766fe5734555dfa1274" - integrity sha512-D2FR03Vir7FIu45XBY20mTb+/ZSWB00sjU9jdQXt83gDrI4Ztz5Fs7/yy74g2N5SVQY4xY1qDr4rNddwYRVX0g== - -p-all@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/p-all/-/p-all-3.0.0.tgz#077c023c37e75e760193badab2bad3ccd5782bfb" - integrity sha512-qUZbvbBFVXm6uJ7U/WDiO0fv6waBMbjlCm4E66oZdRR+egswICarIdHyVSZZHudH8T5SF8x/JG0q0duFzPnlBw== - dependencies: - p-map "^4.0.0" - -p-limit@^2.2.0: - version "2.3.0" - resolved "https://registry.yarnpkg.com/p-limit/-/p-limit-2.3.0.tgz#3dd33c647a214fdfffd835933eb086da0dc21db1" - integrity sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w== - dependencies: - p-try "^2.0.0" - -p-limit@^3.0.2, p-limit@^3.1.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/p-limit/-/p-limit-3.1.0.tgz#e1daccbe78d0d1388ca18c64fea38e3e57e3706b" - integrity sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ== - dependencies: - yocto-queue "^0.1.0" - -p-locate@^4.1.0: - version "4.1.0" - resolved "https://registry.yarnpkg.com/p-locate/-/p-locate-4.1.0.tgz#a3428bb7088b3a60292f66919278b7c297ad4f07" - integrity sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A== - dependencies: - p-limit "^2.2.0" - -p-locate@^5.0.0: - version "5.0.0" - resolved "https://registry.yarnpkg.com/p-locate/-/p-locate-5.0.0.tgz#83c8315c6785005e3bd021839411c9e110e6d834" - integrity sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw== - dependencies: - p-limit "^3.0.2" - -p-map@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/p-map/-/p-map-4.0.0.tgz#bb2f95a5eda2ec168ec9274e06a747c3e2904d2b" - integrity sha512-/bjOqmgETBYB5BoEeGVea8dmvHb2m9GLy1E9W43yeyfP6QQCZGFNa+XRceJEuDB6zqr+gKpIAmlLebMpykw/MQ== - dependencies: - aggregate-error "^3.0.0" - -p-try@^2.0.0: - version "2.2.0" - resolved "https://registry.yarnpkg.com/p-try/-/p-try-2.2.0.tgz#cb2868540e313d61de58fafbe35ce9004d5540e6" - integrity sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ== - -parent-module@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/parent-module/-/parent-module-1.0.1.tgz#691d2709e78c79fae3a156622452d00762caaaa2" - integrity sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g== - dependencies: - callsites "^3.0.0" - -parse-json@^5.2.0: - version "5.2.0" - resolved "https://registry.yarnpkg.com/parse-json/-/parse-json-5.2.0.tgz#c76fc66dee54231c962b22bcc8a72cf2f99753cd" - integrity sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg== - dependencies: - "@babel/code-frame" "^7.0.0" - error-ex "^1.3.1" - json-parse-even-better-errors "^2.3.0" - lines-and-columns "^1.1.6" - -parseurl@^1.3.3: - version "1.3.3" - resolved "https://registry.yarnpkg.com/parseurl/-/parseurl-1.3.3.tgz#9da19e7bee8d12dff0513ed5b76957793bc2e8d4" - integrity sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ== - -path-browserify@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/path-browserify/-/path-browserify-1.0.1.tgz#d98454a9c3753d5790860f16f68867b9e46be1fd" - integrity sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g== - -path-exists@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/path-exists/-/path-exists-4.0.0.tgz#513bdbe2d3b95d7762e8c1137efa195c6c61b5b3" - integrity sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w== - -path-is-absolute@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/path-is-absolute/-/path-is-absolute-1.0.1.tgz#174b9268735534ffbc7ace6bf53a5a9e1b5c5f5f" - integrity sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg== - -path-key@^3.0.0, path-key@^3.1.0: - version "3.1.1" - resolved "https://registry.yarnpkg.com/path-key/-/path-key-3.1.1.tgz#581f6ade658cbba65a0d3380de7753295054f375" - integrity sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q== - -path-parse@^1.0.7: - version "1.0.7" - resolved "https://registry.yarnpkg.com/path-parse/-/path-parse-1.0.7.tgz#fbc114b60ca42b30d9daf5858e4bd68bbedb6735" - integrity sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw== - -path-to-regexp@^8.0.0: - version "8.3.0" - resolved "https://registry.yarnpkg.com/path-to-regexp/-/path-to-regexp-8.3.0.tgz#aa818a6981f99321003a08987d3cec9c3474cd1f" - integrity sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA== - -picocolors@^1.1.1: - version "1.1.1" - resolved "https://registry.yarnpkg.com/picocolors/-/picocolors-1.1.1.tgz#3d321af3eab939b083c8f929a1d12cda81c26b6b" - integrity sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA== - -picomatch@^2.0.4, picomatch@^2.2.3, picomatch@^2.3.1: - version "2.3.1" - resolved "https://registry.yarnpkg.com/picomatch/-/picomatch-2.3.1.tgz#3ba3833733646d9d3e4995946c1365a67fb07a42" - integrity sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA== - -pino-abstract-transport@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/pino-abstract-transport/-/pino-abstract-transport-3.0.0.tgz#b21e5f33a297e8c4c915c62b3ce5dd4a87a52c23" - integrity sha512-wlfUczU+n7Hy/Ha5j9a/gZNy7We5+cXp8YL+X+PG8S0KXxw7n/JXA3c46Y0zQznIJ83URJiwy7Lh56WLokNuxg== - dependencies: - split2 "^4.0.0" - -pino-http@^11.0.0: - version "11.0.0" - resolved "https://registry.yarnpkg.com/pino-http/-/pino-http-11.0.0.tgz#ebadef4694fc59aadab9be7e5939aea625b4615f" - integrity sha512-wqg5XIAGRRIWtTk8qPGxkbrfiwEWz1lgedVLvhLALudKXvg1/L2lTFgTGPJ4Z2e3qcRmxoFxDuSdMdMGNM6I1g== - dependencies: - get-caller-file "^2.0.5" - pino "^10.0.0" - pino-std-serializers "^7.0.0" - process-warning "^5.0.0" - -pino-pretty@^13.1.3: - version "13.1.3" - resolved "https://registry.yarnpkg.com/pino-pretty/-/pino-pretty-13.1.3.tgz#2274cccda925dd355c104079a5029f6598d0381b" - integrity sha512-ttXRkkOz6WWC95KeY9+xxWL6AtImwbyMHrL1mSwqwW9u+vLp/WIElvHvCSDg0xO/Dzrggz1zv3rN5ovTRVowKg== - dependencies: - colorette "^2.0.7" - dateformat "^4.6.3" - fast-copy "^4.0.0" - fast-safe-stringify "^2.1.1" - help-me "^5.0.0" - joycon "^3.1.1" - minimist "^1.2.6" - on-exit-leak-free "^2.1.0" - pino-abstract-transport "^3.0.0" - pump "^3.0.0" - secure-json-parse "^4.0.0" - sonic-boom "^4.0.1" - strip-json-comments "^5.0.2" - -pino-std-serializers@^7.0.0: - version "7.1.0" - resolved "https://registry.yarnpkg.com/pino-std-serializers/-/pino-std-serializers-7.1.0.tgz#a7b0cd65225f29e92540e7853bd73b07479893fc" - integrity sha512-BndPH67/JxGExRgiX1dX0w1FvZck5Wa4aal9198SrRhZjH3GxKQUKIBnYJTdj2HDN3UQAS06HlfcSbQj2OHmaw== - -pino@^10.0.0, pino@^10.3.1: - version "10.3.1" - resolved "https://registry.yarnpkg.com/pino/-/pino-10.3.1.tgz#6552c8f8d8481844c9e452e7bf0be90bff1939ce" - integrity sha512-r34yH/GlQpKZbU1BvFFqOjhISRo1MNx1tWYsYvmj6KIRHSPMT2+yHOEb1SG6NMvRoHRF0a07kCOox/9yakl1vg== - dependencies: - "@pinojs/redact" "^0.4.0" - atomic-sleep "^1.0.0" - on-exit-leak-free "^2.1.0" - pino-abstract-transport "^3.0.0" - pino-std-serializers "^7.0.0" - process-warning "^5.0.0" - quick-format-unescaped "^4.0.3" - real-require "^0.2.0" - safe-stable-stringify "^2.3.1" - sonic-boom "^4.0.1" - thread-stream "^4.0.0" - -pirates@^4.0.4: - version "4.0.7" - resolved "https://registry.yarnpkg.com/pirates/-/pirates-4.0.7.tgz#643b4a18c4257c8a65104b73f3049ce9a0a15e22" - integrity sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA== - -pkce-challenge@^5.0.0: - version "5.0.1" - resolved "https://registry.yarnpkg.com/pkce-challenge/-/pkce-challenge-5.0.1.tgz#3b4446865b17b1745e9ace2016a31f48ddf6230d" - integrity sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ== - -pkg-dir@^4.2.0: - version "4.2.0" - resolved "https://registry.yarnpkg.com/pkg-dir/-/pkg-dir-4.2.0.tgz#f099133df7ede422e81d1d8448270eeb3e4261f3" - integrity sha512-HRDzbaKjC+AOWVXxAU/x54COGeIv9eb+6CkDSQoNTt4XyWoIJvuPsXizxu/Fr23EiekbtZwmh1IcIG/l/a10GQ== - dependencies: - find-up "^4.0.0" - -prelude-ls@^1.2.1: - version "1.2.1" - resolved "https://registry.yarnpkg.com/prelude-ls/-/prelude-ls-1.2.1.tgz#debc6489d7a6e6b0e7611888cec880337d316396" - integrity sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g== - -prettier-linter-helpers@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/prettier-linter-helpers/-/prettier-linter-helpers-1.0.1.tgz#6a31f88a4bad6c7adda253de12ba4edaea80ebcd" - integrity sha512-SxToR7P8Y2lWmv/kTzVLC1t/GDI2WGjMwNhLLE9qtH8Q13C+aEmuRlzDst4Up4s0Wc8sF2M+J57iB3cMLqftfg== - dependencies: - fast-diff "^1.1.2" - -prettier@^3.0.0: - version "3.7.4" - resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.7.4.tgz#d2f8335d4b1cec47e1c8098645411b0c9dff9c0f" - integrity sha512-v6UNi1+3hSlVvv8fSaoUbggEM5VErKmmpGA7Pl3HF8V6uKY7rvClBOJlH6yNwQtfTueNkGVpOv/mtWL9L4bgRA== - -pretty-bytes@^5.6.0: - version "5.6.0" - resolved "https://registry.yarnpkg.com/pretty-bytes/-/pretty-bytes-5.6.0.tgz#356256f643804773c82f64723fe78c92c62beaeb" - integrity sha512-FFw039TmrBqFK8ma/7OL3sDz/VytdtJr044/QUJtH0wK9lb9jLq9tJyIxUwtQJHwar2BqtiA4iCWSwo9JLkzFg== - -pretty-format@^29.0.0, pretty-format@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/pretty-format/-/pretty-format-29.7.0.tgz#ca42c758310f365bfa71a0bda0a807160b776812" - integrity sha512-Pdlw/oPxN+aXdmM9R00JVC9WVFoCLTKJvDVLgmJ+qAffBMxsV85l/Lu7sNx4zSzPyoL2euImuEwHhOXdEgNFZQ== - dependencies: - "@jest/schemas" "^29.6.3" - ansi-styles "^5.0.0" - react-is "^18.0.0" - -process-warning@^5.0.0: - version "5.0.0" - resolved "https://registry.yarnpkg.com/process-warning/-/process-warning-5.0.0.tgz#566e0bf79d1dff30a72d8bbbe9e8ecefe8d378d7" - integrity sha512-a39t9ApHNx2L4+HBnQKqxxHNs1r7KF+Intd8Q/g1bUh6q0WIp9voPXJ/x0j+ZL45KF1pJd9+q2jLIRMfvEshkA== - -prompts@^2.0.1: - version "2.4.2" - resolved "https://registry.yarnpkg.com/prompts/-/prompts-2.4.2.tgz#7b57e73b3a48029ad10ebd44f74b01722a4cb069" - integrity sha512-NxNv/kLguCA7p3jE8oL2aEBsrJWgAakBpgmgK6lpPWV+WuOmY6r2/zbAVnP+T8bQlA0nzHXSJSJW0Hq7ylaD2Q== - dependencies: - kleur "^3.0.3" - sisteransi "^1.0.5" - -proxy-addr@^2.0.7: - version "2.0.7" - resolved "https://registry.yarnpkg.com/proxy-addr/-/proxy-addr-2.0.7.tgz#f19fe69ceab311eeb94b42e70e8c2070f9ba1025" - integrity sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg== - dependencies: - forwarded "0.2.0" - ipaddr.js "1.9.1" - -pump@^3.0.0: - version "3.0.4" - resolved "https://registry.yarnpkg.com/pump/-/pump-3.0.4.tgz#1f313430527fa8b905622ebd22fe1444e757ab3c" - integrity sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA== - dependencies: - end-of-stream "^1.1.0" - once "^1.3.1" - -punycode@^2.1.0: - version "2.3.1" - resolved "https://registry.yarnpkg.com/punycode/-/punycode-2.3.1.tgz#027422e2faec0b25e1549c3e1bd8309b9133b6e5" - integrity sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg== - -pure-rand@^6.0.0: - version "6.1.0" - resolved "https://registry.yarnpkg.com/pure-rand/-/pure-rand-6.1.0.tgz#d173cf23258231976ccbdb05247c9787957604f2" - integrity sha512-bVWawvoZoBYpp6yIoQtQXHZjmz35RSVHnUOTefl8Vcjr8snTPY1wnpSPMWekcFwbxI6gtmT7rSYPFvz71ldiOA== - -qs@^6.14.0, qs@^6.14.1: - version "6.14.1" - resolved "https://registry.yarnpkg.com/qs/-/qs-6.14.1.tgz#a41d85b9d3902f31d27861790506294881871159" - integrity sha512-4EK3+xJl8Ts67nLYNwqw/dsFVnCf+qR7RgXSK9jEEm9unao3njwMDdmsdvoKBKHzxd7tCYz5e5M+SnMjdtXGQQ== - dependencies: - side-channel "^1.1.0" - -queue-microtask@^1.2.2: - version "1.2.3" - resolved "https://registry.yarnpkg.com/queue-microtask/-/queue-microtask-1.2.3.tgz#4929228bbc724dfac43e0efb058caf7b6cfb6243" - integrity sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A== - -quick-format-unescaped@^4.0.3: - version "4.0.4" - resolved "https://registry.yarnpkg.com/quick-format-unescaped/-/quick-format-unescaped-4.0.4.tgz#93ef6dd8d3453cbc7970dd614fad4c5954d6b5a7" - integrity sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg== - -range-parser@^1.2.1: - version "1.2.1" - resolved "https://registry.yarnpkg.com/range-parser/-/range-parser-1.2.1.tgz#3cf37023d199e1c24d1a55b84800c2f3e6468031" - integrity sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg== - -raw-body@^3.0.0, raw-body@^3.0.1: - version "3.0.2" - resolved "https://registry.yarnpkg.com/raw-body/-/raw-body-3.0.2.tgz#3e3ada5ae5568f9095d84376fd3a49b8fb000a51" - integrity sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA== - dependencies: - bytes "~3.1.2" - http-errors "~2.0.1" - iconv-lite "~0.7.0" - unpipe "~1.0.0" - -react-is@^18.0.0: - version "18.3.1" - resolved "https://registry.yarnpkg.com/react-is/-/react-is-18.3.1.tgz#e83557dc12eae63a99e003a46388b1dcbb44db7e" - integrity sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg== - -readable-stream@^3.4.0: - version "3.6.2" - resolved "https://registry.yarnpkg.com/readable-stream/-/readable-stream-3.6.2.tgz#56a9b36ea965c00c5a93ef31eb111a0f11056967" - integrity sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA== - dependencies: - inherits "^2.0.3" - string_decoder "^1.1.1" - util-deprecate "^1.0.1" - -real-require@^0.2.0: - version "0.2.0" - resolved "https://registry.yarnpkg.com/real-require/-/real-require-0.2.0.tgz#209632dea1810be2ae063a6ac084fee7e33fba78" - integrity sha512-57frrGM/OCTLqLOAh0mhVA9VBMHd+9U7Zb2THMGdBUoZVOtGbJzjxsYGDJ3A9AYYCP4hn6y1TVbaOfzWtm5GFg== - -require-directory@^2.1.1: - version "2.1.1" - resolved "https://registry.yarnpkg.com/require-directory/-/require-directory-2.1.1.tgz#8c64ad5fd30dab1c976e2344ffe7f792a6a6df42" - integrity sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q== - -require-from-string@^2.0.2: - version "2.0.2" - resolved "https://registry.yarnpkg.com/require-from-string/-/require-from-string-2.0.2.tgz#89a7fdd938261267318eafe14f9c32e598c36909" - integrity sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw== - -resolve-cwd@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/resolve-cwd/-/resolve-cwd-3.0.0.tgz#0f0075f1bb2544766cf73ba6a6e2adfebcb13f2d" - integrity sha512-OrZaX2Mb+rJCpH/6CpSqt9xFVpN++x01XnN2ie9g6P5/3xelLAkXWVADpdz1IHD/KFfEXyE6V0U01OQ3UO2rEg== - dependencies: - resolve-from "^5.0.0" - -resolve-from@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/resolve-from/-/resolve-from-4.0.0.tgz#4abcd852ad32dd7baabfe9b40e00a36db5f392e6" - integrity sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g== - -resolve-from@^5.0.0: - version "5.0.0" - resolved "https://registry.yarnpkg.com/resolve-from/-/resolve-from-5.0.0.tgz#c35225843df8f776df21c57557bc087e9dfdfc69" - integrity sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw== - -resolve.exports@^2.0.0: - version "2.0.3" - resolved "https://registry.yarnpkg.com/resolve.exports/-/resolve.exports-2.0.3.tgz#41955e6f1b4013b7586f873749a635dea07ebe3f" - integrity sha512-OcXjMsGdhL4XnbShKpAcSqPMzQoYkYyhbEaeSko47MjRP9NfEQMhZkXL1DoFlt9LWQn4YttrdnV6X2OiyzBi+A== - -resolve@^1.20.0: - version "1.22.11" - resolved "https://registry.yarnpkg.com/resolve/-/resolve-1.22.11.tgz#aad857ce1ffb8bfa9b0b1ac29f1156383f68c262" - integrity sha512-RfqAvLnMl313r7c9oclB1HhUEAezcpLjz95wFH4LVuhk9JF/r22qmVP9AMmOU4vMX7Q8pN8jwNg/CSpdFnMjTQ== - dependencies: - is-core-module "^2.16.1" - path-parse "^1.0.7" - supports-preserve-symlinks-flag "^1.0.0" - -reusify@^1.0.4: - version "1.1.0" - resolved "https://registry.yarnpkg.com/reusify/-/reusify-1.1.0.tgz#0fe13b9522e1473f51b558ee796e08f11f9b489f" - integrity sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw== - -router@^2.2.0: - version "2.2.0" - resolved "https://registry.yarnpkg.com/router/-/router-2.2.0.tgz#019be620b711c87641167cc79b99090f00b146ef" - integrity sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ== - dependencies: - debug "^4.4.0" - depd "^2.0.0" - is-promise "^4.0.0" - parseurl "^1.3.3" - path-to-regexp "^8.0.0" - -run-parallel@^1.1.9: - version "1.2.0" - resolved "https://registry.yarnpkg.com/run-parallel/-/run-parallel-1.2.0.tgz#66d1368da7bdf921eb9d95bd1a9229e7f21a43ee" - integrity sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA== - dependencies: - queue-microtask "^1.2.2" - -safe-buffer@~5.2.0: - version "5.2.1" - resolved "https://registry.yarnpkg.com/safe-buffer/-/safe-buffer-5.2.1.tgz#1eaf9fa9bdb1fdd4ec75f58f9cdb4e6b7827eec6" - integrity sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ== - -safe-stable-stringify@^2.3.1: - version "2.5.0" - resolved "https://registry.yarnpkg.com/safe-stable-stringify/-/safe-stable-stringify-2.5.0.tgz#4ca2f8e385f2831c432a719b108a3bf7af42a1dd" - integrity sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA== - -"safer-buffer@>= 2.1.2 < 3", "safer-buffer@>= 2.1.2 < 3.0.0": - version "2.1.2" - resolved "https://registry.yarnpkg.com/safer-buffer/-/safer-buffer-2.1.2.tgz#44fa161b0187b9549dd84bb91802f9bd8385cd6a" - integrity sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg== - -secure-json-parse@^4.0.0: - version "4.1.0" - resolved "https://registry.yarnpkg.com/secure-json-parse/-/secure-json-parse-4.1.0.tgz#4f1ab41c67a13497ea1b9131bb4183a22865477c" - integrity sha512-l4KnYfEyqYJxDwlNVyRfO2E4NTHfMKAWdUuA8J0yve2Dz/E/PdBepY03RvyJpssIpRFwJoCD55wA+mEDs6ByWA== - -semver@^6.3.0, semver@^6.3.1: - version "6.3.1" - resolved "https://registry.yarnpkg.com/semver/-/semver-6.3.1.tgz#556d2ef8689146e46dcea4bfdd095f3434dffcb4" - integrity sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA== - -semver@^7.5.3, semver@^7.5.4, semver@^7.6.0, semver@^7.7.3: - version "7.7.3" - resolved "https://registry.yarnpkg.com/semver/-/semver-7.7.3.tgz#4b5f4143d007633a8dc671cd0a6ef9147b8bb946" - integrity sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q== - -send@^1.1.0, send@^1.2.0: - version "1.2.1" - resolved "https://registry.yarnpkg.com/send/-/send-1.2.1.tgz#9eab743b874f3550f40a26867bf286ad60d3f3ed" - integrity sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ== - dependencies: - debug "^4.4.3" - encodeurl "^2.0.0" - escape-html "^1.0.3" - etag "^1.8.1" - fresh "^2.0.0" - http-errors "^2.0.1" - mime-types "^3.0.2" - ms "^2.1.3" - on-finished "^2.4.1" - range-parser "^1.2.1" - statuses "^2.0.2" - -serve-static@^2.2.0: - version "2.2.1" - resolved "https://registry.yarnpkg.com/serve-static/-/serve-static-2.2.1.tgz#7f186a4a4e5f5b663ad7a4294ff1bf37cf0e98a9" - integrity sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw== - dependencies: - encodeurl "^2.0.0" - escape-html "^1.0.3" - parseurl "^1.3.3" - send "^1.2.0" - -setprototypeof@~1.2.0: - version "1.2.0" - resolved "https://registry.yarnpkg.com/setprototypeof/-/setprototypeof-1.2.0.tgz#66c9a24a73f9fc28cbe66b09fed3d33dcaf1b424" - integrity sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw== - -shebang-command@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/shebang-command/-/shebang-command-2.0.0.tgz#ccd0af4f8835fbdc265b82461aaf0c36663f34ea" - integrity sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA== - dependencies: - shebang-regex "^3.0.0" - -shebang-regex@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/shebang-regex/-/shebang-regex-3.0.0.tgz#ae16f1644d873ecad843b0307b143362d4c42172" - integrity sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A== - -side-channel-list@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/side-channel-list/-/side-channel-list-1.0.0.tgz#10cb5984263115d3b7a0e336591e290a830af8ad" - integrity sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA== - dependencies: - es-errors "^1.3.0" - object-inspect "^1.13.3" - -side-channel-map@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/side-channel-map/-/side-channel-map-1.0.1.tgz#d6bb6b37902c6fef5174e5f533fab4c732a26f42" - integrity sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA== - dependencies: - call-bound "^1.0.2" - es-errors "^1.3.0" - get-intrinsic "^1.2.5" - object-inspect "^1.13.3" - -side-channel-weakmap@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz#11dda19d5368e40ce9ec2bdc1fb0ecbc0790ecea" - integrity sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A== - dependencies: - call-bound "^1.0.2" - es-errors "^1.3.0" - get-intrinsic "^1.2.5" - object-inspect "^1.13.3" - side-channel-map "^1.0.1" - -side-channel@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/side-channel/-/side-channel-1.1.0.tgz#c3fcff9c4da932784873335ec9765fa94ff66bc9" - integrity sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw== - dependencies: - es-errors "^1.3.0" - object-inspect "^1.13.3" - side-channel-list "^1.0.0" - side-channel-map "^1.0.1" - side-channel-weakmap "^1.0.2" - -signal-exit@^3.0.3, signal-exit@^3.0.7: - version "3.0.7" - resolved "https://registry.yarnpkg.com/signal-exit/-/signal-exit-3.0.7.tgz#a9a1767f8af84155114eaabd73f99273c8f59ad9" - integrity sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ== - -signal-exit@^4.1.0: - version "4.1.0" - resolved "https://registry.yarnpkg.com/signal-exit/-/signal-exit-4.1.0.tgz#952188c1cbd546070e2dd20d0f41c0ae0530cb04" - integrity sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw== - -sisteransi@^1.0.5: - version "1.0.5" - resolved "https://registry.yarnpkg.com/sisteransi/-/sisteransi-1.0.5.tgz#134d681297756437cc05ca01370d3a7a571075ed" - integrity sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg== - -slash@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/slash/-/slash-3.0.0.tgz#6539be870c165adbd5240220dbe361f1bc4d4634" - integrity sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q== - -sonic-boom@^4.0.1: - version "4.2.1" - resolved "https://registry.yarnpkg.com/sonic-boom/-/sonic-boom-4.2.1.tgz#28598250df4899c0ac572d7e2f0460690ba6a030" - integrity sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q== - dependencies: - atomic-sleep "^1.0.0" - -source-map-support@0.5.13: - version "0.5.13" - resolved "https://registry.yarnpkg.com/source-map-support/-/source-map-support-0.5.13.tgz#31b24a9c2e73c2de85066c0feb7d44767ed52932" - integrity sha512-SHSKFHadjVA5oR4PPqhtAVdcBWwRYVd6g6cAXnIbRiIwc2EhPrTuKUBdSLvlEKyIP3GCf89fltvcZiP9MMFA1w== - dependencies: - buffer-from "^1.0.0" - source-map "^0.6.0" - -source-map@^0.6.0, source-map@^0.6.1: - version "0.6.1" - resolved "https://registry.yarnpkg.com/source-map/-/source-map-0.6.1.tgz#74722af32e9614e9c287a8d0bbde48b5e2f1a263" - integrity sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g== - -split2@^4.0.0: - version "4.2.0" - resolved "https://registry.yarnpkg.com/split2/-/split2-4.2.0.tgz#c9c5920904d148bab0b9f67145f245a86aadbfa4" - integrity sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg== - -sprintf-js@~1.0.2: - version "1.0.3" - resolved "https://registry.yarnpkg.com/sprintf-js/-/sprintf-js-1.0.3.tgz#04e6926f662895354f3dd015203633b857297e2c" - integrity sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g== - -stack-utils@^2.0.3: - version "2.0.6" - resolved "https://registry.yarnpkg.com/stack-utils/-/stack-utils-2.0.6.tgz#aaf0748169c02fc33c8232abccf933f54a1cc34f" - integrity sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ== - dependencies: - escape-string-regexp "^2.0.0" - -statuses@^2.0.1, statuses@^2.0.2, statuses@~2.0.2: - version "2.0.2" - resolved "https://registry.yarnpkg.com/statuses/-/statuses-2.0.2.tgz#8f75eecef765b5e1cfcdc080da59409ed424e382" - integrity sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw== - -string-length@^4.0.1: - version "4.0.2" - resolved "https://registry.yarnpkg.com/string-length/-/string-length-4.0.2.tgz#a8a8dc7bd5c1a82b9b3c8b87e125f66871b6e57a" - integrity sha512-+l6rNN5fYHNhZZy41RXsYptCjA2Igmq4EG7kZAYFQI1E1VTXarr6ZPXBg6eq7Y6eK4FEhY6AJlyuFIb/v/S0VQ== - dependencies: - char-regex "^1.0.2" - strip-ansi "^6.0.0" - -string-to-stream@^3.0.1: - version "3.0.1" - resolved "https://registry.yarnpkg.com/string-to-stream/-/string-to-stream-3.0.1.tgz#480e6fb4d5476d31cb2221f75307a5dcb6638a42" - integrity sha512-Hl092MV3USJuUCC6mfl9sPzGloA3K5VwdIeJjYIkXY/8K+mUvaeEabWJgArp+xXrsWxCajeT2pc4axbVhIZJyg== - dependencies: - readable-stream "^3.4.0" - -string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.3: - version "4.2.3" - resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010" - integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g== - dependencies: - emoji-regex "^8.0.0" - is-fullwidth-code-point "^3.0.0" - strip-ansi "^6.0.1" - -string_decoder@^1.1.1: - version "1.3.0" - resolved "https://registry.yarnpkg.com/string_decoder/-/string_decoder-1.3.0.tgz#42f114594a46cf1a8e30b0a84f56c78c3edac21e" - integrity sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA== - dependencies: - safe-buffer "~5.2.0" - -strip-ansi@^6.0.0, strip-ansi@^6.0.1: - version "6.0.1" - resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.1.tgz#9e26c63d30f53443e9489495b2105d37b67a85d9" - integrity sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A== - dependencies: - ansi-regex "^5.0.1" - -strip-bom@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/strip-bom/-/strip-bom-3.0.0.tgz#2334c18e9c759f7bdd56fdef7e9ae3d588e68ed3" - integrity sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA== - -strip-bom@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/strip-bom/-/strip-bom-4.0.0.tgz#9c3505c1db45bcedca3d9cf7a16f5c5aa3901878" - integrity sha512-3xurFv5tEgii33Zi8Jtp55wEIILR9eh34FAW00PZf+JnSsTmV/ioewSgQl97JHvgjoRGwPShsWm+IdrxB35d0w== - -strip-final-newline@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/strip-final-newline/-/strip-final-newline-2.0.0.tgz#89b852fb2fcbe936f6f4b3187afb0a12c1ab58ad" - integrity sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA== - -strip-json-comments@^3.1.1: - version "3.1.1" - resolved "https://registry.yarnpkg.com/strip-json-comments/-/strip-json-comments-3.1.1.tgz#31f1281b3832630434831c310c01cccda8cbe006" - integrity sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig== - -strip-json-comments@^5.0.2: - version "5.0.3" - resolved "https://registry.yarnpkg.com/strip-json-comments/-/strip-json-comments-5.0.3.tgz#b7304249dd402ee67fd518ada993ab3593458bcf" - integrity sha512-1tB5mhVo7U+ETBKNf92xT4hrQa3pm0MZ0PQvuDnWgAAGHDsfp4lPSpiS6psrSiet87wyGPh9ft6wmhOMQ0hDiw== - -superstruct@^1.0.4: - version "1.0.4" - resolved "https://registry.yarnpkg.com/superstruct/-/superstruct-1.0.4.tgz#0adb99a7578bd2f1c526220da6571b2d485d91ca" - integrity sha512-7JpaAoX2NGyoFlI9NBh66BQXGONc+uE+MRS5i2iOBKuS4e+ccgMDjATgZldkah+33DakBxDHiss9kvUcGAO8UQ== - -supports-color@^7.1.0: - version "7.2.0" - resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-7.2.0.tgz#1b7dcdcb32b8138801b3e478ba6a51caa89648da" - integrity sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw== - dependencies: - has-flag "^4.0.0" - -supports-color@^8.0.0: - version "8.1.1" - resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-8.1.1.tgz#cd6fc17e28500cff56c1b86c0a7fd4a54a73005c" - integrity sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q== - dependencies: - has-flag "^4.0.0" - -supports-preserve-symlinks-flag@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz#6eda4bd344a3c94aea376d4cc31bc77311039e09" - integrity sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w== - -synckit@^0.11.12: - version "0.11.12" - resolved "https://registry.yarnpkg.com/synckit/-/synckit-0.11.12.tgz#abe74124264fbc00a48011b0d98bdc1cffb64a7b" - integrity sha512-Bh7QjT8/SuKUIfObSXNHNSK6WHo6J1tHCqJsuaFDP7gP0fkzSfTxI8y85JrppZ0h8l0maIgc2tfuZQ6/t3GtnQ== - dependencies: - "@pkgr/core" "^0.2.9" - -test-exclude@^6.0.0: - version "6.0.0" - resolved "https://registry.yarnpkg.com/test-exclude/-/test-exclude-6.0.0.tgz#04a8698661d805ea6fa293b6cb9e63ac044ef15e" - integrity sha512-cAGWPIyOHU6zlmg88jwm7VRyXnMN7iV68OGAbYDk/Mh/xC/pzVPlQtY6ngoIH/5/tciuhGfvESU8GrHrcxD56w== - dependencies: - "@istanbuljs/schema" "^0.1.2" - glob "^7.1.4" - minimatch "^3.0.4" - -thread-stream@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/thread-stream/-/thread-stream-4.0.0.tgz#732f007c24da7084f729d6e3a7e3f5934a7380b7" - integrity sha512-4iMVL6HAINXWf1ZKZjIPcz5wYaOdPhtO8ATvZ+Xqp3BTdaqtAwQkNmKORqcIo5YkQqGXq5cwfswDwMqqQNrpJA== - dependencies: - real-require "^0.2.0" - -tmp@^0.0.33: - version "0.0.33" - resolved "https://registry.yarnpkg.com/tmp/-/tmp-0.0.33.tgz#6d34335889768d21b2bcda0aa277ced3b1bfadf9" - integrity sha512-jRCJlojKnZ3addtTOjdIqoRuPEKBvNXcGYqzO6zWZX8KfKEpnGY5jfggJQ3EjKuu8D4bJRr0y+cYJFmYbImXGw== - dependencies: - os-tmpdir "~1.0.2" - -tmpl@1.0.5: - version "1.0.5" - resolved "https://registry.yarnpkg.com/tmpl/-/tmpl-1.0.5.tgz#8683e0b902bb9c20c4f726e3c0b69f36518c07cc" - integrity sha512-3f0uOEAQwIqGuWW2MVzYg8fV/QNnc/IpuJNG837rLuczAaLVHslWHZQj4IGiEl5Hs3kkbhwL9Ab7Hrsmuj+Smw== - -to-regex-range@^5.0.1: - version "5.0.1" - resolved "https://registry.yarnpkg.com/to-regex-range/-/to-regex-range-5.0.1.tgz#1648c44aae7c8d988a326018ed72f5b4dd0392e4" - integrity sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ== - dependencies: - is-number "^7.0.0" - -toidentifier@~1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/toidentifier/-/toidentifier-1.0.1.tgz#3be34321a88a820ed1bd80dfaa33e479fbb8dd35" - integrity sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA== - -ts-api-utils@^2.0.1: - version "2.4.0" - resolved "https://registry.yarnpkg.com/ts-api-utils/-/ts-api-utils-2.4.0.tgz#2690579f96d2790253bdcf1ca35d569ad78f9ad8" - integrity sha512-3TaVTaAv2gTiMB35i3FiGJaRfwb3Pyn/j3m/bfAvGe8FB7CF6u+LMYqYlDh7reQf7UNvoTvdfAqHGmPGOSsPmA== - -ts-jest@^29.1.0: - version "29.4.6" - resolved "https://registry.yarnpkg.com/ts-jest/-/ts-jest-29.4.6.tgz#51cb7c133f227396818b71297ad7409bb77106e9" - integrity sha512-fSpWtOO/1AjSNQguk43hb/JCo16oJDnMJf3CdEGNkqsEX3t0KX96xvyX1D7PfLCpVoKu4MfVrqUkFyblYoY4lA== - dependencies: - bs-logger "^0.2.6" - fast-json-stable-stringify "^2.1.0" - handlebars "^4.7.8" - json5 "^2.2.3" - lodash.memoize "^4.1.2" - make-error "^1.3.6" - semver "^7.7.3" - type-fest "^4.41.0" - yargs-parser "^21.1.1" - -ts-morph@^19.0.0: - version "19.0.0" - resolved "https://registry.yarnpkg.com/ts-morph/-/ts-morph-19.0.0.tgz#43e95fb0156c3fe3c77c814ac26b7d0be2f93169" - integrity sha512-D6qcpiJdn46tUqV45vr5UGM2dnIEuTGNxVhg0sk5NX11orcouwj6i1bMqZIz2mZTZB1Hcgy7C3oEVhAT+f6mbQ== - dependencies: - "@ts-morph/common" "~0.20.0" - code-block-writer "^12.0.0" - -ts-node@^10.5.0: - version "10.9.2" - resolved "https://registry.yarnpkg.com/ts-node/-/ts-node-10.9.2.tgz#70f021c9e185bccdca820e26dc413805c101c71f" - integrity sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ== - dependencies: - "@cspotcode/source-map-support" "^0.8.0" - "@tsconfig/node10" "^1.0.7" - "@tsconfig/node12" "^1.0.7" - "@tsconfig/node14" "^1.0.0" - "@tsconfig/node16" "^1.0.2" - acorn "^8.4.1" - acorn-walk "^8.1.1" - arg "^4.1.0" - create-require "^1.1.0" - diff "^4.0.1" - make-error "^1.1.1" - v8-compile-cache-lib "^3.0.1" - yn "3.1.1" - -"tsc-multi@https://github.com/stainless-api/tsc-multi/releases/download/v1.1.11/tsc-multi.tgz": - version "1.1.11" - resolved "https://github.com/stainless-api/tsc-multi/releases/download/v1.1.11/tsc-multi.tgz#010247051be13b55abdc98f787c017285149f4f2" - dependencies: - debug "^4.3.7" - fast-glob "^3.3.2" - get-stdin "^8.0.0" - p-all "^3.0.0" - picocolors "^1.1.1" - signal-exit "^3.0.7" - string-to-stream "^3.0.1" - superstruct "^1.0.4" - tslib "^2.8.1" - yargs "^17.7.2" - -tsconfig-paths@^4.0.0: - version "4.2.0" - resolved "https://registry.yarnpkg.com/tsconfig-paths/-/tsconfig-paths-4.2.0.tgz#ef78e19039133446d244beac0fd6a1632e2d107c" - integrity sha512-NoZ4roiN7LnbKn9QqE1amc9DJfzvZXxF4xDavcOWt1BPkdx+m+0gJuPM+S0vCe7zTJMYUP0R8pO2XMr+Y8oLIg== - dependencies: - json5 "^2.2.2" - minimist "^1.2.6" - strip-bom "^3.0.0" - -tslib@^2.8.1: - version "2.8.1" - resolved "https://registry.yarnpkg.com/tslib/-/tslib-2.8.1.tgz#612efe4ed235d567e8aba5f2a5fab70280ade83f" - integrity sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w== - -type-check@^0.4.0, type-check@~0.4.0: - version "0.4.0" - resolved "https://registry.yarnpkg.com/type-check/-/type-check-0.4.0.tgz#07b8203bfa7056c0657050e3ccd2c37730bab8f1" - integrity sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew== - dependencies: - prelude-ls "^1.2.1" - -type-detect@4.0.8: - version "4.0.8" - resolved "https://registry.yarnpkg.com/type-detect/-/type-detect-4.0.8.tgz#7646fb5f18871cfbb7749e69bd39a6388eb7450c" - integrity sha512-0fr/mIH1dlO+x7TlcMy+bIDqKPsw/70tVyeHW787goQjhmqaZe10uwLujubK9q9Lg6Fiho1KUKDYz0Z7k7g5/g== - -type-fest@^0.21.3: - version "0.21.3" - resolved "https://registry.yarnpkg.com/type-fest/-/type-fest-0.21.3.tgz#d260a24b0198436e133fa26a524a6d65fa3b2e37" - integrity sha512-t0rzBq87m3fVcduHDUFhKmyyX+9eo6WQjZvf51Ea/M0Q7+T374Jp1aUiyUl0GKxp8M/OETVHSDvmkyPgvX+X2w== - -type-fest@^4.41.0: - version "4.41.0" - resolved "https://registry.yarnpkg.com/type-fest/-/type-fest-4.41.0.tgz#6ae1c8e5731273c2bf1f58ad39cbae2c91a46c58" - integrity sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA== - -type-is@^2.0.1: - version "2.0.1" - resolved "https://registry.yarnpkg.com/type-is/-/type-is-2.0.1.tgz#64f6cf03f92fce4015c2b224793f6bdd4b068c97" - integrity sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw== - dependencies: - content-type "^1.0.5" - media-typer "^1.1.0" - mime-types "^3.0.0" - -typescript@5.8.3: - version "5.8.3" - resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.8.3.tgz#92f8a3e5e3cf497356f4178c34cd65a7f5e8440e" - integrity sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ== - -uglify-js@^3.1.4: - version "3.19.3" - resolved "https://registry.yarnpkg.com/uglify-js/-/uglify-js-3.19.3.tgz#82315e9bbc6f2b25888858acd1fff8441035b77f" - integrity sha512-v3Xu+yuwBXisp6QYTcH4UbH+xYJXqnq2m/LtQVWKWzYc1iehYnLixoQDN9FH6/j9/oybfd6W9Ghwkl8+UMKTKQ== - -undici-types@~6.21.0: - version "6.21.0" - resolved "https://registry.yarnpkg.com/undici-types/-/undici-types-6.21.0.tgz#691d00af3909be93a7faa13be61b3a5b50ef12cb" - integrity sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ== - -undici-types@~7.16.0: - version "7.16.0" - resolved "https://registry.yarnpkg.com/undici-types/-/undici-types-7.16.0.tgz#ffccdff36aea4884cbfce9a750a0580224f58a46" - integrity sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw== - -universalify@^2.0.0: - version "2.0.1" - resolved "https://registry.yarnpkg.com/universalify/-/universalify-2.0.1.tgz#168efc2180964e6386d061e094df61afe239b18d" - integrity sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw== - -unpipe@~1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/unpipe/-/unpipe-1.0.0.tgz#b2bf4ee8514aae6165b4817829d21b2ef49904ec" - integrity sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ== - -update-browserslist-db@^1.2.0: - version "1.2.3" - resolved "https://registry.yarnpkg.com/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz#64d76db58713136acbeb4c49114366cc6cc2e80d" - integrity sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w== - dependencies: - escalade "^3.2.0" - picocolors "^1.1.1" - -uri-js@^4.2.2: - version "4.4.1" - resolved "https://registry.yarnpkg.com/uri-js/-/uri-js-4.4.1.tgz#9b1a52595225859e55f669d928f88c6c57f2a77e" - integrity sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg== - dependencies: - punycode "^2.1.0" - -util-deprecate@^1.0.1: - version "1.0.2" - resolved "https://registry.yarnpkg.com/util-deprecate/-/util-deprecate-1.0.2.tgz#450d4dc9fa70de732762fbd2d4a28981419a0ccf" - integrity sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw== - -v8-compile-cache-lib@^3.0.1: - version "3.0.1" - resolved "https://registry.yarnpkg.com/v8-compile-cache-lib/-/v8-compile-cache-lib-3.0.1.tgz#6336e8d71965cb3d35a1bbb7868445a7c05264bf" - integrity sha512-wa7YjyUGfNZngI/vtK0UHAN+lgDCxBPCylVXGp0zu59Fz5aiGtNXaq3DhIov063MorB+VfufLh3JlF2KdTK3xg== - -v8-to-istanbul@^9.0.1: - version "9.3.0" - resolved "https://registry.yarnpkg.com/v8-to-istanbul/-/v8-to-istanbul-9.3.0.tgz#b9572abfa62bd556c16d75fdebc1a411d5ff3175" - integrity sha512-kiGUalWN+rgBJ/1OHZsBtU4rXZOfj/7rKQxULKlIzwzQSvMJUUNgPwJEEh7gU6xEVxC0ahoOBvN2YI8GH6FNgA== - dependencies: - "@jridgewell/trace-mapping" "^0.3.12" - "@types/istanbul-lib-coverage" "^2.0.1" - convert-source-map "^2.0.0" - -vary@^1, vary@^1.1.2: - version "1.1.2" - resolved "https://registry.yarnpkg.com/vary/-/vary-1.1.2.tgz#2299f02c6ded30d4a5961b0b9f74524a18f634fc" - integrity sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg== - -walker@^1.0.8: - version "1.0.8" - resolved "https://registry.yarnpkg.com/walker/-/walker-1.0.8.tgz#bd498db477afe573dc04185f011d3ab8a8d7653f" - integrity sha512-ts/8E8l5b7kY0vlWLewOkDXMmPdLcVV4GmOQLyxuSswIJsweeFZtAsMF7k1Nszz+TYBQrlYRmzOnr398y1JemQ== - dependencies: - makeerror "1.0.12" - -which@^2.0.1: - version "2.0.2" - resolved "https://registry.yarnpkg.com/which/-/which-2.0.2.tgz#7c6a8dd0a636a0327e10b59c9286eee93f3f51b1" - integrity sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA== - dependencies: - isexe "^2.0.0" - -word-wrap@^1.2.5: - version "1.2.5" - resolved "https://registry.yarnpkg.com/word-wrap/-/word-wrap-1.2.5.tgz#d2c45c6dd4fbce621a66f136cbe328afd0410b34" - integrity sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA== - -wordwrap@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/wordwrap/-/wordwrap-1.0.0.tgz#27584810891456a4171c8d0226441ade90cbcaeb" - integrity sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q== - -wrap-ansi@^6.2.0: - version "6.2.0" - resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-6.2.0.tgz#e9393ba07102e6c91a3b221478f0257cd2856e53" - integrity sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA== - dependencies: - ansi-styles "^4.0.0" - string-width "^4.1.0" - strip-ansi "^6.0.0" - -wrap-ansi@^7.0.0: - version "7.0.0" - resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-7.0.0.tgz#67e145cff510a6a6984bdf1152911d69d2eb9e43" - integrity sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q== - dependencies: - ansi-styles "^4.0.0" - string-width "^4.1.0" - strip-ansi "^6.0.0" - -wrappy@1: - version "1.0.2" - resolved "https://registry.yarnpkg.com/wrappy/-/wrappy-1.0.2.tgz#b5243d8f3ec1aa35f1364605bc0d1036e30ab69f" - integrity sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ== - -write-file-atomic@^4.0.2: - version "4.0.2" - resolved "https://registry.yarnpkg.com/write-file-atomic/-/write-file-atomic-4.0.2.tgz#a9df01ae5b77858a027fd2e80768ee433555fcfd" - integrity sha512-7KxauUdBmSdWnmpaGFg+ppNjKF8uNLry8LyzjauQDOVONfFLNKrKvQOxZ/VuTIcS/gge/YNahf5RIIQWTSarlg== - dependencies: - imurmurhash "^0.1.4" - signal-exit "^3.0.7" - -y18n@^5.0.5: - version "5.0.8" - resolved "https://registry.yarnpkg.com/y18n/-/y18n-5.0.8.tgz#7f4934d0f7ca8c56f95314939ddcd2dd91ce1d55" - integrity sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA== - -yallist@^3.0.2: - version "3.1.1" - resolved "https://registry.yarnpkg.com/yallist/-/yallist-3.1.1.tgz#dbb7daf9bfd8bac9ab45ebf602b8cbad0d5d08fd" - integrity sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g== - -yargs-parser@^21.1.1: - version "21.1.1" - resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-21.1.1.tgz#9096bceebf990d21bb31fa9516e0ede294a77d35" - integrity sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw== - -yargs@^17.3.1, yargs@^17.7.2: - version "17.7.2" - resolved "https://registry.yarnpkg.com/yargs/-/yargs-17.7.2.tgz#991df39aca675a192b816e1e0363f9d75d2aa269" - integrity sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w== - dependencies: - cliui "^8.0.1" - escalade "^3.1.1" - get-caller-file "^2.0.5" - require-directory "^2.1.1" - string-width "^4.2.3" - y18n "^5.0.5" - yargs-parser "^21.1.1" - -yn@3.1.1: - version "3.1.1" - resolved "https://registry.yarnpkg.com/yn/-/yn-3.1.1.tgz#1e87401a09d767c1d5eab26a6e4c185182d2eb50" - integrity sha512-Ux4ygGWsu2c7isFWe8Yu1YluJmqVhxqK2cLXNQA5AcC3QfbGNpM7fu0Y8b/z16pXLnFxZYvWhd3fhBY9DLmC6Q== - -yocto-queue@^0.1.0: - version "0.1.0" - resolved "https://registry.yarnpkg.com/yocto-queue/-/yocto-queue-0.1.0.tgz#0294eb3dee05028d31ee1a5fa2c556a6aaf10a1b" - integrity sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q== - -yoctocolors-cjs@^2.1.2: - version "2.1.3" - resolved "https://registry.yarnpkg.com/yoctocolors-cjs/-/yoctocolors-cjs-2.1.3.tgz#7e4964ea8ec422b7a40ac917d3a344cfd2304baa" - integrity sha512-U/PBtDf35ff0D8X8D0jfdzHYEPFxAI7jJlxZXwCSez5M3190m+QobIfh+sWDWSHMCWWJN2AWamkegn6vr6YBTw== - -zod-to-json-schema@^3.24.5, zod-to-json-schema@^3.24.6, zod-to-json-schema@^3.25.1: - version "3.25.1" - resolved "https://registry.yarnpkg.com/zod-to-json-schema/-/zod-to-json-schema-3.25.1.tgz#7f24962101a439ddade2bf1aeab3c3bfec7d84ba" - integrity sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA== - -zod-validation-error@^4.0.1: - version "4.0.2" - resolved "https://registry.yarnpkg.com/zod-validation-error/-/zod-validation-error-4.0.2.tgz#bc605eba49ce0fcd598c127fee1c236be3f22918" - integrity sha512-Q6/nZLe6jxuU80qb/4uJ4t5v2VEZ44lzQjPDhYJNztRQ4wyWc6VF3D3Kb/fAuPetZQnhS3hnajCf9CsWesghLQ== - -"zod@^3.25 || ^4.0": - version "4.3.5" - resolved "https://registry.yarnpkg.com/zod/-/zod-4.3.5.tgz#aeb269a6f9fc259b1212c348c7c5432aaa474d2a" - integrity sha512-k7Nwx6vuWx1IJ9Bjuf4Zt1PEllcwe7cls3VNzm4CQ1/hgtFUK2bRNG3rvnpPUhFjmqJKAKtjV576KnUkHocg/g== - -zod@^3.25.20, zod@^3.25.67: - version "3.25.76" - resolved "https://registry.yarnpkg.com/zod/-/zod-3.25.76.tgz#26841c3f6fd22a6a2760e7ccb719179768471e34" - integrity sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ== diff --git a/scripts/build b/scripts/build index 4716248d..7c739e87 100755 --- a/scripts/build +++ b/scripts/build @@ -49,9 +49,3 @@ if [ -e ./scripts/build-deno ] then ./scripts/build-deno fi -# build all sub-packages -for dir in packages/*; do - if [ -d "$dir" ]; then - (cd "$dir" && yarn install --pure-lockfile && yarn build) - fi -done diff --git a/scripts/build-all b/scripts/build-all deleted file mode 100755 index 4e5ac01f..00000000 --- a/scripts/build-all +++ /dev/null @@ -1,5 +0,0 @@ -#!/usr/bin/env bash - -# build-all is deprecated, use build instead - -bash ./scripts/build diff --git a/scripts/publish-packages.ts b/scripts/publish-packages.ts deleted file mode 100644 index 50e93fef..00000000 --- a/scripts/publish-packages.ts +++ /dev/null @@ -1,102 +0,0 @@ -/** - * Called from the `create-releases.yml` workflow with the output - * of the release please action as the first argument. - * - * Example JSON input: - * - * ```json - { - "releases_created": "true", - "release_created": "true", - "id": "137967744", - "name": "sdk: v0.14.5", - "tag_name": "sdk-v0.14.5", - "sha": "7cc2ba5c694e76a117f731d4cf0b06f8b8361f2e", - "body": "## 0.14.5 (2024-01-22)\n\n...", - "html_url": "https://github.com/$org/$repo/releases/tag/sdk-v0.14.5", - "draft": "false", - "upload_url": "https://uploads.github.com/repos/$org/$repo/releases/137967744/assets{?name,label}", - "path": ".", - "version": "0.14.5", - "major": "0", - "minor": "14", - "patch": "5", - "packages/additional-sdk--release_created": "true", - "packages/additional-sdk--id": "137967756", - "packages/additional-sdk--name": "additional-sdk: v0.5.2", - "packages/additional-sdk--tag_name": "additional-sdk-v0.5.2", - "packages/additional-sdk--sha": "7cc2ba5c694e76a117f731d4cf0b06f8b8361f2e", - "packages/additional-sdk--body": "## 0.5.2 (2024-01-22)\n\n...", - "packages/additional-sdk--html_url": "https://github.com/$org/$repo/releases/tag/additional-sdk-v0.5.2", - "packages/additional-sdk--draft": "false", - "packages/additional-sdk--upload_url": "https://uploads.github.com/repos/$org/$repo/releases/137967756/assets{?name,label}", - "packages/additional-sdk--path": "packages/additional-sdk", - "packages/additional-sdk--version": "0.5.2", - "packages/additional-sdk--major": "0", - "packages/additional-sdk--minor": "5", - "packages/additional-sdk--patch": "2", - "paths_released": "[\".\",\"packages/additional-sdk\"]" - } - ``` - */ - -import { execSync } from 'child_process'; -import path from 'path'; - -function main() { - const data = process.argv[2] ?? process.env['DATA']; - if (!data) { - throw new Error(`Usage: publish-packages.ts '{"json": "obj"}'`); - } - - const rootDir = path.join(__dirname, '..'); - console.log('root dir', rootDir); - console.log(`publish-packages called with ${data}`); - - const outputs = JSON.parse(data); - - const rawPaths = outputs.paths_released; - - if (!rawPaths) { - console.error(JSON.stringify(outputs, null, 2)); - throw new Error('Expected outputs to contain a truthy `paths_released` property'); - } - if (typeof rawPaths !== 'string') { - console.error(JSON.stringify(outputs, null, 2)); - throw new Error('Expected outputs `paths_released` property to be a JSON string'); - } - - const paths = JSON.parse(rawPaths); - if (!Array.isArray(paths)) { - console.error(JSON.stringify(outputs, null, 2)); - throw new Error('Expected outputs `paths_released` property to be an array'); - } - if (!paths.length) { - console.error(JSON.stringify(outputs, null, 2)); - throw new Error('Expected outputs `paths_released` property to contain at least one entry'); - } - - const publishScriptPath = path.join(rootDir, 'bin', 'publish-npm'); - console.log('Using publish script at', publishScriptPath); - - console.log('Ensuring root package is built'); - console.log(`$ yarn build`); - execSync(`yarn build`, { cwd: rootDir, encoding: 'utf8', stdio: 'inherit' }); - - for (const relPackagePath of paths) { - console.log('\n'); - - const packagePath = path.join(rootDir, relPackagePath); - console.log(`Publishing in directory: ${packagePath}`); - - console.log(`$ yarn install`); - execSync(`yarn install`, { cwd: packagePath, encoding: 'utf8', stdio: 'inherit' }); - - console.log(`$ bash ${publishScriptPath}`); - execSync(`bash ${publishScriptPath}`, { cwd: packagePath, encoding: 'utf8', stdio: 'inherit' }); - } - - console.log('Finished publishing packages'); -} - -main(); diff --git a/scripts/utils/make-dist-package-json.cjs b/scripts/utils/make-dist-package-json.cjs index 4d6634ea..7c24f56e 100644 --- a/scripts/utils/make-dist-package-json.cjs +++ b/scripts/utils/make-dist-package-json.cjs @@ -12,14 +12,6 @@ processExportMap(pkgJson.exports); for (const key of ['types', 'main', 'module']) { if (typeof pkgJson[key] === 'string') pkgJson[key] = pkgJson[key].replace(/^(\.\/)?dist\//, './'); } -// Fix bin paths if present -if (pkgJson.bin) { - for (const key in pkgJson.bin) { - if (typeof pkgJson.bin[key] === 'string') { - pkgJson.bin[key] = pkgJson.bin[key].replace(/^(\.\/)?dist\//, './'); - } - } -} delete pkgJson.devDependencies; delete pkgJson.scripts.prepack; From d0e73d9ee0371727d6842533ae84030da198bec7 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 27 Aug 2026 19:00:10 +0000 Subject: [PATCH 003/232] seal --- .dockerignore | 59 - .gitignore | 2 - .prettierignore | 3 +- README.md | 9 - eslint.config.mjs | 2 +- packages/mcp-server/Dockerfile | 78 - packages/mcp-server/README.md | 101 - packages/mcp-server/build | 56 - packages/mcp-server/jest.config.ts | 17 - packages/mcp-server/manifest.json | 47 - packages/mcp-server/package.json | 96 - .../mcp-server/scripts/copy-bundle-files.cjs | 36 - .../scripts/postprocess-dist-package-json.cjs | 12 - packages/mcp-server/src/auth.ts | 42 - packages/mcp-server/src/code-tool-paths.cts | 5 - packages/mcp-server/src/code-tool-types.ts | 17 - packages/mcp-server/src/code-tool-worker.ts | 320 -- packages/mcp-server/src/code-tool.ts | 315 -- packages/mcp-server/src/docs-search-tool.ts | 79 - packages/mcp-server/src/http.ts | 227 - packages/mcp-server/src/index.ts | 67 - packages/mcp-server/src/instructions.ts | 57 - packages/mcp-server/src/local-docs-search.ts | 2661 ----------- packages/mcp-server/src/logger.ts | 28 - packages/mcp-server/src/methods.ts | 332 -- packages/mcp-server/src/options.ts | 185 - packages/mcp-server/src/server.ts | 208 - packages/mcp-server/src/stdio.ts | 17 - packages/mcp-server/src/types.ts | 126 - packages/mcp-server/src/util.ts | 25 - packages/mcp-server/tests/options.test.ts | 32 - packages/mcp-server/tsc-multi.json | 7 - packages/mcp-server/tsconfig.build.json | 18 - packages/mcp-server/tsconfig.dist-src.json | 11 - packages/mcp-server/tsconfig.json | 36 - packages/mcp-server/yarn.lock | 4169 ----------------- scripts/build | 6 - scripts/build-all | 5 - scripts/publish-packages.ts | 102 - scripts/utils/make-dist-package-json.cjs | 8 - 40 files changed, 2 insertions(+), 9621 deletions(-) delete mode 100644 .dockerignore delete mode 100644 packages/mcp-server/Dockerfile delete mode 100644 packages/mcp-server/README.md delete mode 100644 packages/mcp-server/build delete mode 100644 packages/mcp-server/jest.config.ts delete mode 100644 packages/mcp-server/manifest.json delete mode 100644 packages/mcp-server/package.json delete mode 100644 packages/mcp-server/scripts/copy-bundle-files.cjs delete mode 100644 packages/mcp-server/scripts/postprocess-dist-package-json.cjs delete mode 100644 packages/mcp-server/src/auth.ts delete mode 100644 packages/mcp-server/src/code-tool-paths.cts delete mode 100644 packages/mcp-server/src/code-tool-types.ts delete mode 100644 packages/mcp-server/src/code-tool-worker.ts delete mode 100644 packages/mcp-server/src/code-tool.ts delete mode 100644 packages/mcp-server/src/docs-search-tool.ts delete mode 100644 packages/mcp-server/src/http.ts delete mode 100644 packages/mcp-server/src/index.ts delete mode 100644 packages/mcp-server/src/instructions.ts delete mode 100644 packages/mcp-server/src/local-docs-search.ts delete mode 100644 packages/mcp-server/src/logger.ts delete mode 100644 packages/mcp-server/src/methods.ts delete mode 100644 packages/mcp-server/src/options.ts delete mode 100644 packages/mcp-server/src/server.ts delete mode 100644 packages/mcp-server/src/stdio.ts delete mode 100644 packages/mcp-server/src/types.ts delete mode 100644 packages/mcp-server/src/util.ts delete mode 100644 packages/mcp-server/tests/options.test.ts delete mode 100644 packages/mcp-server/tsc-multi.json delete mode 100644 packages/mcp-server/tsconfig.build.json delete mode 100644 packages/mcp-server/tsconfig.dist-src.json delete mode 100644 packages/mcp-server/tsconfig.json delete mode 100644 packages/mcp-server/yarn.lock delete mode 100755 scripts/build-all delete mode 100644 scripts/publish-packages.ts diff --git a/.dockerignore b/.dockerignore deleted file mode 100644 index 12ff1e64..00000000 --- a/.dockerignore +++ /dev/null @@ -1,59 +0,0 @@ -# Dependencies -node_modules/ -**/node_modules/ - -# Build outputs -dist/ -**/dist/ - -# Git -.git/ -.gitignore - -# CI/CD -.github/ -.gitlab-ci.yml -.travis.yml - -# IDE -.vscode/ -.idea/ -*.swp -*.swo -*~ - -# OS -.DS_Store -Thumbs.db - -# Testing -test/ -tests/ -__tests__/ -*.test.js -*.spec.js -coverage/ -.nyc_output/ - -# Logs -*.log -npm-debug.log* -yarn-debug.log* -yarn-error.log* - -# Environment -.env -.env.* - -# Temporary files -*.tmp -*.temp -.cache/ - -# Examples and scripts -examples/ -bin/ - -# Other packages (we only need mcp-server) -packages/*/ -!packages/mcp-server/ diff --git a/.gitignore b/.gitignore index ae4aa20e..9487e48a 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,4 @@ dist-deno /*.tgz .idea/ .eslintcache -dist-bundle -*.mcpb oidc diff --git a/.prettierignore b/.prettierignore index 36afd3b3..3548c5af 100644 --- a/.prettierignore +++ b/.prettierignore @@ -2,7 +2,6 @@ CHANGELOG.md /ecosystem-tests/*/** /node_modules /deno -/packages/mcp-server/manifest.json # don't format tsc output, will break source maps -dist +/dist diff --git a/README.md b/README.md index edfa7cc5..503becae 100644 --- a/README.md +++ b/README.md @@ -8,15 +8,6 @@ The REST API documentation can be found on [docs.context.dev](https://docs.conte It is generated with [Stainless](https://www.stainless.com/). -## MCP Server - -Use the Context Dev MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application. - -[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0) -[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D) - -> Note: You may need to set environment variables in your MCP client. - ## Installation ```sh diff --git a/eslint.config.mjs b/eslint.config.mjs index 18b8b5ae..2712a3e0 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -31,7 +31,7 @@ export default tseslint.config( }, }, { - files: ['tests/**', 'examples/**', 'packages/**'], + files: ['tests/**', 'examples/**'], rules: { 'no-restricted-imports': 'off', }, diff --git a/packages/mcp-server/Dockerfile b/packages/mcp-server/Dockerfile deleted file mode 100644 index a3140e2f..00000000 --- a/packages/mcp-server/Dockerfile +++ /dev/null @@ -1,78 +0,0 @@ -# Dockerfile for Context Dev MCP Server -# -# This Dockerfile builds a Docker image for the MCP Server. -# -# To build the image locally: -# docker build -f packages/mcp-server/Dockerfile -t context.dev-mcp:local . -# -# To run the image: -# docker run -i context.dev-mcp:local [OPTIONS] -# -# Common options: -# --tool= Include specific tools -# --resource= Include tools for specific resources -# --operation=read|write Filter by operation type -# --client= Set client compatibility (e.g., claude, cursor) -# --transport= Set transport type (stdio or http) -# -# For a full list of options: -# docker run -i context.dev-mcp:local --help -# -# Note: The MCP server uses stdio transport by default. Docker's -i flag -# enables interactive mode, allowing the container to communicate over stdin/stdout. - -# Build stage -FROM node:24-alpine AS builder - -# Install bash for build script -RUN apk add --no-cache bash openssl - -# Set working directory -WORKDIR /build - -# Copy entire repository -COPY . . - -# Install all dependencies and build everything -RUN yarn install --frozen-lockfile && \ - yarn build && \ - # Remove the symlink to the SDK so it doesn't interfere with the explicit COPY below - rm -Rf packages/mcp-server/node_modules/context.dev - -FROM denoland/deno:alpine-2.7.1 - -# Install node and npm -RUN apk add --no-cache nodejs npm - -ENV LD_LIBRARY_PATH=/usr/lib:/usr/local/lib - -# Add non-root user -RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001 - -# Set working directory -WORKDIR /app - -# Copy the built mcp-server dist directory -COPY --from=builder /build/packages/mcp-server/dist ./ - -# Copy node_modules from mcp-server (includes all production deps) -COPY --from=builder /build/packages/mcp-server/node_modules ./node_modules - -# Copy the built context.dev into node_modules -COPY --from=builder /build/dist ./node_modules/context.dev - -# Change ownership to nodejs user -RUN chown -R nodejs:nodejs /app -RUN chown -R nodejs:nodejs /deno-dir - -# Switch to non-root user -USER nodejs - -# The MCP server uses stdio transport by default -# No exposed ports needed for stdio communication - -# Set the entrypoint to the MCP server -ENTRYPOINT ["node", "index.js"] - -# Allow passing arguments to the MCP server -CMD [] diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.md deleted file mode 100644 index e1b2506f..00000000 --- a/packages/mcp-server/README.md +++ /dev/null @@ -1,101 +0,0 @@ -# Context Dev TypeScript MCP Server - -It is generated with [Stainless](https://www.stainless.com/). - -## Installation - -### Direct invocation - -You can run the MCP Server directly via `npx`: - -```sh -export CONTEXT_DEV_API_KEY="My API Key" -npx -y context.dev-mcp@latest -``` - -### Via MCP Client - -There is a partial list of existing clients at [modelcontextprotocol.io](https://modelcontextprotocol.io/clients). If you already -have a client, consult their documentation to install the MCP server. - -For clients with a configuration JSON, it might look something like this: - -```json -{ - "mcpServers": { - "context_dev_api": { - "command": "npx", - "args": ["-y", "context.dev-mcp"], - "env": { - "CONTEXT_DEV_API_KEY": "My API Key" - } - } - } -} -``` - -### Cursor - -If you use Cursor, you can install the MCP server by using the button below. You will need to set your environment variables -in Cursor's `mcp.json`, which can be found in Cursor Settings > Tools & MCP > New MCP Server. - -[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0) - -### VS Code - -If you use MCP, you can install the MCP server by clicking the link below. You will need to set your environment variables -in VS Code's `mcp.json`, which can be found via Command Palette > MCP: Open User Configuration. - -[Open VS Code](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D) - -### Claude Code - -If you use Claude Code, you can install the MCP server by running the command below in your terminal. You will need to set your -environment variables in Claude Code's `.claude.json`, which can be found in your home directory. - -``` -claude mcp add context.dev_mcp_api --env CONTEXT_DEV_API_KEY="My API Key" -- npx -y context.dev-mcp -``` - -## Code Mode - -This MCP server is built on the "Code Mode" tool scheme. In this MCP Server, -your agent will write code against the TypeScript SDK, which will then be executed in an -isolated sandbox. To accomplish this, the server will expose two tools to your agent: - -- The first tool is a docs search tool, which can be used to generically query for - documentation about your API/SDK. - -- The second tool is a code tool, where the agent can write code against the TypeScript SDK. - The code will be executed in a sandbox environment without web or filesystem access. Then, - anything the code returns or prints will be returned to the agent as the result of the - tool call. - -Using this scheme, agents are capable of performing very complex tasks deterministically -and repeatably. - -## Running remotely - -Launching the client with `--transport=http` launches the server as a remote server using Streamable HTTP transport. The `--port` setting can choose the port it will run on, and the `--socket` setting allows it to run on a Unix socket. - -Authorization can be provided via the `Authorization` header using the Bearer scheme. - -Additionally, authorization can be provided via the following headers: -| Header | Equivalent client option | Security scheme | -| ----------------------- | ------------------------ | --------------- | -| `x-context-dev-api-key` | `apiKey` | bearerAuth | - -A configuration JSON for this server might look like this, assuming the server is hosted at `http://localhost:3000`: - -```json -{ - "mcpServers": { - "context_dev_api": { - "url": "http://localhost:3000", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` diff --git a/packages/mcp-server/build b/packages/mcp-server/build deleted file mode 100644 index 7772183c..00000000 --- a/packages/mcp-server/build +++ /dev/null @@ -1,56 +0,0 @@ -#!/usr/bin/env bash -set -exuo pipefail - -rm -rf dist; mkdir dist - -# Copy src to dist/src and build from dist/src into dist, so that -# the source map for index.js.map will refer to ./src/index.ts etc -cp -rp src README.md dist - -for file in LICENSE; do - if [ -e "../../${file}" ]; then cp "../../${file}" dist; fi -done - -for file in CHANGELOG.md; do - if [ -e "${file}" ]; then cp "${file}" dist; fi -done - -# this converts the export map paths for the dist directory -# and does a few other minor things -PKG_JSON_PATH=../../packages/mcp-server/package.json node ../../scripts/utils/make-dist-package-json.cjs > dist/package.json - -# updates the `context.dev` dependency to point to NPM -node scripts/postprocess-dist-package-json.cjs - -# build to .js/.mjs/.d.ts files -./node_modules/.bin/tsc-multi - -cp tsconfig.dist-src.json dist/src/tsconfig.json - -chmod +x dist/index.js - -DIST_PATH=./dist PKG_IMPORT_PATH=context.dev-mcp/ node ../../scripts/utils/postprocess-files.cjs - -# mcp bundle -rm -rf dist-bundle context_dev_api.mcpb; mkdir dist-bundle - -# copy package.json -PKG_JSON_PATH=../../packages/mcp-server/package.json node ../../scripts/utils/make-dist-package-json.cjs > dist-bundle/package.json - -# copy files -node scripts/copy-bundle-files.cjs - -# install runtime deps -cd dist-bundle -npm install -cd .. - -# pack bundle -cp manifest.json dist-bundle - -npx mcpb pack dist-bundle context_dev_api.mcpb - -npx mcpb sign context_dev_api.mcpb --self-signed - -# clean up -rm -rf dist-bundle diff --git a/packages/mcp-server/jest.config.ts b/packages/mcp-server/jest.config.ts deleted file mode 100644 index 6935ead2..00000000 --- a/packages/mcp-server/jest.config.ts +++ /dev/null @@ -1,17 +0,0 @@ -import type { JestConfigWithTsJest } from 'ts-jest'; - -const config: JestConfigWithTsJest = { - preset: 'ts-jest/presets/default-esm', - testEnvironment: 'node', - transform: { - '^.+\\.(t|j)sx?$': ['@swc/jest', { sourceMaps: 'inline' }], - }, - moduleNameMapper: { - '^context.dev-mcp$': '/src/index.ts', - '^context.dev-mcp/(.*)$': '/src/$1', - }, - modulePathIgnorePatterns: ['/dist/'], - testPathIgnorePatterns: ['scripts'], -}; - -export default config; diff --git a/packages/mcp-server/manifest.json b/packages/mcp-server/manifest.json deleted file mode 100644 index a922fa45..00000000 --- a/packages/mcp-server/manifest.json +++ /dev/null @@ -1,47 +0,0 @@ -{ - "dxt_version": "0.2", - "name": "context.dev-mcp", - "version": "2.14.0", - "description": "The official MCP Server for the Context Dev API", - "author": { - "name": "Context Dev", - "email": "hello@context.dev" - }, - "repository": { - "type": "git", - "url": "git+https://github.com/context-dot-dev/context-typescript-sdk.git" - }, - "homepage": "https://github.com/context-dot-dev/context-typescript-sdk/tree/main/packages/mcp-server#readme", - "documentation": "https://docs.context.dev/", - "server": { - "type": "node", - "entry_point": "index.js", - "mcp_config": { - "command": "node", - "args": [ - "${__dirname}/index.js" - ], - "env": { - "CONTEXT_DEV_API_KEY": "${user_config.CONTEXT_DEV_API_KEY}" - } - } - }, - "user_config": { - "CONTEXT_DEV_API_KEY": { - "title": "api_key", - "description": "", - "required": true, - "type": "string" - } - }, - "tools": [], - "tools_generated": true, - "compatibility": { - "runtimes": { - "node": ">=18.0.0" - } - }, - "keywords": [ - "api" - ] -} diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json deleted file mode 100644 index 25a509b8..00000000 --- a/packages/mcp-server/package.json +++ /dev/null @@ -1,96 +0,0 @@ -{ - "name": "context.dev-mcp", - "version": "2.14.0", - "description": "The official MCP Server for the Context Dev API", - "author": "Context Dev ", - "types": "dist/index.d.ts", - "main": "dist/index.js", - "type": "commonjs", - "repository": { - "type": "git", - "url": "git+https://github.com/context-dot-dev/context-typescript-sdk.git", - "directory": "packages/mcp-server" - }, - "homepage": "https://github.com/context-dot-dev/context-typescript-sdk/tree/main/packages/mcp-server#readme", - "license": "Apache-2.0", - "packageManager": "yarn@1.22.22", - "private": false, - "publishConfig": { - "access": "public" - }, - "scripts": { - "test": "jest", - "build": "bash ./build", - "prepack": "echo 'to pack, run yarn build && (cd dist; yarn pack)' && exit 1", - "prepublishOnly": "echo 'to publish, run yarn build && (cd dist; yarn publish)' && exit 1", - "format": "prettier --write --cache --cache-strategy metadata . !dist", - "prepare": "npm run build", - "tsn": "ts-node -r tsconfig-paths/register", - "lint": "eslint .", - "fix": "eslint --fix ." - }, - "dependencies": { - "context.dev": "link:../../dist/", - "ajv": "^8.18.0", - "@cloudflare/cabidela": "^0.2.4", - "@hono/node-server": "^1.19.10", - "@modelcontextprotocol/sdk": "^1.27.1", - "hono": "^4.12.4", - "@valtown/deno-http-worker": "^0.0.21", - "cookie-parser": "^1.4.6", - "cors": "^2.8.5", - "express": "^5.1.0", - "fuse.js": "^7.1.0", - "minisearch": "^7.2.0", - "jq-web": "https://github.com/stainless-api/jq-web/releases/download/v0.8.8/jq-web.tar.gz", - "pino": "^10.3.1", - "pino-http": "^11.0.0", - "pino-pretty": "^13.1.3", - "qs": "^6.14.1", - "typescript": "5.8.3", - "yargs": "^17.7.2", - "zod": "^3.25.20", - "zod-to-json-schema": "^3.24.5", - "zod-validation-error": "^4.0.1" - }, - "bin": { - "mcp-server": "dist/index.js" - }, - "devDependencies": { - "@anthropic-ai/mcpb": "^2.1.2", - "@types/cookie-parser": "^1.4.10", - "@types/cors": "^2.8.19", - "@types/express": "^5.0.3", - "@types/jest": "^29.4.0", - "@types/qs": "^6.14.0", - "@types/yargs": "^17.0.8", - "@typescript-eslint/eslint-plugin": "8.31.1", - "@typescript-eslint/parser": "8.31.1", - "eslint": "^9.39.1", - "eslint-plugin-prettier": "^5.4.1", - "eslint-plugin-unused-imports": "^4.1.4", - "jest": "^29.4.0", - "prettier": "^3.0.0", - "ts-jest": "^29.1.0", - "ts-morph": "^19.0.0", - "ts-node": "^10.5.0", - "tsc-multi": "https://github.com/stainless-api/tsc-multi/releases/download/v1.1.11/tsc-multi.tgz", - "tsconfig-paths": "^4.0.0" - }, - "imports": { - "context.dev-mcp": ".", - "context.dev-mcp/*": "./src/*" - }, - "exports": { - ".": { - "require": "./dist/index.js", - "default": "./dist/index.mjs" - }, - "./*.mjs": "./dist/*.mjs", - "./*.js": "./dist/*.js", - "./*": { - "require": "./dist/*.js", - "default": "./dist/*.mjs" - } - } -} diff --git a/packages/mcp-server/scripts/copy-bundle-files.cjs b/packages/mcp-server/scripts/copy-bundle-files.cjs deleted file mode 100644 index 5681886c..00000000 --- a/packages/mcp-server/scripts/copy-bundle-files.cjs +++ /dev/null @@ -1,36 +0,0 @@ -const fs = require('fs'); -const path = require('path'); -const pkgJson = require('../dist-bundle/package.json'); - -const distDir = path.resolve(__dirname, '..', 'dist'); -const distBundleDir = path.resolve(__dirname, '..', 'dist-bundle'); -const distBundlePkgJson = path.join(distBundleDir, 'package.json'); - -async function* walk(dir) { - for await (const d of await fs.promises.opendir(dir)) { - const entry = path.join(dir, d.name); - if (d.isDirectory()) yield* walk(entry); - else if (d.isFile()) yield entry; - } -} - -async function copyFiles() { - // copy runtime files - for await (const file of walk(distDir)) { - if (!/[cm]?js$/.test(file)) continue; - const dest = path.join(distBundleDir, path.relative(distDir, file)); - await fs.promises.mkdir(path.dirname(dest), { recursive: true }); - await fs.promises.copyFile(file, dest); - } - - // replace package.json reference with local reference - for (const dep in pkgJson.dependencies) { - if (dep === 'context.dev') { - pkgJson.dependencies[dep] = 'file:../../../dist/'; - } - } - - await fs.promises.writeFile(distBundlePkgJson, JSON.stringify(pkgJson, null, 2)); -} - -copyFiles(); diff --git a/packages/mcp-server/scripts/postprocess-dist-package-json.cjs b/packages/mcp-server/scripts/postprocess-dist-package-json.cjs deleted file mode 100644 index da147f99..00000000 --- a/packages/mcp-server/scripts/postprocess-dist-package-json.cjs +++ /dev/null @@ -1,12 +0,0 @@ -const fs = require('fs'); -const pkgJson = require('../dist/package.json'); -const parentPkgJson = require('../../../package.json'); - -for (const dep in pkgJson.dependencies) { - // ensure we point to NPM instead of a local directory - if (dep === 'context.dev') { - pkgJson.dependencies[dep] = '^' + parentPkgJson.version; - } -} - -fs.writeFileSync('dist/package.json', JSON.stringify(pkgJson, null, 2)); diff --git a/packages/mcp-server/src/auth.ts b/packages/mcp-server/src/auth.ts deleted file mode 100644 index 935a1b16..00000000 --- a/packages/mcp-server/src/auth.ts +++ /dev/null @@ -1,42 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { IncomingMessage } from 'node:http'; -import { ClientOptions } from 'context.dev'; -import { McpOptions } from './options'; - -export const parseClientAuthHeaders = (req: IncomingMessage, required?: boolean): Partial => { - if (req.headers.authorization) { - const scheme = req.headers.authorization.split(' ')[0]!; - const value = req.headers.authorization.slice(scheme.length + 1); - switch (scheme) { - case 'Bearer': - return { apiKey: req.headers.authorization.slice('Bearer '.length) }; - default: - throw new Error( - 'Unsupported authorization scheme. Expected the "Authorization" header to be a supported scheme (Bearer).', - ); - } - } else if (required) { - throw new Error('Missing required Authorization header; see WWW-Authenticate header for details.'); - } - - const apiKey = - Array.isArray(req.headers['x-context-dev-api-key']) ? - req.headers['x-context-dev-api-key'][0] - : req.headers['x-context-dev-api-key']; - return { apiKey }; -}; - -export const getStainlessApiKey = (req: IncomingMessage, mcpOptions: McpOptions): string | undefined => { - // Try to get the key from the x-stainless-api-key header - const headerKey = - Array.isArray(req.headers['x-stainless-api-key']) ? - req.headers['x-stainless-api-key'][0] - : req.headers['x-stainless-api-key']; - if (headerKey && typeof headerKey === 'string') { - return headerKey; - } - - // Fall back to value set in the mcpOptions (e.g. from environment variable), if provided - return mcpOptions.stainlessApiKey; -}; diff --git a/packages/mcp-server/src/code-tool-paths.cts b/packages/mcp-server/src/code-tool-paths.cts deleted file mode 100644 index 78263e45..00000000 --- a/packages/mcp-server/src/code-tool-paths.cts +++ /dev/null @@ -1,5 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -export function getWorkerPath(): string { - return require.resolve('./code-tool-worker.mjs'); -} diff --git a/packages/mcp-server/src/code-tool-types.ts b/packages/mcp-server/src/code-tool-types.ts deleted file mode 100644 index 21108d89..00000000 --- a/packages/mcp-server/src/code-tool-types.ts +++ /dev/null @@ -1,17 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { ClientOptions } from 'context.dev'; - -export type WorkerInput = { - project_name: string; - code: string; - client_opts: ClientOptions; - intent?: string | undefined; -}; - -export type WorkerOutput = { - is_error: boolean; - result: unknown | null; - log_lines: string[]; - err_lines: string[]; -}; diff --git a/packages/mcp-server/src/code-tool-worker.ts b/packages/mcp-server/src/code-tool-worker.ts deleted file mode 100644 index c66589ea..00000000 --- a/packages/mcp-server/src/code-tool-worker.ts +++ /dev/null @@ -1,320 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import path from 'node:path'; -import util from 'node:util'; -import Fuse from 'fuse.js'; -import ts from 'typescript'; -import { WorkerOutput } from './code-tool-types'; -import { ContextDev, ClientOptions } from 'context.dev'; - -async function tseval(code: string) { - return import('data:application/typescript;charset=utf-8;base64,' + Buffer.from(code).toString('base64')); -} - -function getRunFunctionSource(code: string): { - type: 'declaration' | 'expression'; - client: string | undefined; - code: string; -} | null { - const sourceFile = ts.createSourceFile('code.ts', code, ts.ScriptTarget.Latest, true); - const printer = ts.createPrinter(); - - for (const statement of sourceFile.statements) { - // Check for top-level function declarations - if (ts.isFunctionDeclaration(statement)) { - if (statement.name?.text === 'run') { - return { - type: 'declaration', - client: statement.parameters[0]?.name.getText(), - code: printer.printNode(ts.EmitHint.Unspecified, statement.body!, sourceFile), - }; - } - } - - // Check for variable declarations: const run = () => {} or const run = function() {} - if (ts.isVariableStatement(statement)) { - for (const declaration of statement.declarationList.declarations) { - if ( - ts.isIdentifier(declaration.name) && - declaration.name.text === 'run' && - // Check if it's initialized with a function - declaration.initializer && - (ts.isFunctionExpression(declaration.initializer) || ts.isArrowFunction(declaration.initializer)) - ) { - return { - type: 'expression', - client: declaration.initializer.parameters[0]?.name.getText(), - code: printer.printNode(ts.EmitHint.Unspecified, declaration.initializer, sourceFile), - }; - } - } - } - } - - return null; -} - -function getTSDiagnostics(code: string): string[] { - const functionSource = getRunFunctionSource(code)!; - const codeWithImport = [ - 'import { ContextDev } from "context.dev";', - functionSource.type === 'declaration' ? - `async function run(${functionSource.client}: ContextDev)` - : `const run: (${functionSource.client}: ContextDev) => Promise =`, - functionSource.code, - ].join('\n'); - const sourcePath = path.resolve('code.ts'); - const ast = ts.createSourceFile(sourcePath, codeWithImport, ts.ScriptTarget.Latest, true); - const options = ts.getDefaultCompilerOptions(); - options.target = ts.ScriptTarget.Latest; - options.module = ts.ModuleKind.NodeNext; - options.moduleResolution = ts.ModuleResolutionKind.NodeNext; - const host = ts.createCompilerHost(options, true); - const newHost: typeof host = { - ...host, - getSourceFile: (...args) => { - if (path.resolve(args[0]) === sourcePath) { - return ast; - } - return host.getSourceFile(...args); - }, - readFile: (...args) => { - if (path.resolve(args[0]) === sourcePath) { - return codeWithImport; - } - return host.readFile(...args); - }, - fileExists: (...args) => { - if (path.resolve(args[0]) === sourcePath) { - return true; - } - return host.fileExists(...args); - }, - }; - const program = ts.createProgram({ - options, - rootNames: [sourcePath], - host: newHost, - }); - const diagnostics = ts.getPreEmitDiagnostics(program, ast); - return diagnostics.map((d) => { - const message = ts.flattenDiagnosticMessageText(d.messageText, '\n'); - if (!d.file || !d.start) return `- ${message}`; - const { line: lineNumber } = ts.getLineAndCharacterOfPosition(d.file, d.start); - const line = codeWithImport.split('\n').at(lineNumber)?.trim(); - return line ? `- ${message}\n ${line}` : `- ${message}`; - }); -} - -const fuse = new Fuse( - [ - 'client.parse.handle', - 'client.web.extract', - 'client.web.extractCompetitors', - 'client.web.extractFonts', - 'client.web.extractStyleguide', - 'client.web.screenshot', - 'client.web.search', - 'client.web.webCrawlMd', - 'client.web.webScrapeHTML', - 'client.web.webScrapeImages', - 'client.web.webScrapeMd', - 'client.web.webScrapeSitemap', - 'client.ai.extractProduct', - 'client.ai.extractProducts', - 'client.brand.retrieve', - 'client.brand.retrieveSimplified', - 'client.brand.search', - 'client.industry.retrieveNaics', - 'client.industry.retrieveSic', - 'client.utility.prefetch', - 'client.monitors.create', - 'client.monitors.delete', - 'client.monitors.getCreditUsage', - 'client.monitors.getLimits', - 'client.monitors.list', - 'client.monitors.listAccountChanges', - 'client.monitors.listAccountRuns', - 'client.monitors.listChanges', - 'client.monitors.listRuns', - 'client.monitors.retrieve', - 'client.monitors.retrieveChange', - 'client.monitors.run', - 'client.monitors.update', - 'client.batch.cancel', - 'client.batch.delete', - 'client.batch.getResults', - 'client.batch.list', - 'client.batch.retrieve', - 'client.batch.submit', - 'client.people.enrich', - 'client.news.search', - ], - { threshold: 1, shouldSort: true }, -); - -function getMethodSuggestions(fullyQualifiedMethodName: string): string[] { - return fuse - .search(fullyQualifiedMethodName) - .map(({ item }) => item) - .slice(0, 5); -} - -const proxyToObj = new WeakMap(); -const objToProxy = new WeakMap(); - -type ClientProxyConfig = { - path: string[]; - isBelievedBad?: boolean; -}; - -function makeSdkProxy(obj: T, { path, isBelievedBad = false }: ClientProxyConfig): T { - let proxy: T = objToProxy.get(obj); - - if (!proxy) { - proxy = new Proxy(obj, { - get(target, prop, receiver) { - const propPath = [...path, String(prop)]; - const value = Reflect.get(target, prop, receiver); - - if (isBelievedBad || (!(prop in target) && value === undefined)) { - // If we're accessing a path that doesn't exist, it will probably eventually error. - // Let's proxy it and mark it bad so that we can control the error message. - // We proxy an empty class so that an invocation or construction attempt is possible. - return makeSdkProxy(class {}, { path: propPath, isBelievedBad: true }); - } - - if (value !== null && (typeof value === 'object' || typeof value === 'function')) { - return makeSdkProxy(value, { path: propPath, isBelievedBad }); - } - - return value; - }, - - apply(target, thisArg, args) { - if (isBelievedBad || typeof target !== 'function') { - const fullyQualifiedMethodName = path.join('.'); - const suggestions = getMethodSuggestions(fullyQualifiedMethodName); - throw new Error( - `${fullyQualifiedMethodName} is not a function. Did you mean: ${suggestions.join(', ')}`, - ); - } - - return Reflect.apply(target, proxyToObj.get(thisArg) ?? thisArg, args); - }, - - construct(target, args, newTarget) { - if (isBelievedBad || typeof target !== 'function') { - const fullyQualifiedMethodName = path.join('.'); - const suggestions = getMethodSuggestions(fullyQualifiedMethodName); - throw new Error( - `${fullyQualifiedMethodName} is not a constructor. Did you mean: ${suggestions.join(', ')}`, - ); - } - - return Reflect.construct(target, args, newTarget); - }, - }); - - objToProxy.set(obj, proxy); - proxyToObj.set(proxy, obj); - } - - return proxy; -} - -function parseError(code: string, error: unknown): string | undefined { - if (!(error instanceof Error)) return; - const cause = error.cause instanceof Error ? `: ${error.cause.message}` : ''; - const message = error.name ? `${error.name}: ${error.message}${cause}` : `${error.message}${cause}`; - try { - // Deno uses V8; the first ":LINE:COLUMN" is the top of stack. - const lineNumber = error.stack?.match(/:([0-9]+):[0-9]+/)?.[1]; - // -1 for the zero-based indexing - const line = - lineNumber && - code - .split('\n') - .at(parseInt(lineNumber, 10) - 1) - ?.trim(); - return line ? `${message}\n at line ${lineNumber}\n ${line}` : message; - } catch { - return message; - } -} - -const fetch = async (req: Request): Promise => { - const { opts, code } = (await req.json()) as { opts: ClientOptions; code: string }; - - const runFunctionSource = code ? getRunFunctionSource(code) : null; - if (!runFunctionSource) { - const message = - code ? - 'The code is missing a top-level `run` function.' - : 'The code argument is missing. Provide one containing a top-level `run` function.'; - return Response.json( - { - is_error: true, - result: `${message} Write code within this template:\n\n\`\`\`\nasync function run(client) {\n // Fill this out\n}\n\`\`\``, - log_lines: [], - err_lines: [], - } satisfies WorkerOutput, - { status: 400, statusText: 'Code execution error' }, - ); - } - - const diagnostics = getTSDiagnostics(code); - if (diagnostics.length > 0) { - return Response.json( - { - is_error: true, - result: `The code contains TypeScript diagnostics:\n${diagnostics.join('\n')}`, - log_lines: [], - err_lines: [], - } satisfies WorkerOutput, - { status: 400, statusText: 'Code execution error' }, - ); - } - - const client = new ContextDev({ - ...opts, - }); - - const log_lines: string[] = []; - const err_lines: string[] = []; - const originalConsole = globalThis.console; - globalThis.console = { - ...originalConsole, - log: (...args: unknown[]) => { - log_lines.push(util.format(...args)); - }, - error: (...args: unknown[]) => { - err_lines.push(util.format(...args)); - }, - }; - try { - let run_ = async (client: any) => {}; - run_ = (await tseval(`${code}\nexport default run;`)).default; - const result = await run_(makeSdkProxy(client, { path: ['client'] })); - return Response.json({ - is_error: false, - result, - log_lines, - err_lines, - } satisfies WorkerOutput); - } catch (e) { - return Response.json( - { - is_error: true, - result: parseError(code, e), - log_lines, - err_lines, - } satisfies WorkerOutput, - { status: 400, statusText: 'Code execution error' }, - ); - } finally { - globalThis.console = originalConsole; - } -}; - -export default { fetch }; diff --git a/packages/mcp-server/src/code-tool.ts b/packages/mcp-server/src/code-tool.ts deleted file mode 100644 index d5cd7d59..00000000 --- a/packages/mcp-server/src/code-tool.ts +++ /dev/null @@ -1,315 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { ContentBlock, McpRequestContext, McpTool, Metadata, ToolCallResult, asErrorResult } from './types'; -import { Tool } from '@modelcontextprotocol/sdk/types.js'; -import { WorkerOutput } from './code-tool-types'; -import { getLogger } from './logger'; -import { SdkMethod } from './methods'; -import { McpCodeExecutionMode } from './options'; -import { ClientOptions } from 'context.dev'; - -const prompt = `Runs JavaScript code to interact with the Context Dev API. - -You are a skilled TypeScript programmer writing code to interface with the service. -Define an async function named "run" that takes a single parameter of an initialized SDK client and it will be run. -For example: - -\`\`\` -async function run(client) { - const brand = await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }); - - console.log(brand.cache_metadata); -} -\`\`\` - -You will be returned anything that your function returns, plus the results of any console.log statements. -Do not add try-catch blocks for single API calls. The tool will handle errors for you. -Do not add comments unless necessary for generating better code. -Code will run in a container, and cannot interact with the network outside of the given SDK client. -Variables will not persist between calls, so make sure to return or log any data you might need later. -Remember that you are writing TypeScript code, so you need to be careful with your types. -Always type dynamic key-value stores explicitly as Record instead of {}.`; - -/** - * A tool that runs code against a copy of the SDK. - * - * Instead of exposing every endpoint as its own tool, which uses up too many tokens for LLMs to use at once, - * we expose a single tool that can be used to search for endpoints by name, resource, operation, or tag, and then - * a generic endpoint that can be used to invoke any endpoint with the provided arguments. - * - * @param blockedMethods - The methods to block for code execution. Blocking is done by simple string - * matching, so it is not secure against obfuscation. For stronger security, block in the downstream API - * with limited API keys. - * @param codeExecutionMode - Whether to execute code in a local Deno environment or in a remote - * sandbox environment hosted by Stainless. - */ -export function codeTool({ - blockedMethods, - codeExecutionMode, -}: { - blockedMethods: SdkMethod[] | undefined; - codeExecutionMode: McpCodeExecutionMode; -}): McpTool { - const metadata: Metadata = { resource: 'all', operation: 'write', tags: [] }; - const tool: Tool = { - name: 'execute', - description: prompt, - inputSchema: { - type: 'object', - properties: { - code: { - type: 'string', - description: 'Code to execute.', - }, - intent: { - type: 'string', - description: 'Task you are trying to perform. Used for improving the service.', - }, - }, - required: ['code'], - }, - }; - - const logger = getLogger(); - - const handler = async ({ - reqContext, - args, - }: { - reqContext: McpRequestContext; - args: any; - }): Promise => { - const code = args.code as string; - // Do very basic blocking of code that includes forbidden method names. - // - // WARNING: This is not secure against obfuscation and other evasion methods. If - // stronger security blocks are required, then these should be enforced in the downstream - // API (e.g., by having users call the MCP server with API keys with limited permissions). - if (blockedMethods) { - const blockedMatches = blockedMethods.filter((method) => code.includes(method.fullyQualifiedName)); - if (blockedMatches.length > 0) { - return asErrorResult( - `The following methods have been blocked by the MCP server and cannot be used in code execution: ${blockedMatches - .map((m) => m.fullyQualifiedName) - .join(', ')}`, - ); - } - } - - let result: ToolCallResult; - const startTime = Date.now(); - - logger.debug('Executing code in local Deno environment'); - result = await localDenoHandler({ reqContext, args }); - - logger.info( - { - codeExecutionMode, - durationMs: Date.now() - startTime, - isError: result.isError, - contentRows: result.content?.length ?? 0, - }, - 'Got code tool execution result', - ); - return result; - }; - - return { metadata, tool, handler }; -} - -const localDenoHandler = async ({ - reqContext, - args, -}: { - reqContext: McpRequestContext; - args: unknown; -}): Promise => { - const fs = await import('node:fs'); - const path = await import('node:path'); - const url = await import('node:url'); - const { newDenoHTTPWorker } = await import('@valtown/deno-http-worker'); - const { getWorkerPath } = await import('./code-tool-paths.cjs'); - const workerPath = getWorkerPath(); - - const client = reqContext.client; - const baseURLHostname = new URL(client.baseURL).hostname; - const { code } = args as { code: string }; - - let denoPath: string; - - const packageRoot = path.resolve(path.dirname(workerPath), '..'); - const packageNodeModulesPath = path.resolve(packageRoot, 'node_modules'); - - // Check if deno is in PATH - const { execSync } = await import('node:child_process'); - try { - execSync('command -v deno', { stdio: 'ignore' }); - denoPath = 'deno'; - } catch { - try { - // Use deno binary in node_modules if it's found - const denoNodeModulesPath = path.resolve(packageNodeModulesPath, 'deno', 'bin.cjs'); - await fs.promises.access(denoNodeModulesPath, fs.constants.X_OK); - denoPath = denoNodeModulesPath; - } catch { - return asErrorResult( - 'Deno is required for code execution but was not found. ' + - 'Install it from https://deno.land or run: npm install deno', - ); - } - } - - const allowReadPaths = [ - 'code-tool-worker.mjs', - `${workerPath.replace(/([\/\\]node_modules)[\/\\].+$/, '$1')}/`, - packageRoot, - ]; - - // Follow symlinks in node_modules to allow read access to workspace-linked packages - try { - const sdkPkgName = 'context.dev'; - const sdkDir = path.resolve(packageNodeModulesPath, sdkPkgName); - const realSdkDir = fs.realpathSync(sdkDir); - if (realSdkDir !== sdkDir) { - allowReadPaths.push(realSdkDir); - } - } catch { - // Ignore if symlink resolution fails - } - - const allowRead = allowReadPaths.join(','); - - const worker = await newDenoHTTPWorker(url.pathToFileURL(workerPath), { - denoExecutable: denoPath, - runFlags: [ - `--node-modules-dir=manual`, - `--allow-read=${allowRead}`, - `--allow-net=${baseURLHostname}`, - // Allow environment variables because instantiating the client will try to read from them, - // even though they are not set. - '--allow-env', - ], - printOutput: true, - spawnOptions: { - cwd: path.dirname(workerPath), - // Merge any upstream client envs into the Deno subprocess environment, - // with the upstream env vars taking precedence. - env: { ...process.env, ...reqContext.upstreamClientEnvs }, - }, - }); - - try { - const resp = await new Promise((resolve, reject) => { - worker.addEventListener('exit', (exitCode) => { - reject(new Error(`Worker exited with code ${exitCode}`)); - }); - - // Strip null/undefined values so that the worker SDK client can fall back to - // reading from environment variables (including any upstreamClientEnvs). - const opts = { - ...(client.baseURL != null ? { baseURL: client.baseURL } : undefined), - ...(client.apiKey != null ? { apiKey: client.apiKey } : undefined), - defaultHeaders: { - 'X-Stainless-MCP': 'true', - }, - } satisfies Partial as ClientOptions; - - const req = worker.request( - 'http://localhost', - { - headers: { - 'content-type': 'application/json', - }, - method: 'POST', - }, - (resp) => { - const body: Uint8Array[] = []; - resp.on('error', (err) => { - reject(err); - }); - resp.on('data', (chunk) => { - body.push(chunk); - }); - resp.on('end', () => { - resolve( - new Response(Buffer.concat(body).toString(), { - status: resp.statusCode ?? 200, - headers: resp.headers as any, - }), - ); - }); - }, - ); - - const body = JSON.stringify({ - opts, - code, - }); - - req.write(body, (err) => { - if (err != null) { - reject(err); - } - }); - - req.end(); - }); - - if (resp.status === 200) { - const { result, log_lines, err_lines } = (await resp.json()) as WorkerOutput; - const returnOutput: ContentBlock | null = - result == null ? null : ( - { - type: 'text', - text: typeof result === 'string' ? result : JSON.stringify(result), - } - ); - const logOutput: ContentBlock | null = - log_lines.length === 0 ? - null - : { - type: 'text', - text: log_lines.join('\n'), - }; - const errOutput: ContentBlock | null = - err_lines.length === 0 ? - null - : { - type: 'text', - text: 'Error output:\n' + err_lines.join('\n'), - }; - return { - content: [returnOutput, logOutput, errOutput].filter((block) => block !== null), - }; - } else { - const { result, log_lines, err_lines } = (await resp.json()) as WorkerOutput; - const messageOutput: ContentBlock | null = - result == null ? null : ( - { - type: 'text', - text: typeof result === 'string' ? result : JSON.stringify(result), - } - ); - const logOutput: ContentBlock | null = - log_lines.length === 0 ? - null - : { - type: 'text', - text: log_lines.join('\n'), - }; - const errOutput: ContentBlock | null = - err_lines.length === 0 ? - null - : { - type: 'text', - text: 'Error output:\n' + err_lines.join('\n'), - }; - return { - content: [messageOutput, logOutput, errOutput].filter((block) => block !== null), - isError: true, - }; - } - } finally { - worker.terminate(); - } -}; diff --git a/packages/mcp-server/src/docs-search-tool.ts b/packages/mcp-server/src/docs-search-tool.ts deleted file mode 100644 index eafcd871..00000000 --- a/packages/mcp-server/src/docs-search-tool.ts +++ /dev/null @@ -1,79 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { Tool } from '@modelcontextprotocol/sdk/types.js'; -import { Metadata, McpRequestContext, asTextContentResult } from './types'; - -import type { LocalDocsSearch } from './local-docs-search'; - -export const metadata: Metadata = { - resource: 'all', - operation: 'read', - tags: [], - httpMethod: 'get', -}; - -export const tool: Tool = { - name: 'search_docs', - description: - 'Search SDK documentation to find methods, parameters, and usage examples for interacting with the API. Use this before writing code when you need to discover the right approach.', - inputSchema: { - type: 'object', - properties: { - query: { - type: 'string', - description: 'The query to search for.', - }, - language: { - type: 'string', - description: 'The language for the SDK to search for.', - enum: ['http', 'python', 'go', 'typescript', 'javascript', 'terraform', 'ruby', 'java', 'kotlin'], - }, - detail: { - type: 'string', - description: 'The amount of detail to return.', - enum: ['default', 'verbose'], - }, - }, - required: ['query', 'language'], - }, - annotations: { - readOnlyHint: true, - }, -}; - -let _localSearch: LocalDocsSearch | undefined; - -export function setLocalSearch(search: LocalDocsSearch): void { - _localSearch = search; -} - -async function searchLocal(args: Record): Promise { - if (!_localSearch) { - throw new Error('Local search not initialized'); - } - - const query = (args['query'] as string) ?? ''; - const language = (args['language'] as string) ?? 'typescript'; - const detail = (args['detail'] as string) ?? 'default'; - - return _localSearch.search({ - query, - language, - detail, - maxResults: 10, - }).results; -} - -export const handler = async ({ - reqContext, - args, -}: { - reqContext: McpRequestContext; - args: Record | undefined; -}) => { - const body = args ?? {}; - - return asTextContentResult(await searchLocal(body)); -}; - -export default { metadata, tool, handler }; diff --git a/packages/mcp-server/src/http.ts b/packages/mcp-server/src/http.ts deleted file mode 100644 index a8dfd8a9..00000000 --- a/packages/mcp-server/src/http.ts +++ /dev/null @@ -1,227 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp'; -import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; -import { ClientOptions } from 'context.dev'; -import express from 'express'; -import pino from 'pino'; -import pinoHttp from 'pino-http'; -import { getStainlessApiKey, parseClientAuthHeaders } from './auth'; -import { getLogger } from './logger'; -import { McpOptions } from './options'; -import { initMcpServer, newMcpServer } from './server'; - -const newServer = async ({ - clientOptions, - mcpOptions, - req, - res, -}: { - clientOptions: ClientOptions; - mcpOptions: McpOptions; - req: express.Request; - res: express.Response; -}): Promise => { - const stainlessApiKey = getStainlessApiKey(req, mcpOptions); - const customInstructionsPath = mcpOptions.customInstructionsPath; - const server = await newMcpServer({ stainlessApiKey, customInstructionsPath }); - - const authOptions = parseClientAuthHeaders(req, false); - - let upstreamClientEnvs: Record | undefined; - const clientEnvsHeader = req.headers['x-stainless-mcp-client-envs']; - if (typeof clientEnvsHeader === 'string') { - try { - const parsed = JSON.parse(clientEnvsHeader); - if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) { - upstreamClientEnvs = parsed; - } - } catch { - // Ignore malformed header - } - } - - // Parse x-stainless-mcp-client-permissions header to override permission options - // - // Note: Permissions are best-effort and intended to prevent clients from doing unexpected things; - // they're not a hard security boundary, so we allow arbitrary, client-driven overrides. - // - // See the Stainless MCP documentation for more details. - let effectiveMcpOptions = mcpOptions; - const clientPermissionsHeader = req.headers['x-stainless-mcp-client-permissions']; - if (typeof clientPermissionsHeader === 'string') { - try { - const parsed = JSON.parse(clientPermissionsHeader); - if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) { - effectiveMcpOptions = { - ...mcpOptions, - ...(typeof parsed.allow_http_gets === 'boolean' && { codeAllowHttpGets: parsed.allow_http_gets }), - ...(Array.isArray(parsed.allowed_methods) && { codeAllowedMethods: parsed.allowed_methods }), - ...(Array.isArray(parsed.blocked_methods) && { codeBlockedMethods: parsed.blocked_methods }), - }; - getLogger().info( - { clientPermissions: parsed }, - 'Overriding code execution permissions from x-stainless-mcp-client-permissions header', - ); - } - } catch (error) { - getLogger().warn({ error }, 'Failed to parse x-stainless-mcp-client-permissions header'); - } - } - - const mcpClientInfo = - typeof req.body?.params?.clientInfo?.name === 'string' ? - { name: req.body.params.clientInfo.name, version: String(req.body.params.clientInfo.version ?? '') } - : undefined; - - await initMcpServer({ - server: server, - mcpOptions: effectiveMcpOptions, - clientOptions: { - ...clientOptions, - ...authOptions, - }, - stainlessApiKey: stainlessApiKey, - upstreamClientEnvs, - mcpSessionId: (req as any).mcpSessionId, - mcpClientInfo, - }); - - if (mcpClientInfo) { - getLogger().info({ mcpSessionId: (req as any).mcpSessionId, mcpClientInfo }, 'MCP client connected'); - } - - return server; -}; - -const post = - (options: { clientOptions: ClientOptions; mcpOptions: McpOptions }) => - async (req: express.Request, res: express.Response) => { - const server = await newServer({ ...options, req, res }); - // If we return null, we already set the authorization error. - if (server === null) return; - const transport = new StreamableHTTPServerTransport(); - await server.connect(transport as any); - await transport.handleRequest(req, res, req.body); - }; - -const get = async (req: express.Request, res: express.Response) => { - res.status(405).json({ - jsonrpc: '2.0', - error: { - code: -32000, - message: 'Method not supported', - }, - }); -}; - -const del = async (req: express.Request, res: express.Response) => { - res.status(405).json({ - jsonrpc: '2.0', - error: { - code: -32000, - message: 'Method not supported', - }, - }); -}; - -const redactHeaders = (headers: Record) => { - const hiddenHeaders = /auth|cookie|key|token|x-stainless-mcp-client-envs/i; - const filtered = { ...headers }; - Object.keys(filtered).forEach((key) => { - if (hiddenHeaders.test(key)) { - filtered[key] = '[REDACTED]'; - } - }); - return filtered; -}; - -export const streamableHTTPApp = ({ - clientOptions = {}, - mcpOptions, -}: { - clientOptions?: ClientOptions; - mcpOptions: McpOptions; -}): express.Express => { - const app = express(); - app.set('query parser', 'extended'); - app.use(express.json()); - app.use((req: express.Request, res: express.Response, next: express.NextFunction) => { - const existing = req.headers['mcp-session-id']; - const sessionId = (Array.isArray(existing) ? existing[0] : existing) || crypto.randomUUID(); - (req as any).mcpSessionId = sessionId; - const origWriteHead = res.writeHead.bind(res); - res.writeHead = function (statusCode: number, ...rest: any[]) { - res.setHeader('mcp-session-id', sessionId); - return origWriteHead(statusCode, ...rest); - } as typeof res.writeHead; - next(); - }); - app.use( - pinoHttp({ - logger: getLogger(), - customProps: (req) => ({ - mcpSessionId: (req as any).mcpSessionId, - }), - customLogLevel: (req, res) => { - if (res.statusCode >= 500) { - return 'error'; - } else if (res.statusCode >= 400) { - return 'warn'; - } - return 'info'; - }, - customSuccessMessage: function (req, res) { - return `Request ${req.method} to ${req.url} completed with status ${res.statusCode}`; - }, - customErrorMessage: function (req, res, err) { - return `Request ${req.method} to ${req.url} errored with status ${res.statusCode}`; - }, - serializers: { - req: pino.stdSerializers.wrapRequestSerializer((req) => { - return { - ...req, - headers: redactHeaders(req.raw.headers), - }; - }), - res: pino.stdSerializers.wrapResponseSerializer((res) => { - return { - ...res, - headers: redactHeaders(res.headers), - }; - }), - }, - }), - ); - - app.get('/health', async (req: express.Request, res: express.Response) => { - res.status(200).send('OK'); - }); - app.get('/', get); - app.post('/', post({ clientOptions, mcpOptions })); - app.delete('/', del); - - return app; -}; - -export const launchStreamableHTTPServer = async ({ - mcpOptions, - port, -}: { - mcpOptions: McpOptions; - port: number | string | undefined; -}) => { - const app = streamableHTTPApp({ mcpOptions }); - const server = app.listen(port); - const address = server.address(); - - const logger = getLogger(); - - if (typeof address === 'string') { - logger.info(`MCP Server running on streamable HTTP at ${address}`); - } else if (address !== null) { - logger.info(`MCP Server running on streamable HTTP on port ${address.port}`); - } else { - logger.info(`MCP Server running on streamable HTTP on port ${port}`); - } -}; diff --git a/packages/mcp-server/src/index.ts b/packages/mcp-server/src/index.ts deleted file mode 100644 index 5bca4a60..00000000 --- a/packages/mcp-server/src/index.ts +++ /dev/null @@ -1,67 +0,0 @@ -#!/usr/bin/env node - -import { selectTools } from './server'; -import { McpOptions, parseCLIOptions } from './options'; -import { launchStdioServer } from './stdio'; -import { launchStreamableHTTPServer } from './http'; -import type { McpTool } from './types'; -import { configureLogger, getLogger } from './logger'; - -async function main() { - const options = parseOptionsOrError(); - configureLogger({ - level: options.debug ? 'debug' : 'info', - pretty: options.logFormat === 'pretty', - }); - - const selectedTools = await selectToolsOrError(options); - - getLogger().info( - { tools: selectedTools.map((e) => e.tool.name) }, - `MCP Server starting with ${selectedTools.length} tools`, - ); - - switch (options.transport) { - case 'stdio': - await launchStdioServer(options); - break; - case 'http': - await launchStreamableHTTPServer({ - mcpOptions: options, - port: options.socket ?? options.port, - }); - break; - } -} - -if (require.main === module) { - main().catch((error) => { - // Logger might not be initialized yet - console.error('Fatal error in main()', error); - process.exit(1); - }); -} - -function parseOptionsOrError() { - try { - return parseCLIOptions(); - } catch (error) { - // Logger is initialized after options, so use console.error here - console.error('Error parsing options', error); - process.exit(1); - } -} - -async function selectToolsOrError(options: McpOptions): Promise { - try { - const includedTools = selectTools(options); - if (includedTools.length === 0) { - getLogger().error('No tools match the provided filters'); - process.exit(1); - } - return includedTools; - } catch (error) { - getLogger().error({ error }, 'Error filtering tools'); - process.exit(1); - } -} diff --git a/packages/mcp-server/src/instructions.ts b/packages/mcp-server/src/instructions.ts deleted file mode 100644 index f3d6fdd8..00000000 --- a/packages/mcp-server/src/instructions.ts +++ /dev/null @@ -1,57 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import fs from 'fs/promises'; -import { getLogger } from './logger'; - -const INSTRUCTIONS_CACHE_TTL_MS = 15 * 60 * 1000; // 15 minutes - -interface InstructionsCacheEntry { - fetchedInstructions: string; - fetchedAt: number; -} - -const instructionsCache = new Map(); - -export async function getInstructions({ - stainlessApiKey, - customInstructionsPath, -}: { - stainlessApiKey?: string | undefined; - customInstructionsPath?: string | undefined; -}): Promise { - const now = Date.now(); - const cacheKey = customInstructionsPath ?? stainlessApiKey ?? ''; - const cached = instructionsCache.get(cacheKey); - - if (cached && now - cached.fetchedAt <= INSTRUCTIONS_CACHE_TTL_MS) { - return cached.fetchedInstructions; - } - - // Evict stale entries so the cache doesn't grow unboundedly. - for (const [key, entry] of instructionsCache) { - if (now - entry.fetchedAt > INSTRUCTIONS_CACHE_TTL_MS) { - instructionsCache.delete(key); - } - } - - let fetchedInstructions: string; - - if (customInstructionsPath) { - fetchedInstructions = await fetchLatestInstructionsFromFile(customInstructionsPath); - } else { - fetchedInstructions = - '\n This is the context.dev MCP server.\n\n Available tools:\n - search_docs: Search SDK documentation to find the right methods and parameters.\n - execute: Run TypeScript code against a pre-authenticated SDK client. Define an async run(client) function.\n\n Workflow:\n - If unsure about the API, call search_docs first.\n - Write complete solutions in a single execute call when possible. For large datasets, use API filters to narrow results or paginate within a single execute block.\n - If execute returns an error, read the error and fix your code rather than retrying the same approach.\n - Variables do not persist between execute calls. Return or log all data you need.\n - Individual HTTP requests to the API have a 30-second timeout. If a request times out, try a smaller query or add filters.\n - Code execution has a total timeout of approximately 5 minutes. If your code times out, simplify it or break it into smaller steps.\n '; - } - - instructionsCache.set(cacheKey, { fetchedInstructions, fetchedAt: now }); - return fetchedInstructions; -} - -async function fetchLatestInstructionsFromFile(path: string): Promise { - try { - return await fs.readFile(path, 'utf-8'); - } catch (error) { - getLogger().error({ error, path }, 'Error fetching instructions from file'); - throw error; - } -} diff --git a/packages/mcp-server/src/local-docs-search.ts b/packages/mcp-server/src/local-docs-search.ts deleted file mode 100644 index 8709272a..00000000 --- a/packages/mcp-server/src/local-docs-search.ts +++ /dev/null @@ -1,2661 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import MiniSearch from 'minisearch'; -import * as fs from 'node:fs/promises'; -import * as path from 'node:path'; -import { getLogger } from './logger'; - -type PerLanguageData = { - method?: string; - example?: string; -}; - -type MethodEntry = { - name: string; - endpoint: string; - httpMethod: string; - summary: string; - description: string; - stainlessPath: string; - qualified: string; - params?: string[]; - response?: string; - markdown?: string; - perLanguage?: Record; -}; - -type ProseChunk = { - content: string; - tag: string; - sectionContext?: string; - source?: string; -}; - -type MiniSearchDocument = { - id: string; - kind: 'http_method' | 'prose'; - name?: string; - endpoint?: string; - summary?: string; - description?: string; - qualified?: string; - stainlessPath?: string; - content?: string; - sectionContext?: string; - _original: Record; -}; - -type SearchResult = { - results: (string | Record)[]; -}; - -const EMBEDDED_METHODS: MethodEntry[] = [ - { - name: 'handle', - endpoint: '/parse', - httpMethod: 'post', - summary: 'Parse Bytes', - description: - 'Converts raw text, source code, web/data, PDF, Microsoft Office, and image bytes into LLM-usable Markdown.', - stainlessPath: '(resource) parse > (method) handle', - qualified: 'client.parse.handle', - params: [ - 'body: string;', - 'client?: string;', - 'extension?: string;', - 'includeImages?: boolean;', - 'includeLinks?: boolean;', - 'ocr?: boolean;', - 'pdf?: { end?: number; start?: number; };', - 'shortenBase64Images?: boolean;', - 'tags?: string[];', - 'useMainContentOnly?: boolean;', - "zdr?: 'enabled' | 'disabled';", - ], - response: - '{ markdown: string; success: true; type: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }', - markdown: - "## handle\n\n`client.parse.handle(body: string, client?: string, extension?: string, includeImages?: boolean, includeLinks?: boolean, ocr?: boolean, pdf?: { end?: number; start?: number; }, shortenBase64Images?: boolean, tags?: string[], useMainContentOnly?: boolean, zdr?: 'enabled' | 'disabled'): { markdown: string; success: true; type: string; key_metadata?: object; }`\n\n**post** `/parse`\n\nConverts raw text, source code, web/data, PDF, Microsoft Office, and image bytes into LLM-usable Markdown.\n\n### Parameters\n\n- `body: string`\n\n- `client?: string`\n Optional client identifier used for usage attribution.\n\n- `extension?: string`\n Optional file extension hint, such as pdf, docx, xlsx, pptx, html, json, csv, md, py, rtf, jpg, png, or txt.\n\n- `includeImages?: boolean`\n Include image references in Markdown output\n\n- `includeLinks?: boolean`\n Preserve hyperlinks in Markdown output\n\n- `ocr?: boolean`\n When true for PDF inputs, OCR the selected pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. pdf.start/pdf.end limit the inclusive page range. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs.\n\n- `pdf?: { end?: number; start?: number; }`\n PDF page-range options as a JSON object, e.g. {\"start\": 2, \"end\": 5}.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `shortenBase64Images?: boolean`\n Shorten base64-encoded image data in the Markdown output\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `useMainContentOnly?: boolean`\n Extract only the main content from HTML-like inputs\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ markdown: string; success: true; type: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `markdown: string`\n - `success: true`\n - `type: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.parse.handle(fs.createReadStream('path/to/file'));\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'parse->handle', - example: - "parse->handle(\n FileParam::fromString('Example data', filename: uniqid('file-upload-', true))\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Parse.Handle', - example: - 'package main\n\nimport (\n\t"bytes"\n\t"context"\n\t"fmt"\n\t"io"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Parse.Handle(\n\t\tcontext.TODO(),\n\t\tio.Reader(bytes.NewBuffer([]byte("Example data"))),\n\t\tcontextdev.ParseHandleParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Markdown)\n}\n', - }, - cli: { - method: 'parse handle', - example: "context-dev parse handle \\\n --api-key 'My API Key' \\\n --body 'Example data'", - }, - python: { - method: 'parse.handle', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.parse.handle(\n body=b"Example data",\n)\nprint(response.markdown)', - }, - ruby: { - method: 'parse.handle', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.parse.handle(body: StringIO.new("Example data"))\n\nputs(response)', - }, - typescript: { - method: 'client.parse.handle', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.parse.handle(fs.createReadStream('path/to/file'));\n\nconsole.log(response.markdown);", - }, - http: { - example: - "curl https://api.context.dev/v1/parse \\\n -H 'Content-Type: application/octet-stream' \\\n -H \"Authorization: Bearer $CONTEXT_DEV_API_KEY\" \\\n -F 'body=@/path/to/body'", - }, - }, - }, - { - name: 'web_scrape_html', - endpoint: '/web/scrape/html', - httpMethod: 'get', - summary: 'Scrape HTML', - description: - 'Scrapes the given URL and returns the raw HTML content of the page. The base request costs 1 credit; requests with browser actions cost 2 credits.', - stainlessPath: '(resource) web > (method) web_scrape_html', - qualified: 'client.web.webScrapeHTML', - params: [ - 'url: string;', - "actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[];", - 'country?: string;', - 'excludeSelectors?: string[];', - 'headers?: object;', - 'includeFrames?: boolean;', - 'includeSelectors?: string[];', - 'maxAgeMs?: number;', - 'pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; };', - 'settleAnimations?: boolean;', - 'tags?: string[];', - 'timeoutMS?: number;', - 'useMainContentOnly?: boolean;', - 'waitForMs?: number;', - "zdr?: 'enabled' | 'disabled';", - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; html: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; type: string; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## web_scrape_html\n\n`client.web.webScrapeHTML(url: string, actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[], country?: string, excludeSelectors?: string[], headers?: object, includeFrames?: boolean, includeSelectors?: string[], maxAgeMs?: number, pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }, settleAnimations?: boolean, tags?: string[], timeoutMS?: number, useMainContentOnly?: boolean, waitForMs?: number, zdr?: 'enabled' | 'disabled'): { cache_metadata: object; html: string; metadata: object; success: true; type: string; url: string; actionsApplied?: object[]; actionsHtmlStale?: boolean; key_metadata?: object; }`\n\n**get** `/web/scrape/html`\n\nScrapes the given URL and returns the raw HTML content of the page. The base request costs 1 credit; requests with browser actions cost 2 credits.\n\n### Parameters\n\n- `url: string`\n Full URL to scrape (must include http:// or https:// protocol)\n\n- `actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[]`\n Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `excludeSelectors?: string[]`\n CSS selectors to remove from the result. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\".\n\n- `headers?: object`\n Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.\n\n- `includeFrames?: boolean`\n When true, iframes are rendered inline into the returned HTML.\n\n- `includeSelectors?: string[]`\n CSS selectors. When provided, only matching subtrees (and their descendants) are kept and everything else is dropped. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\".\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }`\n PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `ocr?: boolean`\n When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs.\n - `shouldParse?: boolean`\n When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned.\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `settleAnimations?: boolean`\n When true, waits briefly for CSS and transition animations to settle before extracting HTML. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `useMainContentOnly?: boolean`\n When true, return only the page's main content in the HTML response, excluding headers, footers, sidebars, and navigation when detectable.\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load. Min: 0. Max: 30000 (30 seconds).\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; html: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; type: string; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `html: string`\n - `metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }`\n - `success: true`\n - `type: string`\n - `url: string`\n - `actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]`\n - `actionsHtmlStale?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webScrapeHTML({ url: 'https://example.com' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->webScrapeHTML', - example: - "web->webScrapeHTML(\n url: 'https://example.com',\n actions: [['do' => 'wait', 'timeMs' => 0]],\n country: 'de',\n excludeSelectors: ['x'],\n headers: ['foo' => 'J!'],\n includeFrames: true,\n includeSelectors: ['x'],\n maxAgeMs: 0,\n pdf: ['end' => 1, 'ocr' => true, 'shouldParse' => true, 'start' => 1],\n settleAnimations: true,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1,\n useMainContentOnly: true,\n waitForMs: 0,\n zdr: 'enabled',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.WebScrapeHTML', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.WebScrapeHTML(context.TODO(), contextdev.WebWebScrapeHTMLParams{\n\t\tURL: "https://example.com",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'web web_scrape_html', - example: - "context-dev web web-scrape-html \\\n --api-key 'My API Key' \\\n --url https://example.com", - }, - python: { - method: 'web.web_scrape_html', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.web_scrape_html(\n url="https://example.com",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'web.web_scrape_html', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.web_scrape_html(url: "https://example.com")\n\nputs(response)', - }, - typescript: { - method: 'client.web.webScrapeHTML', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.webScrapeHTML({ url: 'https://example.com' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/scrape/html \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'web_scrape_md', - endpoint: '/web/scrape/markdown', - httpMethod: 'get', - summary: 'Scrape Markdown', - description: - 'Scrapes the given URL into LLM usable Markdown. Inspect key_metadata on JSON responses from a recognized API key; use error_code to distinguish stable failure categories.\n\n### YouTube\n\nYouTube URLs return the video or channel itself rather than the surrounding player and navigation chrome. A URL addressing a single video (`/watch`, `youtu.be`, `/shorts`, `/embed`, `/live`) returns its title, channel, duration, view count, keywords, full description, and the transcript when the video has captions that can be retrieved; videos without captions return everything except the transcript. A channel URL (`/channel/UC…`, `/@handle`, `/c/…`, `/user/…`) returns its name, handle, subscriber count, video count, and full description. When `includeImages=true`, video responses also include the thumbnail and channel responses include the avatar. Costs the same as any other scrape.\n\n### Billing & errors\n\n| HTTP status | Billed? | Meaning |\n| --- | --- | --- |\n| 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing |\n| 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds |\n| 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code |\n| 404 | No | Target page returned or fingerprinted as not found |\n| 408 | No | Request timed out |\n| 413 | No | Target content exceeds the maximum supported size (20 MB) |\n| 415 | No | Unsupported content type |\n| 429 | No | Per-minute rate limit exceeded; honor Retry-After |\n| 500 | No | Internal error |', - stainlessPath: '(resource) web > (method) web_scrape_md', - qualified: 'client.web.webScrapeMd', - params: [ - 'url: string;', - "actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[];", - 'country?: string;', - 'excludeSelectors?: string[];', - 'headers?: object;', - 'includeFrames?: boolean;', - 'includeHTML?: boolean;', - 'includeImages?: boolean;', - 'includeLinks?: boolean;', - 'includeSelectors?: string[];', - 'maxAgeMs?: number;', - 'pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; };', - 'settleAnimations?: boolean;', - 'shortenBase64Images?: boolean;', - 'tags?: string[];', - 'timeoutMS?: number;', - 'useMainContentOnly?: boolean;', - 'waitForMs?: number;', - "zdr?: 'enabled' | 'disabled';", - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; contentLength: number; markdown: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; html?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## web_scrape_md\n\n`client.web.webScrapeMd(url: string, actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[], country?: string, excludeSelectors?: string[], headers?: object, includeFrames?: boolean, includeHTML?: boolean, includeImages?: boolean, includeLinks?: boolean, includeSelectors?: string[], maxAgeMs?: number, pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }, settleAnimations?: boolean, shortenBase64Images?: boolean, tags?: string[], timeoutMS?: number, useMainContentOnly?: boolean, waitForMs?: number, zdr?: 'enabled' | 'disabled'): { cache_metadata: object; contentLength: number; markdown: string; metadata: object; success: true; url: string; actionsApplied?: object[]; actionsHtmlStale?: boolean; html?: string; key_metadata?: object; }`\n\n**get** `/web/scrape/markdown`\n\nScrapes the given URL into LLM usable Markdown. Inspect key_metadata on JSON responses from a recognized API key; use error_code to distinguish stable failure categories.\n\n### YouTube\n\nYouTube URLs return the video or channel itself rather than the surrounding player and navigation chrome. A URL addressing a single video (`/watch`, `youtu.be`, `/shorts`, `/embed`, `/live`) returns its title, channel, duration, view count, keywords, full description, and the transcript when the video has captions that can be retrieved; videos without captions return everything except the transcript. A channel URL (`/channel/UC…`, `/@handle`, `/c/…`, `/user/…`) returns its name, handle, subscriber count, video count, and full description. When `includeImages=true`, video responses also include the thumbnail and channel responses include the avatar. Costs the same as any other scrape.\n\n### Billing & errors\n\n| HTTP status | Billed? | Meaning |\n| --- | --- | --- |\n| 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing |\n| 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds |\n| 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code |\n| 404 | No | Target page returned or fingerprinted as not found |\n| 408 | No | Request timed out |\n| 413 | No | Target content exceeds the maximum supported size (20 MB) |\n| 415 | No | Unsupported content type |\n| 429 | No | Per-minute rate limit exceeded; honor Retry-After |\n| 500 | No | Internal error |\n\n### Parameters\n\n- `url: string`\n Full URL to scrape into LLM usable Markdown (must include http:// or https:// protocol)\n\n- `actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[]`\n Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `excludeSelectors?: string[]`\n CSS selectors to remove before conversion to Markdown. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\".\n\n- `headers?: object`\n Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.\n\n- `includeFrames?: boolean`\n When true, the contents of iframes are rendered to Markdown.\n\n- `includeHTML?: boolean`\n When true, the response also includes an `html` field with the page HTML the Markdown was converted from — the same body the Scrape HTML endpoint returns for the equivalent request.\n\n- `includeImages?: boolean`\n Include image references in Markdown output\n\n- `includeLinks?: boolean`\n Preserve hyperlinks in Markdown output\n\n- `includeSelectors?: string[]`\n CSS selectors. When provided, only matching HTML subtrees (and their descendants) are kept before conversion to Markdown. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\".\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }`\n PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `ocr?: boolean`\n When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs.\n - `shouldParse?: boolean`\n When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned.\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `settleAnimations?: boolean`\n When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `shortenBase64Images?: boolean`\n Shorten base64-encoded image data in the Markdown output\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `useMainContentOnly?: boolean`\n Extract only the main content of the page, excluding headers, footers, sidebars, and navigation\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds).\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; contentLength: number; markdown: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; html?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `contentLength: number`\n - `markdown: string`\n - `metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }`\n - `success: true`\n - `url: string`\n - `actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]`\n - `actionsHtmlStale?: boolean`\n - `html?: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webScrapeMd({ url: 'https://example.com' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->webScrapeMd', - example: - "web->webScrapeMd(\n url: 'https://example.com',\n actions: [['do' => 'wait', 'timeMs' => 0]],\n country: 'de',\n excludeSelectors: ['x'],\n headers: ['foo' => 'J!'],\n includeFrames: true,\n includeHTML: true,\n includeImages: true,\n includeLinks: true,\n includeSelectors: ['x'],\n maxAgeMs: 0,\n pdf: ['end' => 1, 'ocr' => true, 'shouldParse' => true, 'start' => 1],\n settleAnimations: true,\n shortenBase64Images: true,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1,\n useMainContentOnly: true,\n waitForMs: 0,\n zdr: 'enabled',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.WebScrapeMd', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.WebScrapeMd(context.TODO(), contextdev.WebWebScrapeMdParams{\n\t\tURL: "https://example.com",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'web web_scrape_md', - example: "context-dev web web-scrape-md \\\n --api-key 'My API Key' \\\n --url https://example.com", - }, - python: { - method: 'web.web_scrape_md', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.web_scrape_md(\n url="https://example.com",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'web.web_scrape_md', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.web_scrape_md(url: "https://example.com")\n\nputs(response)', - }, - typescript: { - method: 'client.web.webScrapeMd', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.webScrapeMd({ url: 'https://example.com' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/scrape/markdown \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'web_scrape_images', - endpoint: '/web/scrape/images', - httpMethod: 'get', - summary: 'Scrape Images', - description: - 'Extract image assets from a web page, including standard URLs, inline SVGs, data URIs, responsive image sources, metadata, CSS backgrounds, video posters, and embeds. The base request costs 1 credit, or 2 credits with browser actions. When enrichment is enabled, the entire call costs 5 credits, including requests that also use actions.', - stainlessPath: '(resource) web > (method) web_scrape_images', - qualified: 'client.web.webScrapeImages', - params: [ - 'url: string;', - "actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[];", - 'dedupe?: boolean;', - 'enrichment?: { classification?: boolean; hostedUrl?: boolean; maxTimePerMs?: number; resolution?: boolean; };', - 'headers?: object;', - 'maxAgeMs?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - 'waitForMs?: number;', - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; images: { alt: string; element: 'img' | 'svg' | 'link' | 'source' | 'video' | 'css' | 'object' | 'meta' | 'background'; src: string; type: 'url' | 'html' | 'base64'; enrichment?: { height?: number; mimetype?: string; type?: 'photography' | 'illustration' | 'logo' | 'wordmark' | 'icon' | 'pattern' | 'graphic' | 'other'; url?: string; width?: number; }; }[]; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## web_scrape_images\n\n`client.web.webScrapeImages(url: string, actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[], dedupe?: boolean, enrichment?: { classification?: boolean; hostedUrl?: boolean; maxTimePerMs?: number; resolution?: boolean; }, headers?: object, maxAgeMs?: number, tags?: string[], timeoutMS?: number, waitForMs?: number): { cache_metadata: object; images: object[]; success: true; url: string; actionsApplied?: object[]; key_metadata?: object; }`\n\n**get** `/web/scrape/images`\n\nExtract image assets from a web page, including standard URLs, inline SVGs, data URIs, responsive image sources, metadata, CSS backgrounds, video posters, and embeds. The base request costs 1 credit, or 2 credits with browser actions. When enrichment is enabled, the entire call costs 5 credits, including requests that also use actions.\n\n### Parameters\n\n- `url: string`\n Page URL to inspect. Must include http:// or https://.\n\n- `actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[]`\n Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.\n\n- `dedupe?: boolean`\n When true, visually duplicate images are removed: every image is loaded and perceptually hashed, and only the highest-resolution copy of each duplicate group is kept. Images that cannot be downloaded or hashed are kept. Default: false.\n\n- `enrichment?: { classification?: boolean; hostedUrl?: boolean; maxTimePerMs?: number; resolution?: boolean; }`\n Optional per-image processing, sent as deep-object query params such as enrichment[resolution]=true.\n - `classification?: boolean`\n Classify each image by visual asset type.\n - `hostedUrl?: boolean`\n Host materializable images on the Brand.dev CDN and return their URL and MIME type.\n - `maxTimePerMs?: number`\n Per-image enrichment timeout in milliseconds. Default: 30000. Maximum: 60000.\n - `resolution?: boolean`\n Measure image width and height when possible.\n\n- `headers?: object`\n Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.\n\n- `maxAgeMs?: number`\n Reuse a cached result this many milliseconds old or newer. Default: 86400000 (1 day). Set to 0 to bypass cache. Maximum: 2592000000 (30 days).\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load before collecting images. Min: 0. Max: 30000 (30 seconds).\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; images: { alt: string; element: 'img' | 'svg' | 'link' | 'source' | 'video' | 'css' | 'object' | 'meta' | 'background'; src: string; type: 'url' | 'html' | 'base64'; enrichment?: { height?: number; mimetype?: string; type?: 'photography' | 'illustration' | 'logo' | 'wordmark' | 'icon' | 'pattern' | 'graphic' | 'other'; url?: string; width?: number; }; }[]; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `images: { alt: string; element: 'img' | 'svg' | 'link' | 'source' | 'video' | 'css' | 'object' | 'meta' | 'background'; src: string; type: 'url' | 'html' | 'base64'; enrichment?: { height?: number; mimetype?: string; type?: 'photography' | 'illustration' | 'logo' | 'wordmark' | 'icon' | 'pattern' | 'graphic' | 'other'; url?: string; width?: number; }; }[]`\n - `success: true`\n - `url: string`\n - `actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webScrapeImages({ url: 'https://example.com' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->webScrapeImages', - example: - "web->webScrapeImages(\n url: 'https://example.com',\n actions: [['do' => 'wait', 'timeMs' => 0]],\n dedupe: true,\n enrichment: [\n 'classification' => true,\n 'hostedURL' => true,\n 'maxTimePerMs' => 1,\n 'resolution' => true,\n ],\n headers: ['foo' => 'J!'],\n maxAgeMs: 0,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1,\n waitForMs: 0,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.WebScrapeImages', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.WebScrapeImages(context.TODO(), contextdev.WebWebScrapeImagesParams{\n\t\tURL: "https://example.com",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'web web_scrape_images', - example: - "context-dev web web-scrape-images \\\n --api-key 'My API Key' \\\n --url https://example.com", - }, - python: { - method: 'web.web_scrape_images', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.web_scrape_images(\n url="https://example.com",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'web.web_scrape_images', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.web_scrape_images(url: "https://example.com")\n\nputs(response)', - }, - typescript: { - method: 'client.web.webScrapeImages', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.webScrapeImages({ url: 'https://example.com' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/scrape/images \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'web_scrape_sitemap', - endpoint: '/web/scrape/sitemap', - httpMethod: 'get', - summary: 'Crawl Sitemap', - description: - "Crawl an entire website's sitemap and return all discovered page URLs. Pass `search` to have the crawled sitemap filtered down to the pages about a phrase (for example `pricing and plans` or `api authentication docs`), most relevant first — a searched crawl scans the whole sitemap and costs 2 credits instead of 1.", - stainlessPath: '(resource) web > (method) web_scrape_sitemap', - qualified: 'client.web.webScrapeSitemap', - params: [ - 'domain: string;', - 'headers?: object;', - 'maxLinks?: number;', - 'search?: string;', - 'sitemapUrl?: string;', - 'tags?: string[];', - 'timeoutMS?: number;', - 'urlRegex?: string;', - "zdr?: 'enabled' | 'disabled';", - ], - response: - '{ domain: string; meta: { errors: number; sitemapsDiscovered: number; sitemapsFetched: number; sitemapsSkipped: number; }; success: true; urls: string[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }', - markdown: - "## web_scrape_sitemap\n\n`client.web.webScrapeSitemap(domain: string, headers?: object, maxLinks?: number, search?: string, sitemapUrl?: string, tags?: string[], timeoutMS?: number, urlRegex?: string, zdr?: 'enabled' | 'disabled'): { domain: string; meta: object; success: true; urls: string[]; key_metadata?: object; }`\n\n**get** `/web/scrape/sitemap`\n\nCrawl an entire website's sitemap and return all discovered page URLs. Pass `search` to have the crawled sitemap filtered down to the pages about a phrase (for example `pricing and plans` or `api authentication docs`), most relevant first — a searched crawl scans the whole sitemap and costs 2 credits instead of 1.\n\n### Parameters\n\n- `domain: string`\n Domain to build a sitemap for\n\n- `headers?: object`\n Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.\n\n- `maxLinks?: number`\n Maximum number of links to return from the sitemap crawl. Defaults to 10,000. Minimum is 1, maximum is 100,000.\n\n- `search?: string`\n Optional search phrase. When provided, the crawled sitemap is filtered to the pages whose URLs are about that phrase, most relevant first, and the request costs 2 credits instead of 1.\n\n- `sitemapUrl?: string`\n Optional explicit sitemap URL. When provided, exactly this sitemap is crawled instead of discovering the domain's sitemaps.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `urlRegex?: string`\n Optional RE2-compatible regex pattern. Only URLs matching this pattern are returned and counted against maxLinks.\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ domain: string; meta: { errors: number; sitemapsDiscovered: number; sitemapsFetched: number; sitemapsSkipped: number; }; success: true; urls: string[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `domain: string`\n - `meta: { errors: number; sitemapsDiscovered: number; sitemapsFetched: number; sitemapsSkipped: number; }`\n - `success: true`\n - `urls: string[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webScrapeSitemap({ domain: 'xxx' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->webScrapeSitemap', - example: - "web->webScrapeSitemap(\n domain: 'xxx',\n headers: ['foo' => 'J!'],\n maxLinks: 1,\n search: 'help center and troubleshooting articles',\n sitemapURL: 'https://example.com',\n tags: ['production', 'team-alpha'],\n timeoutMs: 1,\n urlRegex: '^https?://[^/]+/blog/',\n zdr: 'enabled',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.WebScrapeSitemap', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.WebScrapeSitemap(context.TODO(), contextdev.WebWebScrapeSitemapParams{\n\t\tDomain: "xxx",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Domain)\n}\n', - }, - cli: { - method: 'web web_scrape_sitemap', - example: "context-dev web web-scrape-sitemap \\\n --api-key 'My API Key' \\\n --domain xxx", - }, - python: { - method: 'web.web_scrape_sitemap', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.web_scrape_sitemap(\n domain="xxx",\n)\nprint(response.domain)', - }, - ruby: { - method: 'web.web_scrape_sitemap', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.web_scrape_sitemap(domain: "xxx")\n\nputs(response)', - }, - typescript: { - method: 'client.web.webScrapeSitemap', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.webScrapeSitemap({ domain: 'xxx' });\n\nconsole.log(response.domain);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/scrape/sitemap \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'screenshot', - endpoint: '/web/screenshot', - httpMethod: 'get', - summary: 'Scrape Screenshot', - description: 'Capture a screenshot of a website.', - stainlessPath: '(resource) web > (method) screenshot', - qualified: 'client.web.screenshot', - params: [ - 'clearPopups?: boolean;', - "colorScheme?: 'light' | 'dark';", - 'country?: string;', - 'directUrl?: string;', - 'domain?: string;', - "fullScreenshot?: 'true' | 'false';", - 'handleCookiePopup?: boolean;', - 'maxAgeMs?: number;', - "page?: 'login' | 'signup' | 'blog' | 'careers' | 'pricing' | 'terms' | 'privacy' | 'contact';", - 'scrollOffset?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - 'viewport?: { height?: number; width?: number; };', - 'waitForMs?: number;', - "zdr?: 'enabled' | 'disabled';", - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; code?: number; domain?: string; height?: number; key_metadata?: { credits_consumed: number; credits_remaining: number; }; screenshot?: string; screenshotType?: 'viewport' | 'fullPage'; status?: string; width?: number; }", - markdown: - "## screenshot\n\n`client.web.screenshot(clearPopups?: boolean, colorScheme?: 'light' | 'dark', country?: string, directUrl?: string, domain?: string, fullScreenshot?: 'true' | 'false', handleCookiePopup?: boolean, maxAgeMs?: number, page?: 'login' | 'signup' | 'blog' | 'careers' | 'pricing' | 'terms' | 'privacy' | 'contact', scrollOffset?: number, tags?: string[], timeoutMS?: number, viewport?: { height?: number; width?: number; }, waitForMs?: number, zdr?: 'enabled' | 'disabled'): { cache_metadata: object; code?: number; domain?: string; height?: number; key_metadata?: object; screenshot?: string; screenshotType?: 'viewport' | 'fullPage'; status?: string; width?: number; }`\n\n**get** `/web/screenshot`\n\nCapture a screenshot of a website.\n\n### Parameters\n\n- `clearPopups?: boolean`\n Optional parameter for comprehensive popup cleanup. If 'true', the browser dismisses detected cookie/consent UI and clears other detected obstructive popups and overlays before capture. If 'false' or not provided, this parameter requests no cleanup; handleCookiePopup can still request cookie/consent handling independently.\n\n- `colorScheme?: 'light' | 'dark'`\n Optional parameter to choose the site's visual theme in the screenshot. Use 'light' or 'dark' when the site offers both appearances.\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `directUrl?: string`\n A specific URL to screenshot directly, bypassing domain resolution (e.g., 'https://example.com/pricing'). When provided, the screenshot is taken of this exact URL. You must provide either 'domain' or 'directUrl', but not both.\n\n- `domain?: string`\n Domain name to take screenshot of (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both.\n\n- `fullScreenshot?: 'true' | 'false'`\n Optional parameter to determine screenshot type. If 'true', takes a full page screenshot capturing all content. If 'false' or not provided, takes a viewport screenshot (standard browser view).\n\n- `handleCookiePopup?: boolean`\n Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step.\n\n- `maxAgeMs?: number`\n Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh.\n\n- `page?: 'login' | 'signup' | 'blog' | 'careers' | 'pricing' | 'terms' | 'privacy' | 'contact'`\n Optional parameter to specify which page type to screenshot. If provided, the system will scrape the domain's links and use heuristics to find the most appropriate URL for the specified page type (30 supported languages). If not provided, screenshots the main domain landing page. Only applicable when using 'domain', not 'directUrl'.\n\n- `scrollOffset?: number`\n Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `viewport?: { height?: number; width?: number; }`\n Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080.\n - `height?: number`\n Viewport height in pixels.\n - `width?: number`\n Viewport width in pixels.\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load before taking the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when omitted.\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; code?: number; domain?: string; height?: number; key_metadata?: { credits_consumed: number; credits_remaining: number; }; screenshot?: string; screenshotType?: 'viewport' | 'fullPage'; status?: string; width?: number; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `code?: number`\n - `domain?: string`\n - `height?: number`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `screenshot?: string`\n - `screenshotType?: 'viewport' | 'fullPage'`\n - `status?: string`\n - `width?: number`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.screenshot();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->screenshot', - example: - "web->screenshot(\n clearPopups: true,\n colorScheme: 'light',\n country: 'de',\n directURL: 'https://example.com',\n domain: 'xxx',\n fullScreenshot: 'true',\n handleCookiePopup: true,\n maxAgeMs: 0,\n page: 'login',\n scrollOffset: 0,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1,\n viewport: ['height' => 240, 'width' => 240],\n waitForMs: 0,\n zdr: 'enabled',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.Screenshot', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.Screenshot(context.TODO(), contextdev.WebScreenshotParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Width)\n}\n', - }, - cli: { - method: 'web screenshot', - example: "context-dev web screenshot \\\n --api-key 'My API Key'", - }, - python: { - method: 'web.screenshot', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.screenshot()\nprint(response.width)', - }, - ruby: { - method: 'web.screenshot', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.screenshot\n\nputs(response)', - }, - typescript: { - method: 'client.web.screenshot', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.screenshot();\n\nconsole.log(response.width);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/screenshot \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'web_crawl_md', - endpoint: '/web/crawl', - httpMethod: 'post', - summary: 'Crawl Website & Scrape Markdown', - description: - 'Performs a crawl starting from a given URL, extracts page content as Markdown, and returns results for all crawled pages.', - stainlessPath: '(resource) web > (method) web_crawl_md', - qualified: 'client.web.webCrawlMd', - params: [ - 'url: string;', - 'country?: string;', - 'excludeSelectors?: string[];', - 'followSubdomains?: boolean;', - 'includeFrames?: boolean;', - 'includeImages?: boolean;', - 'includeLinks?: boolean;', - 'includeSelectors?: string[];', - 'maxAgeMs?: number;', - 'maxDepth?: number;', - 'maxPages?: number;', - 'pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; };', - 'settleAnimations?: boolean;', - 'shortenBase64Images?: boolean;', - 'stopAfterMs?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - 'urlRegex?: string;', - 'useMainContentOnly?: boolean;', - 'waitForMs?: number;', - "zdr?: 'enabled' | 'disabled';", - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; metadata: { maxCrawlDepth: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; }; results: { markdown: string; metadata: { crawlDepth: number; finalUrl: string; sourceUrl: string; statusCode: number; success: boolean; title: string; url: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: object[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; twitter?: object; }; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## web_crawl_md\n\n`client.web.webCrawlMd(url: string, country?: string, excludeSelectors?: string[], followSubdomains?: boolean, includeFrames?: boolean, includeImages?: boolean, includeLinks?: boolean, includeSelectors?: string[], maxAgeMs?: number, maxDepth?: number, maxPages?: number, pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }, settleAnimations?: boolean, shortenBase64Images?: boolean, stopAfterMs?: number, tags?: string[], timeoutMS?: number, urlRegex?: string, useMainContentOnly?: boolean, waitForMs?: number, zdr?: 'enabled' | 'disabled'): { cache_metadata: object; metadata: object; results: object[]; key_metadata?: object; }`\n\n**post** `/web/crawl`\n\nPerforms a crawl starting from a given URL, extracts page content as Markdown, and returns results for all crawled pages.\n\n### Parameters\n\n- `url: string`\n The starting URL for the crawl (must include http:// or https:// protocol)\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `excludeSelectors?: string[]`\n CSS selectors to remove before each crawled page is converted to Markdown. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\".\n\n- `followSubdomains?: boolean`\n When true, follow links on subdomains of the starting URL's domain (e.g. docs.example.com when starting from example.com). www and apex are always treated as equivalent.\n\n- `includeFrames?: boolean`\n When true, the contents of iframes are rendered to Markdown for each crawled page.\n\n- `includeImages?: boolean`\n Include image references in the Markdown output\n\n- `includeLinks?: boolean`\n Preserve hyperlinks in the Markdown output\n\n- `includeSelectors?: string[]`\n CSS selectors. When provided, only matching HTML subtrees (and their descendants) are kept before each crawled page is converted to Markdown. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\".\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `maxDepth?: number`\n Maximum link depth from the starting URL (0 = only the starting page)\n\n- `maxPages?: number`\n Maximum number of pages to crawl. Hard cap: 500.\n\n- `pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }`\n PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `ocr?: boolean`\n When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost.\n - `shouldParse?: boolean`\n When true, PDF pages are fetched and parsed. When false, PDF pages are skipped entirely (not included in results and not counted as failures).\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `settleAnimations?: boolean`\n When true, waits briefly for CSS and transition animations to settle before extracting each crawled page. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `shortenBase64Images?: boolean`\n Truncate base64-encoded image data in the Markdown output\n\n- `stopAfterMs?: number`\n Soft time budget for the crawl in milliseconds. After each scrape, the crawler checks the elapsed time and, if exceeded, returns the pages collected so far instead of continuing. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 (80s).\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `urlRegex?: string`\n Regex pattern. Only URLs matching this pattern will be followed and scraped. An automatic prefix scope in the form ^ follows a redirect of the starting page.\n\n- `useMainContentOnly?: boolean`\n Extract only the main content, stripping headers, footers, sidebars, and navigation\n\n- `waitForMs?: number`\n Browser wait time in milliseconds after initial page load for each crawled page. Defaults to 3500 (3.5 seconds). Min: 0. Max: 30000 (30 seconds).\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; metadata: { maxCrawlDepth: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; }; results: { markdown: string; metadata: { crawlDepth: number; finalUrl: string; sourceUrl: string; statusCode: number; success: boolean; title: string; url: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: object[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; twitter?: object; }; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `metadata: { maxCrawlDepth: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; }`\n - `results: { markdown: string; metadata: { crawlDepth: number; finalUrl: string; sourceUrl: string; statusCode: number; success: boolean; title: string; url: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; twitter?: object; }; }[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webCrawlMd({ url: 'https://example.com' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->webCrawlMd', - example: - "web->webCrawlMd(\n url: 'https://example.com',\n country: 'de',\n excludeSelectors: ['string'],\n followSubdomains: true,\n includeFrames: true,\n includeImages: true,\n includeLinks: true,\n includeSelectors: ['string'],\n maxAgeMs: 0,\n maxDepth: 0,\n maxPages: 1,\n pdf: ['end' => 1, 'ocr' => true, 'shouldParse' => true, 'start' => 1],\n settleAnimations: true,\n shortenBase64Images: true,\n stopAfterMs: 10000,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n urlRegex: '^https?://[^/]+/blog/',\n useMainContentOnly: true,\n waitForMs: 0,\n zdr: 'enabled',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.WebCrawlMd', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.WebCrawlMd(context.TODO(), contextdev.WebWebCrawlMdParams{\n\t\tURL: "https://example.com",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'web web_crawl_md', - example: "context-dev web web-crawl-md \\\n --api-key 'My API Key' \\\n --url https://example.com", - }, - python: { - method: 'web.web_crawl_md', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.web_crawl_md(\n url="https://example.com",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'web.web_crawl_md', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.web_crawl_md(url: "https://example.com")\n\nputs(response)', - }, - typescript: { - method: 'client.web.webCrawlMd', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.webCrawlMd({ url: 'https://example.com' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/crawl \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "url": "https://example.com",\n "country": "de",\n "tags": [\n "production",\n "team-alpha"\n ],\n "urlRegex": "^https?://[^/]+/blog/"\n }\'', - }, - }, - }, - { - name: 'extract_fonts', - endpoint: '/web/fonts', - httpMethod: 'get', - summary: 'Scrape Fonts', - description: - 'Scrape font information from a website including font families, usage statistics, fallbacks, and element/word counts.', - stainlessPath: '(resource) web > (method) extract_fonts', - qualified: 'client.web.extractFonts', - params: [ - 'directUrl?: string;', - 'domain?: string;', - 'maxAgeMs?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; code: number; domain: string; fonts: { fallbacks: string[]; font: string; num_elements: number; num_words: number; percent_elements: number; percent_words: number; uses: string[]; }[]; status: string; fontLinks?: object; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## extract_fonts\n\n`client.web.extractFonts(directUrl?: string, domain?: string, maxAgeMs?: number, tags?: string[], timeoutMS?: number): { cache_metadata: object; code: number; domain: string; fonts: object[]; status: string; fontLinks?: object; key_metadata?: object; }`\n\n**get** `/web/fonts`\n\nScrape font information from a website including font families, usage statistics, fallbacks, and element/word counts.\n\n### Parameters\n\n- `directUrl?: string`\n A specific URL to fetch fonts from directly, bypassing domain resolution (e.g., 'https://example.com/design-system'). When provided, fonts are extracted from this exact URL. You must provide either 'domain' or 'directUrl', but not both.\n\n- `domain?: string`\n Domain name to extract fonts from (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both.\n\n- `maxAgeMs?: number`\n Maximum age in milliseconds for cached brand data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 year.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; code: number; domain: string; fonts: { fallbacks: string[]; font: string; num_elements: number; num_words: number; percent_elements: number; percent_words: number; uses: string[]; }[]; status: string; fontLinks?: object; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `code: number`\n - `domain: string`\n - `fonts: { fallbacks: string[]; font: string; num_elements: number; num_words: number; percent_elements: number; percent_words: number; uses: string[]; }[]`\n - `status: string`\n - `fontLinks?: object`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.extractFonts();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->extractFonts', - example: - "web->extractFonts(\n directURL: 'https://example.com',\n domain: 'xxx',\n maxAgeMs: 0,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.ExtractFonts', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.ExtractFonts(context.TODO(), contextdev.WebExtractFontsParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'web extract_fonts', - example: "context-dev web extract-fonts \\\n --api-key 'My API Key'", - }, - python: { - method: 'web.extract_fonts', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.extract_fonts()\nprint(response.cache_metadata)', - }, - ruby: { - method: 'web.extract_fonts', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.extract_fonts\n\nputs(response)', - }, - typescript: { - method: 'client.web.extractFonts', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.extractFonts();\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/fonts \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'extract_styleguide', - endpoint: '/web/styleguide', - httpMethod: 'get', - summary: 'Scrape Styleguide', - description: - 'Extract a comprehensive design system from a website including colors, typography, spacing, shadows, and UI components.', - stainlessPath: '(resource) web > (method) extract_styleguide', - qualified: 'client.web.extractStyleguide', - params: [ - "colorScheme?: 'light' | 'dark';", - 'directUrl?: string;', - 'domain?: string;', - 'maxAgeMs?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; code?: number; domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; styleguide?: { colors: { accent: string; background: string; text: string; }; components: { button: object; card?: object; }; elementSpacing: { lg: string; md: string; sm: string; xl: string; xs: string; }; fontLinks: object; mode: 'light' | 'dark'; shadows: { inner: string; lg: string; md: string; sm: string; xl: string; }; typography: { headings: object; p?: object; }; }; }", - markdown: - "## extract_styleguide\n\n`client.web.extractStyleguide(colorScheme?: 'light' | 'dark', directUrl?: string, domain?: string, maxAgeMs?: number, tags?: string[], timeoutMS?: number): { cache_metadata: object; code?: number; domain?: string; key_metadata?: object; status?: string; styleguide?: object; }`\n\n**get** `/web/styleguide`\n\nExtract a comprehensive design system from a website including colors, typography, spacing, shadows, and UI components.\n\n### Parameters\n\n- `colorScheme?: 'light' | 'dark'`\n Optional browser color scheme to emulate for websites that respond to prefers-color-scheme. This value is part of the styleguide cache key.\n\n- `directUrl?: string`\n A specific URL to fetch the styleguide from directly, bypassing domain resolution (e.g., 'https://example.com/design-system'). When provided, the styleguide is extracted from this exact URL. You must provide either 'domain' or 'directUrl', but not both.\n\n- `domain?: string`\n Domain name to extract styleguide from (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both.\n\n- `maxAgeMs?: number`\n Maximum age in milliseconds for cached brand data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 year.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; code?: number; domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; styleguide?: { colors: { accent: string; background: string; text: string; }; components: { button: object; card?: object; }; elementSpacing: { lg: string; md: string; sm: string; xl: string; xs: string; }; fontLinks: object; mode: 'light' | 'dark'; shadows: { inner: string; lg: string; md: string; sm: string; xl: string; }; typography: { headings: object; p?: object; }; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `code?: number`\n - `domain?: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `status?: string`\n - `styleguide?: { colors: { accent: string; background: string; text: string; }; components: { button: { link?: { backgroundColor: string; borderColor: string; borderRadius: string; borderStyle: string; borderWidth: string; boxShadow: string; color: string; css: string; fontSize: string; fontWeight: number; minHeight: string; minWidth: string; padding: string; textDecoration: string; fontFallbacks?: string[]; fontFamily?: string; textDecorationColor?: string; }; primary?: { backgroundColor: string; borderColor: string; borderRadius: string; borderStyle: string; borderWidth: string; boxShadow: string; color: string; css: string; fontSize: string; fontWeight: number; minHeight: string; minWidth: string; padding: string; textDecoration: string; fontFallbacks?: string[]; fontFamily?: string; textDecorationColor?: string; }; secondary?: { backgroundColor: string; borderColor: string; borderRadius: string; borderStyle: string; borderWidth: string; boxShadow: string; color: string; css: string; fontSize: string; fontWeight: number; minHeight: string; minWidth: string; padding: string; textDecoration: string; fontFallbacks?: string[]; fontFamily?: string; textDecorationColor?: string; }; }; card?: { backgroundColor: string; borderColor: string; borderRadius: string; borderStyle: string; borderWidth: string; boxShadow: string; css: string; padding: string; textColor: string; }; }; elementSpacing: { lg: string; md: string; sm: string; xl: string; xs: string; }; fontLinks: object; mode: 'light' | 'dark'; shadows: { inner: string; lg: string; md: string; sm: string; xl: string; }; typography: { headings: { h1?: { fontFallbacks: string[]; fontFamily: string; fontSize: string; fontWeight: number; letterSpacing: string; lineHeight: string; }; h2?: { fontFallbacks: string[]; fontFamily: string; fontSize: string; fontWeight: number; letterSpacing: string; lineHeight: string; }; h3?: { fontFallbacks: string[]; fontFamily: string; fontSize: string; fontWeight: number; letterSpacing: string; lineHeight: string; }; h4?: { fontFallbacks: string[]; fontFamily: string; fontSize: string; fontWeight: number; letterSpacing: string; lineHeight: string; }; }; p?: { fontFallbacks: string[]; fontFamily: string; fontSize: string; fontWeight: number; letterSpacing: string; lineHeight: string; }; }; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.extractStyleguide();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->extractStyleguide', - example: - "web->extractStyleguide(\n colorScheme: 'light',\n directURL: 'https://example.com',\n domain: 'xxx',\n maxAgeMs: 0,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.ExtractStyleguide', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.ExtractStyleguide(context.TODO(), contextdev.WebExtractStyleguideParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Styleguide)\n}\n', - }, - cli: { - method: 'web extract_styleguide', - example: "context-dev web extract-styleguide \\\n --api-key 'My API Key'", - }, - python: { - method: 'web.extract_styleguide', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.extract_styleguide()\nprint(response.styleguide)', - }, - ruby: { - method: 'web.extract_styleguide', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.extract_styleguide\n\nputs(response)', - }, - typescript: { - method: 'client.web.extractStyleguide', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.extractStyleguide();\n\nconsole.log(response.styleguide);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/styleguide \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'search', - endpoint: '/web/search', - httpMethod: 'post', - summary: 'Web Search', - description: 'Search the web and optionally scrape each result to Markdown in one round-trip.', - stainlessPath: '(resource) web > (method) search', - qualified: 'client.web.search', - params: [ - 'query: string;', - 'country?: string;', - 'excludeDomains?: string[];', - "freshness?: 'last_24_hours' | 'last_week' | 'last_month' | 'last_year';", - 'includeDomains?: string[];', - 'markdownOptions?: { enabled?: boolean; includeFrames?: boolean; includeImages?: boolean; includeLinks?: boolean; maxAgeMs?: number; pdf?: { end?: number; shouldParse?: boolean; start?: number; }; shortenBase64Images?: boolean; timeoutMS?: number; useMainContentOnly?: boolean; waitForMs?: number; };', - 'numResults?: number;', - 'queryFanout?: boolean;', - 'tags?: string[];', - 'timeoutMS?: number;', - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; query: string; results: { description: string; markdown: { code: 'SUCCESS' | 'NOT_REQUESTED' | 'TIMEOUT' | 'CONTENT_TOO_LARGE' | 'WEBSITE_ACCESS_ERROR' | 'ERROR'; markdown: string; }; relevance: 'high' | 'medium' | 'low'; title: string; url: string; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## search\n\n`client.web.search(query: string, country?: string, excludeDomains?: string[], freshness?: 'last_24_hours' | 'last_week' | 'last_month' | 'last_year', includeDomains?: string[], markdownOptions?: { enabled?: boolean; includeFrames?: boolean; includeImages?: boolean; includeLinks?: boolean; maxAgeMs?: number; pdf?: { end?: number; shouldParse?: boolean; start?: number; }; shortenBase64Images?: boolean; timeoutMS?: number; useMainContentOnly?: boolean; waitForMs?: number; }, numResults?: number, queryFanout?: boolean, tags?: string[], timeoutMS?: number): { cache_metadata: object; query: string; results: object[]; key_metadata?: object; }`\n\n**post** `/web/search`\n\nSearch the web and optionally scrape each result to Markdown in one round-trip.\n\n### Parameters\n\n- `query: string`\n Search query. Accepts natural language as well as Google-style search operators such as `site:`, `-site:`, `inurl:`, `intitle:`, quoted phrases, and `OR`.\n\n- `country?: string`\n Two-letter ISO 3166-1 alpha-2 country code to localize results to a specific country (maps to Google's `gl` parameter). Example: \"us\", \"gb\", \"de\".\n\n- `excludeDomains?: string[]`\n Blocklist — drop results from these domains. Example: [\"pinterest.com\", \"reddit.com\"].\n\n- `freshness?: 'last_24_hours' | 'last_week' | 'last_month' | 'last_year'`\n Restrict results to content published within this window.\n\n- `includeDomains?: string[]`\n Allowlist — only return results from these domains. Example: [\"arxiv.org\", \"github.com\"].\n\n- `markdownOptions?: { enabled?: boolean; includeFrames?: boolean; includeImages?: boolean; includeLinks?: boolean; maxAgeMs?: number; pdf?: { end?: number; shouldParse?: boolean; start?: number; }; shortenBase64Images?: boolean; timeoutMS?: number; useMainContentOnly?: boolean; waitForMs?: number; }`\n Inline Markdown scraping for each result. Set `enabled: true` to activate.\n - `enabled?: boolean`\n Scrape each result to Markdown. Off by default to keep search cheap and fast.\n - `includeFrames?: boolean`\n Render iframe contents into the Markdown.\n - `includeImages?: boolean`\n Emit image references in the Markdown.\n - `includeLinks?: boolean`\n Keep hyperlinks in the Markdown.\n - `maxAgeMs?: number`\n Cache TTL in ms for scraped Markdown keyed by URL + options. Default 1 day, max 30 days. Set to 0 to force a fresh scrape.\n - `pdf?: { end?: number; shouldParse?: boolean; start?: number; }`\n PDF handling. Use start/end to bound text extraction and OCR to a page range.\n - `shortenBase64Images?: boolean`\n Truncate inline base64 image payloads to keep responses small.\n - `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n - `useMainContentOnly?: boolean`\n Strip nav, header, footer, and sidebar — keep only the primary article content.\n - `waitForMs?: number`\n Extra wait after page load before rendering, in ms (0–30000). Useful for JS-heavy pages.\n\n- `numResults?: number`\n Number of results to request and return (10–100). Defaults to 10.\n\n- `queryFanout?: boolean`\n Expand the query into multiple parallel variants for broader recall.\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; query: string; results: { description: string; markdown: { code: 'SUCCESS' | 'NOT_REQUESTED' | 'TIMEOUT' | 'CONTENT_TOO_LARGE' | 'WEBSITE_ACCESS_ERROR' | 'ERROR'; markdown: string; }; relevance: 'high' | 'medium' | 'low'; title: string; url: string; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `query: string`\n - `results: { description: string; markdown: { code: 'SUCCESS' | 'NOT_REQUESTED' | 'TIMEOUT' | 'CONTENT_TOO_LARGE' | 'WEBSITE_ACCESS_ERROR' | 'ERROR'; markdown: string; }; relevance: 'high' | 'medium' | 'low'; title: string; url: string; }[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.search({ query: 'x' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->search', - example: - "web->search(\n query: 'x',\n country: 'af',\n excludeDomains: ['string'],\n freshness: 'last_24_hours',\n includeDomains: ['string'],\n markdownOptions: [\n 'enabled' => true,\n 'includeFrames' => true,\n 'includeImages' => true,\n 'includeLinks' => true,\n 'maxAgeMs' => 0,\n 'pdf' => ['end' => 1, 'shouldParse' => true, 'start' => 1],\n 'shortenBase64Images' => true,\n 'timeoutMs' => 1000,\n 'useMainContentOnly' => true,\n 'waitForMs' => 0,\n ],\n numResults: 10,\n queryFanout: true,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.Search', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.Search(context.TODO(), contextdev.WebSearchParams{\n\t\tQuery: "x",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'web search', - example: "context-dev web search \\\n --api-key 'My API Key' \\\n --query x", - }, - python: { - method: 'web.search', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.search(\n query="x",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'web.search', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.search(query: "x")\n\nputs(response)', - }, - typescript: { - method: 'client.web.search', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.search({ query: 'x' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/search \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "query": "x",\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, - { - name: 'extract', - endpoint: '/web/extract', - httpMethod: 'post', - summary: 'Extract Structured Website Data', - description: - 'Crawl a website, use the provided JSON Schema and instructions to prioritize relevant internal links, and extract structured data from the selected pages.', - stainlessPath: '(resource) web > (method) extract', - qualified: 'client.web.extract', - params: [ - 'schema: object;', - 'url: string;', - "actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[];", - 'factCheck?: boolean;', - 'followSubdomains?: boolean;', - 'includeFrames?: boolean;', - 'instructions?: string;', - 'maxAgeMs?: number;', - 'maxDepth?: number;', - 'maxPages?: number;', - 'pdf?: { end?: number; shouldParse?: boolean; start?: number; };', - 'settleAnimations?: boolean;', - 'stopAfterMs?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - 'waitForMs?: number;', - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; data: object; metadata: { maxCrawlDepth: number; numBlocked: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; }; status: string; url: string; urls_analyzed: string[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## extract\n\n`client.web.extract(schema: object, url: string, actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[], factCheck?: boolean, followSubdomains?: boolean, includeFrames?: boolean, instructions?: string, maxAgeMs?: number, maxDepth?: number, maxPages?: number, pdf?: { end?: number; shouldParse?: boolean; start?: number; }, settleAnimations?: boolean, stopAfterMs?: number, tags?: string[], timeoutMS?: number, waitForMs?: number): { cache_metadata: object; data: object; metadata: object; status: string; url: string; urls_analyzed: string[]; key_metadata?: object; }`\n\n**post** `/web/extract`\n\nCrawl a website, use the provided JSON Schema and instructions to prioritize relevant internal links, and extract structured data from the selected pages.\n\n### Parameters\n\n- `schema: object`\n JSON Schema for the returned data object. Image fields such as `image_urls` or `product_photos` automatically make page image references available to extraction, so product data and photos can be returned in one call. TypeScript Zod users can pass a JSON Schema generated from a Zod object; Python users can pass the equivalent JSON Schema object.\n\n- `url: string`\n The starting website URL to crawl and extract from. Must include http:// or https://.\n\n- `actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; } | { do: 'scroll'; amount?: number | 'viewport' | 'max'; container?: string; direction?: 'up' | 'down' | 'left' | 'right'; maxScrolls?: number; }[]`\n Optional browser actions executed in order on the requested page after it loads, before links are discovered or additional pages are crawled. Requires a paid plan. When actions are provided and stopAfterMs is omitted, the crawl budget defaults to 110000 ms.\n\n- `factCheck?: boolean`\n When true, every returned value must be grounded in facts stated on the page; fields that cannot be supported by the page are returned as null/empty. When false (default), the model may make reasonable inferences and derivations from the page content (e.g. ideal customer, competitor analysis, recommendations) while keeping verifiable specifics (names, quotes, URLs, dates, metrics) faithful to the source.\n\n- `followSubdomains?: boolean`\n When true, follow links on subdomains of the starting URL's domain.\n\n- `includeFrames?: boolean`\n When true, iframe contents are included in Markdown before extraction.\n\n- `instructions?: string`\n Optional extraction guidance, such as which facts to prioritize or how to interpret fields in the schema.\n\n- `maxAgeMs?: number`\n Return cached scrape results if a prior scrape for the same parameters is younger than this many milliseconds. Defaults to 7 days (604800000 ms).\n\n- `maxDepth?: number`\n Optional maximum link depth from the starting URL (0 = only the starting page). If omitted, there is no crawl depth limit.\n\n- `maxPages?: number`\n Maximum number of pages to analyze for extraction. Hard cap: 50. Defaults to 5.\n\n- `pdf?: { end?: number; shouldParse?: boolean; start?: number; }`\n - `end?: number`\n Last 1-based PDF page to parse. Must be greater than or equal to start when both are provided.\n - `shouldParse?: boolean`\n When true, PDF pages are fetched and parsed. When false, PDF pages are skipped.\n - `start?: number`\n First 1-based PDF page to parse.\n\n- `settleAnimations?: boolean`\n When true, waits briefly for CSS and transition animations to settle before extracting each crawled page. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `stopAfterMs?: number`\n Soft time budget for the crawl in milliseconds. Min: 10000 (10s). Max: 110000 (110s). Defaults to 80000 (80s), or 110000 (110s) when browser actions are provided.\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load for each crawled page.\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; data: object; metadata: { maxCrawlDepth: number; numBlocked: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; }; status: string; url: string; urls_analyzed: string[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `data: object`\n - `metadata: { maxCrawlDepth: number; numBlocked: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; }`\n - `status: string`\n - `url: string`\n - `urls_analyzed: string[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.extract({\n schema: {\n type: 'bar',\n properties: 'bar',\n required: 'bar',\n additionalProperties: 'bar',\n},\n url: 'https://example.com',\n});\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->extract', - example: - "web->extract(\n schema: [\n 'type' => 'bar',\n 'properties' => 'bar',\n 'required' => 'bar',\n 'additionalProperties' => 'bar',\n ],\n url: 'https://example.com',\n actions: [['do' => 'wait', 'timeMs' => 0]],\n factCheck: true,\n followSubdomains: true,\n includeFrames: true,\n instructions: 'instructions',\n maxAgeMs: 0,\n maxDepth: 0,\n maxPages: 1,\n pdf: ['end' => 1, 'shouldParse' => true, 'start' => 1],\n settleAnimations: true,\n stopAfterMs: 10000,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n waitForMs: 0,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.Extract', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.Extract(context.TODO(), contextdev.WebExtractParams{\n\t\tSchema: map[string]any{\n\t\t\t"type": "bar",\n\t\t\t"properties": "bar",\n\t\t\t"required": "bar",\n\t\t\t"additionalProperties": "bar",\n\t\t},\n\t\tURL: "https://example.com",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'web extract', - example: - "context-dev web extract \\\n --api-key 'My API Key' \\\n --schema '{type: bar, properties: bar, required: bar, additionalProperties: bar}' \\\n --url https://example.com", - }, - python: { - method: 'web.extract', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.extract(\n schema={\n "type": "bar",\n "properties": "bar",\n "required": "bar",\n "additionalProperties": "bar",\n },\n url="https://example.com",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'web.extract', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.extract(\n schema: {type: "bar", properties: "bar", required: "bar", additionalProperties: "bar"},\n url: "https://example.com"\n)\n\nputs(response)', - }, - typescript: { - method: 'client.web.extract', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.extract({\n schema: {\n type: 'bar',\n properties: 'bar',\n required: 'bar',\n additionalProperties: 'bar',\n },\n url: 'https://example.com',\n});\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/extract \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "schema": {\n "type": "bar",\n "properties": "bar",\n "required": "bar",\n "additionalProperties": "bar"\n },\n "url": "https://example.com",\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, - { - name: 'extract_competitors', - endpoint: '/web/competitors', - httpMethod: 'get', - summary: 'Find website competitors', - description: - "Analyze a company's landing page and web search evidence to return direct competitors for the same product or market.", - stainlessPath: '(resource) web > (method) extract_competitors', - qualified: 'client.web.extractCompetitors', - params: ['domain: string;', 'numCompetitors?: number;', 'tags?: string[];', 'timeoutMS?: number;'], - response: - "{ competitors: { confidence: 'high' | 'medium'; description: string; domain: string; name: string; sourceUrls: string[]; url: string; }[]; domain: string; status: 'ok'; target: { companyName: string; field: string; fieldDescription: string; websiteUrl: string; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## extract_competitors\n\n`client.web.extractCompetitors(domain: string, numCompetitors?: number, tags?: string[], timeoutMS?: number): { competitors: object[]; domain: string; status: 'ok'; target: object; key_metadata?: object; }`\n\n**get** `/web/competitors`\n\nAnalyze a company's landing page and web search evidence to return direct competitors for the same product or market.\n\n### Parameters\n\n- `domain: string`\n Company domain to analyze, such as `stripe.com`. Full http(s) URLs are accepted and normalized to their domain.\n\n- `numCompetitors?: number`\n Exact number of direct competitors to return. Defaults to 5.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ competitors: { confidence: 'high' | 'medium'; description: string; domain: string; name: string; sourceUrls: string[]; url: string; }[]; domain: string; status: 'ok'; target: { companyName: string; field: string; fieldDescription: string; websiteUrl: string; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `competitors: { confidence: 'high' | 'medium'; description: string; domain: string; name: string; sourceUrls: string[]; url: string; }[]`\n - `domain: string`\n - `status: 'ok'`\n - `target: { companyName: string; field: string; fieldDescription: string; websiteUrl: string; }`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.extractCompetitors({ domain: 'xxx' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'web->extractCompetitors', - example: - "web->extractCompetitors(\n domain: 'xxx',\n numCompetitors: 1,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Web.ExtractCompetitors', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Web.ExtractCompetitors(context.TODO(), contextdev.WebExtractCompetitorsParams{\n\t\tDomain: "xxx",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Competitors)\n}\n', - }, - cli: { - method: 'web extract_competitors', - example: "context-dev web extract-competitors \\\n --api-key 'My API Key' \\\n --domain xxx", - }, - python: { - method: 'web.extract_competitors', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.web.extract_competitors(\n domain="xxx",\n)\nprint(response.competitors)', - }, - ruby: { - method: 'web.extract_competitors', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.web.extract_competitors(domain: "xxx")\n\nputs(response)', - }, - typescript: { - method: 'client.web.extractCompetitors', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.web.extractCompetitors({ domain: 'xxx' });\n\nconsole.log(response.competitors);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/competitors \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'extract_products', - endpoint: '/brand/ai/products', - httpMethod: 'post', - summary: "Extract products from a brand's website", - description: - "Extract product information from a brand's website. We will analyze the website and return a list of products with details such as name, description, image, pricing, features, and more.", - stainlessPath: '(resource) ai > (method) extract_products', - qualified: 'client.ai.extractProducts', - params: [ - '{ domain: string; maxAgeMs?: number; maxProducts?: number; tags?: string[]; timeoutMS?: number; } | { directUrl: string; maxAgeMs?: number; maxProducts?: number; tags?: string[]; timeoutMS?: number; };', - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; products?: { description: string; features: string[]; images: string[]; name: string; sku: string; tags: string[]; target_audience: string[]; availability?: string; billing_frequency?: 'monthly' | 'yearly' | 'one_time' | 'usage_based'; category?: string; currency?: string; dimensions?: string[]; image_url?: string; price?: number; pricing_model?: 'per_seat' | 'flat' | 'tiered' | 'freemium' | 'custom'; regular_price?: number; url?: string; }[]; }", - perLanguage: { - php: { - method: 'ai->extractProducts', - example: - "ai->extractProducts(\n domain: 'domain',\n maxAgeMs: 0,\n maxProducts: 1,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n directURL: 'https://example.com',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.AI.ExtractProducts', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.AI.ExtractProducts(context.TODO(), contextdev.AIExtractProductsParams{\n\t\tOfByDomain: &contextdev.AIExtractProductsParamsBodyByDomain{\n\t\t\tDomain: "domain",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'ai extract_products', - example: - "context-dev ai extract-products \\\n --api-key 'My API Key' \\\n --domain domain \\\n --direct-url https://example.com", - }, - python: { - method: 'ai.extract_products', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.ai.extract_products(\n domain="domain",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'ai.extract_products', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.ai.extract_products(body: {domain: "domain"})\n\nputs(response)', - }, - typescript: { - method: 'client.ai.extractProducts', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.ai.extractProducts({ domain: 'domain' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/brand/ai/products \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "domain": "domain",\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, - { - name: 'extract_product', - endpoint: '/brand/ai/product', - httpMethod: 'post', - summary: 'Extract a single product from a URL', - description: - 'Given a single URL, determines if it is a product page and extracts the product information.', - stainlessPath: '(resource) ai > (method) extract_product', - qualified: 'client.ai.extractProduct', - params: ['url: string;', 'maxAgeMs?: number;', 'tags?: string[];', 'timeoutMS?: number;'], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; is_product_page?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; platform?: 'amazon' | 'tiktok_shop' | 'etsy' | 'generic'; product?: { description: string; features: string[]; images: string[]; name: string; sku: string; tags: string[]; target_audience: string[]; availability?: string; billing_frequency?: 'monthly' | 'yearly' | 'one_time' | 'usage_based'; category?: string; currency?: string; dimensions?: string[]; image_url?: string; price?: number; pricing_model?: 'per_seat' | 'flat' | 'tiered' | 'freemium' | 'custom'; regular_price?: number; url?: string; }; }", - markdown: - "## extract_product\n\n`client.ai.extractProduct(url: string, maxAgeMs?: number, tags?: string[], timeoutMS?: number): { cache_metadata: object; is_product_page?: boolean; key_metadata?: object; platform?: 'amazon' | 'tiktok_shop' | 'etsy' | 'generic'; product?: object; }`\n\n**post** `/brand/ai/product`\n\nGiven a single URL, determines if it is a product page and extracts the product information.\n\n### Parameters\n\n- `url: string`\n The product page URL to extract product data from.\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 7 days (604800000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; is_product_page?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; platform?: 'amazon' | 'tiktok_shop' | 'etsy' | 'generic'; product?: { description: string; features: string[]; images: string[]; name: string; sku: string; tags: string[]; target_audience: string[]; availability?: string; billing_frequency?: 'monthly' | 'yearly' | 'one_time' | 'usage_based'; category?: string; currency?: string; dimensions?: string[]; image_url?: string; price?: number; pricing_model?: 'per_seat' | 'flat' | 'tiered' | 'freemium' | 'custom'; regular_price?: number; url?: string; }; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `is_product_page?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `platform?: 'amazon' | 'tiktok_shop' | 'etsy' | 'generic'`\n - `product?: { description: string; features: string[]; images: string[]; name: string; sku: string; tags: string[]; target_audience: string[]; availability?: string; billing_frequency?: 'monthly' | 'yearly' | 'one_time' | 'usage_based'; category?: string; currency?: string; dimensions?: string[]; image_url?: string; price?: number; pricing_model?: 'per_seat' | 'flat' | 'tiered' | 'freemium' | 'custom'; regular_price?: number; url?: string; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.ai.extractProduct({ url: 'https://example.com' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'ai->extractProduct', - example: - "ai->extractProduct(\n url: 'https://example.com',\n maxAgeMs: 0,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.AI.ExtractProduct', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.AI.ExtractProduct(context.TODO(), contextdev.AIExtractProductParams{\n\t\tURL: "https://example.com",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'ai extract_product', - example: - "context-dev ai extract-product \\\n --api-key 'My API Key' \\\n --url https://example.com", - }, - python: { - method: 'ai.extract_product', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.ai.extract_product(\n url="https://example.com",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'ai.extract_product', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.ai.extract_product(url: "https://example.com")\n\nputs(response)', - }, - typescript: { - method: 'client.ai.extractProduct', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.ai.extractProduct({ url: 'https://example.com' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/brand/ai/product \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "url": "https://example.com",\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, - { - name: 'retrieve', - endpoint: '/brand/retrieve', - httpMethod: 'post', - summary: 'Retrieve brand data', - description: - 'Retrieve logos, backdrops, colors, industry, description, and more. Provide exactly one lookup identifier in the request body: a domain, company name, email address, stock ticker, transaction descriptor, or direct URL. Note: `by_direct_url` fetches brand data only from the provided URL — not from the entire internet.', - stainlessPath: '(resource) brand > (method) retrieve', - qualified: 'client.brand.retrieve', - params: [ - "{ domain: string; type: 'by_domain'; force_language?: string; maxAgeMs?: number; maxSpeed?: boolean; tags?: string[]; timeoutMS?: number; } | { name: string; type: 'by_name'; country_gl?: string; force_language?: string; maxAgeMs?: number; maxSpeed?: boolean; tags?: string[]; timeoutMS?: number; } | { email: string; type: 'by_email'; force_language?: string; maxAgeMs?: number; maxSpeed?: boolean; tags?: string[]; timeoutMS?: number; } | { ticker: string; type: 'by_ticker'; force_language?: string; maxAgeMs?: number; maxSpeed?: boolean; tags?: string[]; ticker_exchange?: string; timeoutMS?: number; } | { direct_url: string; type: 'by_direct_url'; tags?: string[]; timeoutMS?: number; } | { transaction_info: string; type: 'by_transaction'; city?: string; country_gl?: string; force_language?: string; high_confidence_only?: boolean; maxSpeed?: boolean; mcc?: string | number; phone?: string | number; tags?: string[]; timeoutMS?: number; };", - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; brand?: { address?: { city?: string; country?: string; country_code?: string; postal_code?: string; state_code?: string; state_province?: string; street?: string; }; backdrops?: { colors?: object[]; resolution?: object; url?: string; }[]; colors?: { hex?: string; name?: string; source?: 'site' | 'logo'; }[]; description?: string; domain?: string; email?: string; employees?: { exact?: number; range?: string; }; industries?: { eic?: object[]; }; is_nsfw?: boolean; links?: { blog?: string; careers?: string; contact?: string; pricing?: string; privacy?: string; terms?: string; }; logos?: { colors?: object[]; mode?: 'light' | 'dark' | 'has_opaque_background'; resolution?: object; type?: 'icon' | 'logo'; url?: string; }[]; phone?: string; primary_language?: string; slogan?: string; socials?: { type?: string; url?: string; }[]; stock?: { exchange?: string; ticker?: string; }; title?: string; }; code?: number; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; }", - perLanguage: { - php: { - method: 'brand->retrieve', - example: - "brand->retrieve(\n domain: 'xxx',\n type: 'by_transaction',\n forceLanguage: 'afrikaans',\n maxAgeMs: 0,\n maxSpeed: true,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n name: 'xxx',\n countryGl: 'country_gl',\n email: 'dev@stainless.com',\n ticker: 'ticker',\n tickerExchange: 'ticker_exchange',\n directURL: 'https://example.com',\n transactionInfo: 'xxx',\n city: 'city',\n highConfidenceOnly: true,\n mcc: 'string',\n phone: 'string',\n);\n\nvar_dump($brand);", - }, - go: { - method: 'client.Brand.Get', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tbrand, err := client.Brand.Get(context.TODO(), contextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", brand.CacheMetadata)\n}\n', - }, - cli: { - method: 'brand retrieve', - example: - "context-dev brand retrieve \\\n --api-key 'My API Key' \\\n --domain xxx \\\n --type by_domain \\\n --name xxx \\\n --email dev@stainless.com \\\n --ticker ticker \\\n --direct-url https://example.com \\\n --transaction-info xxx", - }, - python: { - method: 'brand.retrieve', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nbrand = client.brand.retrieve(\n domain="stripe.com",\n type="by_domain",\n)\nprint(brand.cache_metadata)', - }, - ruby: { - method: 'brand.retrieve', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nbrand = context_dev.brand.retrieve(body: {domain: "stripe.com", type: :by_domain})\n\nputs(brand)', - }, - typescript: { - method: 'client.brand.retrieve', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst brand = await client.brand.retrieve({ domain: 'stripe.com', type: 'by_domain' });\n\nconsole.log(brand.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/brand/retrieve \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "domain": "xxx",\n "type": "by_domain",\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, - { - name: 'search', - endpoint: '/brand/search', - httpMethod: 'get', - summary: 'Brand Search', - description: 'Search indexed brands by name or domain', - stainlessPath: '(resource) brand > (method) search', - qualified: 'client.brand.search', - params: [ - 'query: string;', - 'autocomplete?: boolean;', - "queryBy?: 'name' | 'domain'[];", - 'tags?: string[];', - 'typoTolerance?: number;', - ], - response: - '{ results: { domain: string; logo: string; name: string; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }', - markdown: - "## search\n\n`client.brand.search(query: string, autocomplete?: boolean, queryBy?: 'name' | 'domain'[], tags?: string[], typoTolerance?: number): { results: object[]; key_metadata?: object; }`\n\n**get** `/brand/search`\n\nSearch indexed brands by name or domain\n\n### Parameters\n\n- `query: string`\n Search term, matched against the fields selected by queryBy (e.g. 'nike', 'nike.com', 'nik').\n\n- `autocomplete?: boolean`\n Whether the search term matches by prefix, so partial words match as they are typed (e.g. 'nik' matches Nike). Set to false to match whole words only.\n\n- `queryBy?: 'name' | 'domain'[]`\n Fields to match the search term against, as a comma-separated list or repeated parameter: 'name', 'domain', or both. Defaults to both.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `typoTolerance?: number`\n Maximum number of typos tolerated when matching, from 0 to 2. Defaults to 0 (no typo tolerance).\n\n### Returns\n\n- `{ results: { domain: string; logo: string; name: string; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `results: { domain: string; logo: string; name: string; }[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.brand.search({ query: 'x' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'brand->search', - example: - "brand->search(\n query: 'x',\n autocomplete: true,\n queryBy: ['name'],\n tags: ['production', 'team-alpha'],\n typoTolerance: 0,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Brand.Search', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Brand.Search(context.TODO(), contextdev.BrandSearchParams{\n\t\tQuery: "x",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Results)\n}\n', - }, - cli: { - method: 'brand search', - example: "context-dev brand search \\\n --api-key 'My API Key' \\\n --query x", - }, - python: { - method: 'brand.search', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.brand.search(\n query="x",\n)\nprint(response.results)', - }, - ruby: { - method: 'brand.search', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.brand.search(query: "x")\n\nputs(response)', - }, - typescript: { - method: 'client.brand.search', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.brand.search({ query: 'x' });\n\nconsole.log(response.results);", - }, - http: { - example: - 'curl https://api.context.dev/v1/brand/search \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'retrieve_simplified', - endpoint: '/brand/retrieve-simplified', - httpMethod: 'get', - summary: 'Retrieve simplified brand data by domain', - description: - 'Returns a simplified version of brand data containing only essential information: domain, title, colors, logos, and backdrops. Optimized for faster responses and reduced data transfer.', - stainlessPath: '(resource) brand > (method) retrieve_simplified', - qualified: 'client.brand.retrieveSimplified', - params: [ - 'domain: string;', - 'maxAgeMs?: number;', - 'tags?: string[];', - "theme?: 'light' | 'dark';", - 'timeoutMS?: number;', - ], - response: - "{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; brand?: { backdrops?: { colors?: object[]; resolution?: object; url?: string; }[]; colors?: { hex?: string; name?: string; source?: 'site' | 'logo'; }[]; domain?: string; logos?: { colors?: object[]; mode?: 'light' | 'dark' | 'has_opaque_background'; resolution?: object; type?: 'icon' | 'logo'; url?: string; }[]; title?: string; }; code?: number; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; }", - markdown: - "## retrieve_simplified\n\n`client.brand.retrieveSimplified(domain: string, maxAgeMs?: number, tags?: string[], theme?: 'light' | 'dark', timeoutMS?: number): { cache_metadata: object; brand?: object; code?: number; key_metadata?: object; status?: string; }`\n\n**get** `/brand/retrieve-simplified`\n\nReturns a simplified version of brand data containing only essential information: domain, title, colors, logos, and backdrops. Optimized for faster responses and reduced data transfer.\n\n### Parameters\n\n- `domain: string`\n Domain name to retrieve simplified brand data for\n\n- `maxAgeMs?: number`\n Maximum age in milliseconds for cached brand data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 year.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `theme?: 'light' | 'dark'`\n Optional theme preference used when selecting brand assets.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; brand?: { backdrops?: { colors?: object[]; resolution?: object; url?: string; }[]; colors?: { hex?: string; name?: string; source?: 'site' | 'logo'; }[]; domain?: string; logos?: { colors?: object[]; mode?: 'light' | 'dark' | 'has_opaque_background'; resolution?: object; type?: 'icon' | 'logo'; url?: string; }[]; title?: string; }; code?: number; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; }`\n\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `brand?: { backdrops?: { colors?: { hex?: string; name?: string; }[]; resolution?: { aspect_ratio?: number; height?: number; width?: number; }; url?: string; }[]; colors?: { hex?: string; name?: string; source?: 'site' | 'logo'; }[]; domain?: string; logos?: { colors?: { hex?: string; name?: string; }[]; mode?: 'light' | 'dark' | 'has_opaque_background'; resolution?: { aspect_ratio?: number; height?: number; width?: number; }; type?: 'icon' | 'logo'; url?: string; }[]; title?: string; }`\n - `code?: number`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `status?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.brand.retrieveSimplified({ domain: 'xxx' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'brand->retrieveSimplified', - example: - "brand->retrieveSimplified(\n domain: 'xxx',\n maxAgeMs: 0,\n tags: ['production', 'team-alpha'],\n theme: 'light',\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Brand.GetSimplified', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Brand.GetSimplified(context.TODO(), contextdev.BrandGetSimplifiedParams{\n\t\tDomain: "xxx",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.CacheMetadata)\n}\n', - }, - cli: { - method: 'brand retrieve_simplified', - example: "context-dev brand retrieve-simplified \\\n --api-key 'My API Key' \\\n --domain xxx", - }, - python: { - method: 'brand.retrieve_simplified', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.brand.retrieve_simplified(\n domain="xxx",\n)\nprint(response.cache_metadata)', - }, - ruby: { - method: 'brand.retrieve_simplified', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.brand.retrieve_simplified(domain: "xxx")\n\nputs(response)', - }, - typescript: { - method: 'client.brand.retrieveSimplified', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.brand.retrieveSimplified({ domain: 'xxx' });\n\nconsole.log(response.cache_metadata);", - }, - http: { - example: - 'curl https://api.context.dev/v1/brand/retrieve-simplified \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'retrieve_naics', - endpoint: '/web/naics', - httpMethod: 'get', - summary: 'Classify NAICS industries', - description: 'Classify any brand into 2022 NAICS industry codes from its domain or name.', - stainlessPath: '(resource) industry > (method) retrieve_naics', - qualified: 'client.industry.retrieveNaics', - params: [ - 'input: string;', - 'maxResults?: number;', - 'minResults?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - ], - response: - "{ codes?: { code: string; confidence: 'high' | 'medium' | 'low'; name: string; }[]; domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; type?: string; }", - markdown: - "## retrieve_naics\n\n`client.industry.retrieveNaics(input: string, maxResults?: number, minResults?: number, tags?: string[], timeoutMS?: number): { codes?: object[]; domain?: string; key_metadata?: object; status?: string; type?: string; }`\n\n**get** `/web/naics`\n\nClassify any brand into 2022 NAICS industry codes from its domain or name.\n\n### Parameters\n\n- `input: string`\n Brand domain or title to retrieve NAICS code for. If a valid domain is provided, it will be used for classification, otherwise, we will search for the brand using the provided title.\n\n- `maxResults?: number`\n Maximum number of NAICS codes to return. Must be between 1 and 10. Defaults to 5.\n\n- `minResults?: number`\n Minimum number of NAICS codes to return. Must be at least 1. Defaults to 1.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ codes?: { code: string; confidence: 'high' | 'medium' | 'low'; name: string; }[]; domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; type?: string; }`\n\n - `codes?: { code: string; confidence: 'high' | 'medium' | 'low'; name: string; }[]`\n - `domain?: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `status?: string`\n - `type?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.industry.retrieveNaics({ input: 'xxxx' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'industry->retrieveNaics', - example: - "industry->retrieveNaics(\n input: 'xxxx',\n maxResults: 1,\n minResults: 1,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Industry.GetNaics', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Industry.GetNaics(context.TODO(), contextdev.IndustryGetNaicsParams{\n\t\tInput: "xxxx",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Codes)\n}\n', - }, - cli: { - method: 'industry retrieve_naics', - example: "context-dev industry retrieve-naics \\\n --api-key 'My API Key' \\\n --input xxxx", - }, - python: { - method: 'industry.retrieve_naics', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.industry.retrieve_naics(\n input="xxxx",\n)\nprint(response.codes)', - }, - ruby: { - method: 'industry.retrieve_naics', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.industry.retrieve_naics(input: "xxxx")\n\nputs(response)', - }, - typescript: { - method: 'client.industry.retrieveNaics', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.industry.retrieveNaics({ input: 'xxxx' });\n\nconsole.log(response.codes);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/naics \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'retrieve_sic', - endpoint: '/web/sic', - httpMethod: 'get', - summary: 'Classify SIC industries', - description: - 'Classify any brand into Standard Industrial Classification (SIC) codes from its domain or name. Choose between the original SIC system (`original_sic`) or the latest SIC list maintained by the SEC (`latest_sec`).', - stainlessPath: '(resource) industry > (method) retrieve_sic', - qualified: 'client.industry.retrieveSic', - params: [ - 'input: string;', - 'maxResults?: number;', - 'minResults?: number;', - 'tags?: string[];', - 'timeoutMS?: number;', - "type?: 'original_sic' | 'latest_sec';", - ], - response: - "{ classification?: 'original_sic' | 'latest_sec'; codes?: { code: string; confidence: 'high' | 'medium' | 'low'; name: string; majorGroup?: string; majorGroupName?: string; office?: string; }[]; domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; type?: string; }", - markdown: - "## retrieve_sic\n\n`client.industry.retrieveSic(input: string, maxResults?: number, minResults?: number, tags?: string[], timeoutMS?: number, type?: 'original_sic' | 'latest_sec'): { classification?: 'original_sic' | 'latest_sec'; codes?: object[]; domain?: string; key_metadata?: object; status?: string; type?: string; }`\n\n**get** `/web/sic`\n\nClassify any brand into Standard Industrial Classification (SIC) codes from its domain or name. Choose between the original SIC system (`original_sic`) or the latest SIC list maintained by the SEC (`latest_sec`).\n\n### Parameters\n\n- `input: string`\n Brand domain or title to retrieve SIC code for. If a valid domain is provided, it will be used for classification, otherwise, we will search for the brand using the provided title.\n\n- `maxResults?: number`\n Maximum number of SIC codes to return. Must be between 1 and 10. Defaults to 5.\n\n- `minResults?: number`\n Minimum number of SIC codes to return. Must be at least 1. Defaults to 1.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `type?: 'original_sic' | 'latest_sec'`\n Which SIC dataset to classify against. `original_sic` uses the 1987 Standard Industrial Classification system; `latest_sec` uses the current SIC list as published by the SEC. Defaults to `original_sic`.\n\n### Returns\n\n- `{ classification?: 'original_sic' | 'latest_sec'; codes?: { code: string; confidence: 'high' | 'medium' | 'low'; name: string; majorGroup?: string; majorGroupName?: string; office?: string; }[]; domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; status?: string; type?: string; }`\n\n - `classification?: 'original_sic' | 'latest_sec'`\n - `codes?: { code: string; confidence: 'high' | 'medium' | 'low'; name: string; majorGroup?: string; majorGroupName?: string; office?: string; }[]`\n - `domain?: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `status?: string`\n - `type?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.industry.retrieveSic({ input: 'xxxx' });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'industry->retrieveSic', - example: - "industry->retrieveSic(\n input: 'xxxx',\n maxResults: 1,\n minResults: 1,\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n type: 'original_sic',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Industry.GetSic', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Industry.GetSic(context.TODO(), contextdev.IndustryGetSicParams{\n\t\tInput: "xxxx",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Classification)\n}\n', - }, - cli: { - method: 'industry retrieve_sic', - example: "context-dev industry retrieve-sic \\\n --api-key 'My API Key' \\\n --input xxxx", - }, - python: { - method: 'industry.retrieve_sic', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.industry.retrieve_sic(\n input="xxxx",\n)\nprint(response.classification)', - }, - ruby: { - method: 'industry.retrieve_sic', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.industry.retrieve_sic(input: "xxxx")\n\nputs(response)', - }, - typescript: { - method: 'client.industry.retrieveSic', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.industry.retrieveSic({ input: 'xxxx' });\n\nconsole.log(response.classification);", - }, - http: { - example: - 'curl https://api.context.dev/v1/web/sic \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'prefetch', - endpoint: '/utility/prefetch', - httpMethod: 'post', - summary: 'Prefetch data', - description: - "Signal that you may fetch data soon to improve latency. The type field selects what to prefetch ('brand' queues a brand data fetch, 'styleguide' queues a styleguide extraction) and identifier carries exactly one lookup key: a domain, or an email whose domain is extracted and validated (free email providers and disposable email addresses are not allowed).", - stainlessPath: '(resource) utility > (method) prefetch', - qualified: 'client.utility.prefetch', - params: [ - 'identifier: { domain: string; } | { email: string; };', - "type: 'brand' | 'styleguide';", - 'tags?: string[];', - 'timeoutMS?: number;', - ], - response: - "{ domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; message?: string; status?: string; type?: 'brand' | 'styleguide'; }", - markdown: - "## prefetch\n\n`client.utility.prefetch(identifier: { domain: string; } | { email: string; }, type: 'brand' | 'styleguide', tags?: string[], timeoutMS?: number): { domain?: string; key_metadata?: object; message?: string; status?: string; type?: 'brand' | 'styleguide'; }`\n\n**post** `/utility/prefetch`\n\nSignal that you may fetch data soon to improve latency. The type field selects what to prefetch ('brand' queues a brand data fetch, 'styleguide' queues a styleguide extraction) and identifier carries exactly one lookup key: a domain, or an email whose domain is extracted and validated (free email providers and disposable email addresses are not allowed).\n\n### Parameters\n\n- `identifier: { domain: string; } | { email: string; }`\n Identifier of the target to prefetch. Provide exactly one of domain or email.\n\n- `type: 'brand' | 'styleguide'`\n What to prefetch: 'brand' warms the brand data cache, 'styleguide' warms the styleguide cache.\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; message?: string; status?: string; type?: 'brand' | 'styleguide'; }`\n\n - `domain?: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `message?: string`\n - `status?: string`\n - `type?: 'brand' | 'styleguide'`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.utility.prefetch({\n identifier: { domain: 'xxx' },\n type: 'brand',\n});\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'utility->prefetch', - example: - "utility->prefetch(\n identifier: ['domain' => 'xxx'],\n type: 'brand',\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Utility.Prefetch', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Utility.Prefetch(context.TODO(), contextdev.UtilityPrefetchParams{\n\t\tIdentifier: contextdev.UtilityPrefetchParamsIdentifierUnion{\n\t\t\tOfByDomain: &contextdev.UtilityPrefetchParamsIdentifierByDomain{\n\t\t\t\tDomain: "xxx",\n\t\t\t},\n\t\t},\n\t\tType: contextdev.UtilityPrefetchParamsTypeBrand,\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Domain)\n}\n', - }, - cli: { - method: 'utility prefetch', - example: - "context-dev utility prefetch \\\n --api-key 'My API Key' \\\n --identifier '{domain: xxx}' \\\n --type brand", - }, - python: { - method: 'utility.prefetch', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.utility.prefetch(\n identifier={\n "domain": "xxx"\n },\n type="brand",\n)\nprint(response.domain)', - }, - ruby: { - method: 'utility.prefetch', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.utility.prefetch(identifier: {domain: "xxx"}, type: :brand)\n\nputs(response)', - }, - typescript: { - method: 'client.utility.prefetch', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.utility.prefetch({\n identifier: { domain: 'xxx' },\n type: 'brand',\n});\n\nconsole.log(response.domain);", - }, - http: { - example: - 'curl https://api.context.dev/v1/utility/prefetch \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "identifier": {\n "domain": "xxx"\n },\n "type": "brand",\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, - { - name: 'create', - endpoint: '/monitors', - httpMethod: 'post', - summary: 'Create a monitor', - description: - 'Creates a monitor. The request body is a union of the supported target/change detection combinations. The monitor runs immediately after creation to create its initial baseline.', - stainlessPath: '(resource) monitors > (method) create', - qualified: 'client.monitors.create', - params: [ - 'name: string;', - "target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; };", - "change_detection?: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; };", - "mode?: 'web';", - "schedule?: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; };", - 'tags?: string[];', - "webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; };", - ], - response: - "{ id: string; change_detection: object | object; created_at: string; initial_run_id: string; mode: 'web'; name: string; schedule: object; status: 'active' | 'paused' | 'failed'; target: object | object | object; updated_at: string; baseline?: object | object | object; last_change_at?: string; last_error?: object; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: object; webhook_failure?: object; }", - markdown: - "## create\n\n`client.monitors.create(name: string, target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }, change_detection?: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }, mode?: 'web', schedule?: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }, tags?: string[], webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }): { id: string; change_detection: object | object; created_at: string; initial_run_id: string; mode: 'web'; name: string; schedule: object; status: 'active' | 'paused' | 'failed'; target: object | object | object; updated_at: string; baseline?: object | object | object; last_change_at?: string; last_error?: object; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: object; webhook_failure?: object; }`\n\n**post** `/monitors`\n\nCreates a monitor. The request body is a union of the supported target/change detection combinations. The monitor runs immediately after creation to create its initial baseline.\n\n### Parameters\n\n- `name: string`\n\n- `target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }`\n Discriminated union describing what the monitor watches.\n\n- `change_detection?: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }`\n Discriminated union describing how changes are detected.\n\n- `mode?: 'web'`\n Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`.\n\n- `schedule?: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }`\n Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.\n - `frequency: number`\n Number of units between runs. The resulting interval (frequency × unit) must be at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; maximum 365 when unit is days).\n - `type: 'interval'`\n - `unit: 'minutes' | 'hours' | 'days'`\n\n- `tags?: string[]`\n User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.\n\n- `webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }`\n - `url: string`\n Webhook URL events are delivered to.\n - `events?: 'change.detected' | 'run.completed'[]`\n Events delivered to this endpoint. `change.detected` fires only when a run detects a change; `run.completed` fires on every completed run — including runs that detected no change — and embeds the change when one was detected. Defaults to `[\"change.detected\"]` when omitted.\n - `secret?: string`\n Signing secret used to verify webhook authenticity. Each delivery includes an `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over `\"{t}.{rawRequestBody}\"` keyed by this secret. Recompute it with a constant-time compare and reject stale timestamps to prevent replay. Generated by the API; cannot be set by clients.\n\n### Returns\n\n- `{ id: string; change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }; created_at: string; initial_run_id: string; mode: 'web'; name: string; schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }; status: 'active' | 'paused' | 'failed'; target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }; updated_at: string; baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }; last_change_at?: string; last_error?: { code: string; message: string; }; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }; webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }; }`\n A newly created monitor plus `initial_run_id`, the id of the baseline run queued at creation.\n\n - `id: string`\n - `change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }`\n - `created_at: string`\n - `initial_run_id: string`\n - `mode: 'web'`\n - `name: string`\n - `schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }`\n - `status: 'active' | 'paused' | 'failed'`\n - `target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }`\n - `updated_at: string`\n - `baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }`\n - `last_change_at?: string`\n - `last_error?: { code: string; message: string; }`\n - `last_run_at?: string`\n - `next_run_at?: string`\n - `tags?: string[]`\n - `webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }`\n - `webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst monitor = await client.monitors.create({\n name: 'Acme pricing page',\n target: { type: 'page', url: 'https://acme.com/pricing' },\n});\n\nconsole.log(monitor);\n```", - perLanguage: { - php: { - method: 'monitors->create', - example: - "monitors->create(\n name: 'Acme pricing page',\n target: [\n 'type' => 'page',\n 'url' => 'https://acme.com/pricing',\n 'instructions' => 'Report pricing or plan availability changes. Ignore counters, timestamps, testimonials, and navigation.',\n 'normalizeWhitespace' => true,\n ],\n changeDetection: ['type' => 'exact'],\n mode: 'web',\n schedule: ['frequency' => 6, 'type' => 'interval', 'unit' => 'hours'],\n tags: ['pricing', 'competitor'],\n webhook: [\n 'url' => 'https://example.com/webhook',\n 'events' => ['change.detected', 'run.completed'],\n ],\n);\n\nvar_dump($monitor);", - }, - go: { - method: 'client.Monitors.New', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tmonitor, err := client.Monitors.New(context.TODO(), contextdev.MonitorNewParams{\n\t\tName: "Acme pricing page",\n\t\tTarget: contextdev.MonitorNewParamsTargetUnion{\n\t\t\tOfPage: &contextdev.MonitorNewParamsTargetPage{\n\t\t\t\tURL: "https://acme.com/pricing",\n\t\t\t},\n\t\t},\n\t\tChangeDetection: contextdev.MonitorNewParamsChangeDetectionUnion{\n\t\t\tOfExact: &contextdev.MonitorNewParamsChangeDetectionExact{},\n\t\t},\n\t\tMode: contextdev.MonitorNewParamsModeWeb,\n\t\tSchedule: contextdev.MonitorNewParamsSchedule{\n\t\t\tType: "interval",\n\t\t\tFrequency: 6,\n\t\t\tUnit: "hours",\n\t\t},\n\t\tWebhook: contextdev.MonitorNewParamsWebhook{\n\t\t\tURL: "https://example.com/webhook",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", monitor.ID)\n}\n', - }, - cli: { - method: 'monitors create', - example: - "context-dev monitors create \\\n --api-key 'My API Key' \\\n --name 'Acme pricing page' \\\n --target '{type: page, url: https://acme.com/pricing}'", - }, - python: { - method: 'monitors.create', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nmonitor = client.monitors.create(\n name="Acme pricing page",\n target={\n "type": "page",\n "url": "https://acme.com/pricing",\n },\n change_detection={\n "type": "exact"\n },\n mode="web",\n schedule={\n "type": "interval",\n "frequency": 6,\n "unit": "hours",\n },\n webhook={\n "url": "https://example.com/webhook"\n },\n)\nprint(monitor.id)', - }, - ruby: { - method: 'monitors.create', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nmonitor = context_dev.monitors.create(\n name: "Acme pricing page",\n target: {type: :page, url: "https://acme.com/pricing"}\n)\n\nputs(monitor)', - }, - typescript: { - method: 'client.monitors.create', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst monitor = await client.monitors.create({\n name: 'Acme pricing page',\n target: { type: 'page', url: 'https://acme.com/pricing' },\n change_detection: { type: 'exact' },\n mode: 'web',\n schedule: {\n type: 'interval',\n frequency: 6,\n unit: 'hours',\n },\n webhook: { url: 'https://example.com/webhook' },\n});\n\nconsole.log(monitor.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "name": "Acme pricing page",\n "target": {\n "type": "page",\n "url": "https://acme.com/pricing"\n },\n "change_detection": {\n "type": "exact"\n },\n "mode": "web",\n "schedule": {\n "frequency": 6,\n "type": "interval",\n "unit": "hours"\n },\n "tags": [\n "pricing",\n "competitor"\n ],\n "webhook": {\n "url": "https://example.com/webhook"\n }\n }\'', - }, - }, - }, - { - name: 'list', - endpoint: '/monitors', - httpMethod: 'get', - summary: 'List monitors', - description: - 'Lists monitors for the authenticated organization. Supports free-text search (`q` over `search_by` fields, `prefix` or `exact` via `search_type`) plus status/type/tag filters. Results are paginated via the opaque `cursor`.', - stainlessPath: '(resource) monitors > (method) list', - qualified: 'client.monitors.list', - params: [ - "change_detection_type?: 'exact' | 'semantic';", - 'cursor?: string;', - 'limit?: number;', - 'q?: string;', - "search_by?: 'name' | 'url' | 'instructions' | 'tags'[];", - "search_type?: 'exact' | 'prefix';", - "status?: 'active' | 'paused' | 'failed';", - 'tag?: string;', - 'tags?: string[];', - "target_type?: 'page' | 'sitemap' | 'extract';", - ], - response: - "{ data: { id: string; change_detection: object | object; created_at: string; mode: 'web'; name: string; schedule: object; status: 'active' | 'paused' | 'failed'; target: object | object | object; updated_at: string; baseline?: object | object | object; last_change_at?: string; last_error?: object; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: object; webhook_failure?: object; }[]; has_more: boolean; next_cursor: string; }", - markdown: - "## list\n\n`client.monitors.list(change_detection_type?: 'exact' | 'semantic', cursor?: string, limit?: number, q?: string, search_by?: 'name' | 'url' | 'instructions' | 'tags'[], search_type?: 'exact' | 'prefix', status?: 'active' | 'paused' | 'failed', tag?: string, tags?: string[], target_type?: 'page' | 'sitemap' | 'extract'): { data: object[]; has_more: boolean; next_cursor: string; }`\n\n**get** `/monitors`\n\nLists monitors for the authenticated organization. Supports free-text search (`q` over `search_by` fields, `prefix` or `exact` via `search_type`) plus status/type/tag filters. Results are paginated via the opaque `cursor`.\n\n### Parameters\n\n- `change_detection_type?: 'exact' | 'semantic'`\n Filter by change detection type.\n\n- `cursor?: string`\n Opaque pagination cursor from a previous response.\n\n- `limit?: number`\n Maximum number of items to return per page (1-100). Defaults to 25.\n\n- `q?: string`\n Free-text search term, matched against the fields named in `search_by`.\n\n- `search_by?: 'name' | 'url' | 'instructions' | 'tags'[]`\n Comma-separated fields to search with `q`. Defaults to all of them. Note `instructions` only exists on extract monitors.\n\n- `search_type?: 'exact' | 'prefix'`\n `prefix` for as-you-type prefix matching (default), `exact` for full-token matching.\n\n- `status?: 'active' | 'paused' | 'failed'`\n Filter monitors by lifecycle status.\n\n- `tag?: string`\n Filter to items that have this tag.\n\n- `tags?: string[]`\n Comma-separated list of tags to filter by (matches monitors having any of them).\n\n- `target_type?: 'page' | 'sitemap' | 'extract'`\n Filter by target type.\n\n### Returns\n\n- `{ data: { id: string; change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }; created_at: string; mode: 'web'; name: string; schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }; status: 'active' | 'paused' | 'failed'; target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }; updated_at: string; baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }; last_change_at?: string; last_error?: { code: string; message: string; }; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }; webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }; }[]; has_more: boolean; next_cursor: string; }`\n\n - `data: { id: string; change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }; created_at: string; mode: 'web'; name: string; schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }; status: 'active' | 'paused' | 'failed'; target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }; updated_at: string; baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }; last_change_at?: string; last_error?: { code: string; message: string; }; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }; webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }; }[]`\n - `has_more: boolean`\n - `next_cursor: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst monitors = await client.monitors.list();\n\nconsole.log(monitors);\n```", - perLanguage: { - php: { - method: 'monitors->list', - example: - "monitors->list(\n changeDetectionType: 'exact',\n cursor: 'cursor',\n limit: 1,\n q: 'pricing',\n searchBy: ['name'],\n searchType: 'exact',\n status: 'active',\n tag: 'pricing',\n tags: ['x'],\n targetType: 'page',\n);\n\nvar_dump($monitors);", - }, - go: { - method: 'client.Monitors.List', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tmonitors, err := client.Monitors.List(context.TODO(), contextdev.MonitorListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", monitors.Data)\n}\n', - }, - cli: { - method: 'monitors list', - example: "context-dev monitors list \\\n --api-key 'My API Key'", - }, - python: { - method: 'monitors.list', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nmonitors = client.monitors.list()\nprint(monitors.data)', - }, - ruby: { - method: 'monitors.list', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nmonitors = context_dev.monitors.list\n\nputs(monitors)', - }, - typescript: { - method: 'client.monitors.list', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst monitors = await client.monitors.list();\n\nconsole.log(monitors.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'retrieve', - endpoint: '/monitors/{monitor_id}', - httpMethod: 'get', - summary: 'Get a monitor', - description: 'Get a monitor', - stainlessPath: '(resource) monitors > (method) retrieve', - qualified: 'client.monitors.retrieve', - params: ['monitor_id: string;'], - response: - "{ id: string; change_detection: object | object; created_at: string; mode: 'web'; name: string; schedule: object; status: 'active' | 'paused' | 'failed'; target: object | object | object; updated_at: string; baseline?: object | object | object; last_change_at?: string; last_error?: object; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: object; webhook_failure?: object; }", - markdown: - "## retrieve\n\n`client.monitors.retrieve(monitor_id: string): { id: string; change_detection: object | object; created_at: string; mode: 'web'; name: string; schedule: object; status: 'active' | 'paused' | 'failed'; target: object | object | object; updated_at: string; baseline?: object | object | object; last_change_at?: string; last_error?: object; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: object; webhook_failure?: object; }`\n\n**get** `/monitors/{monitor_id}`\n\nGet a monitor\n\n### Parameters\n\n- `monitor_id: string`\n\n### Returns\n\n- `{ id: string; change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }; created_at: string; mode: 'web'; name: string; schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }; status: 'active' | 'paused' | 'failed'; target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }; updated_at: string; baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }; last_change_at?: string; last_error?: { code: string; message: string; }; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }; webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }; }`\n A web monitor. `mode` is the constant `web`; behavior is described by `target` (page/sitemap/extract) and `change_detection` (exact/semantic).\n\n - `id: string`\n - `change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }`\n - `created_at: string`\n - `mode: 'web'`\n - `name: string`\n - `schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }`\n - `status: 'active' | 'paused' | 'failed'`\n - `target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }`\n - `updated_at: string`\n - `baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }`\n - `last_change_at?: string`\n - `last_error?: { code: string; message: string; }`\n - `last_run_at?: string`\n - `next_run_at?: string`\n - `tags?: string[]`\n - `webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }`\n - `webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst monitor = await client.monitors.retrieve('mon_123');\n\nconsole.log(monitor);\n```", - perLanguage: { - php: { - method: 'monitors->retrieve', - example: - "monitors->retrieve('mon_123');\n\nvar_dump($monitor);", - }, - go: { - method: 'client.Monitors.Get', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tmonitor, err := client.Monitors.Get(context.TODO(), "mon_123")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", monitor.ID)\n}\n', - }, - cli: { - method: 'monitors retrieve', - example: "context-dev monitors retrieve \\\n --api-key 'My API Key' \\\n --monitor-id mon_123", - }, - python: { - method: 'monitors.retrieve', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nmonitor = client.monitors.retrieve(\n "mon_123",\n)\nprint(monitor.id)', - }, - ruby: { - method: 'monitors.retrieve', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nmonitor = context_dev.monitors.retrieve("mon_123")\n\nputs(monitor)', - }, - typescript: { - method: 'client.monitors.retrieve', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst monitor = await client.monitors.retrieve('mon_123');\n\nconsole.log(monitor.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/$MONITOR_ID \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'update', - endpoint: '/monitors/{monitor_id}', - httpMethod: 'patch', - summary: 'Update a monitor', - description: - 'Updates a monitor. If `target` or `change_detection` changes, the monitor creates a new baseline. Unsupported target/change detection combinations are rejected.', - stainlessPath: '(resource) monitors > (method) update', - qualified: 'client.monitors.update', - params: [ - 'monitor_id: string;', - "change_detection?: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; };", - 'name?: string;', - "schedule?: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; };", - "status?: 'active' | 'paused';", - 'tags?: string[];', - "target?: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; };", - "webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; };", - ], - response: - "{ id: string; change_detection: object | object; created_at: string; mode: 'web'; name: string; schedule: object; status: 'active' | 'paused' | 'failed'; target: object | object | object; updated_at: string; baseline?: object | object | object; last_change_at?: string; last_error?: object; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: object; webhook_failure?: object; }", - markdown: - "## update\n\n`client.monitors.update(monitor_id: string, change_detection?: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }, name?: string, schedule?: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }, status?: 'active' | 'paused', tags?: string[], target?: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }, webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }): { id: string; change_detection: object | object; created_at: string; mode: 'web'; name: string; schedule: object; status: 'active' | 'paused' | 'failed'; target: object | object | object; updated_at: string; baseline?: object | object | object; last_change_at?: string; last_error?: object; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: object; webhook_failure?: object; }`\n\n**patch** `/monitors/{monitor_id}`\n\nUpdates a monitor. If `target` or `change_detection` changes, the monitor creates a new baseline. Unsupported target/change detection combinations are rejected.\n\n### Parameters\n\n- `monitor_id: string`\n\n- `change_detection?: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }`\n Discriminated union describing how changes are detected.\n\n- `name?: string`\n\n- `schedule?: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }`\n Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.\n - `frequency: number`\n Number of units between runs. The resulting interval (frequency × unit) must be at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; maximum 365 when unit is days).\n - `type: 'interval'`\n - `unit: 'minutes' | 'hours' | 'days'`\n\n- `status?: 'active' | 'paused'`\n\n- `tags?: string[]`\n User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.\n\n- `target?: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }`\n Discriminated union describing what the monitor watches.\n\n- `webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }`\n Set to null to remove the webhook.\n - `url: string`\n Webhook URL events are delivered to.\n - `events?: 'change.detected' | 'run.completed'[]`\n Events delivered to this endpoint. `change.detected` fires only when a run detects a change; `run.completed` fires on every completed run — including runs that detected no change — and embeds the change when one was detected. Defaults to `[\"change.detected\"]` when omitted.\n - `secret?: string`\n Signing secret used to verify webhook authenticity. Each delivery includes an `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over `\"{t}.{rawRequestBody}\"` keyed by this secret. Recompute it with a constant-time compare and reject stale timestamps to prevent replay. Generated by the API; cannot be set by clients.\n\n### Returns\n\n- `{ id: string; change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }; created_at: string; mode: 'web'; name: string; schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }; status: 'active' | 'paused' | 'failed'; target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }; updated_at: string; baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }; last_change_at?: string; last_error?: { code: string; message: string; }; last_run_at?: string; next_run_at?: string; tags?: string[]; webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }; webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }; }`\n A web monitor. `mode` is the constant `web`; behavior is described by `target` (page/sitemap/extract) and `change_detection` (exact/semantic).\n\n - `id: string`\n - `change_detection: { type: 'exact'; } | { type: 'semantic'; confidence_threshold?: number; }`\n - `created_at: string`\n - `mode: 'web'`\n - `name: string`\n - `schedule: { frequency: number; type: 'interval'; unit: 'minutes' | 'hours' | 'days'; }`\n - `status: 'active' | 'paused' | 'failed'`\n - `target: { type: 'page'; url: string; instructions?: string; normalize_whitespace?: boolean; } | { type: 'sitemap'; url: string; exclude?: string[]; include?: string[]; max_urls?: number; } | { instructions: string; type: 'extract'; url: string; follow_subdomains?: boolean; max_depth?: number; max_pages?: number; schema?: object; }`\n - `updated_at: string`\n - `baseline?: { captured_at: string; text: string; } | { captured_at: string; url_count: number; urls: string[]; } | { captured_at: string; data: object; urls_analyzed: string[]; }`\n - `last_change_at?: string`\n - `last_error?: { code: string; message: string; }`\n - `last_run_at?: string`\n - `next_run_at?: string`\n - `tags?: string[]`\n - `webhook?: { url: string; events?: 'change.detected' | 'run.completed'[]; secret?: string; }`\n - `webhook_failure?: { consecutive_failures: number; last_failed_at: string; last_message: string; last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst monitor = await client.monitors.update('mon_123');\n\nconsole.log(monitor);\n```", - perLanguage: { - php: { - method: 'monitors->update', - example: - "monitors->update(\n 'mon_123',\n changeDetection: ['type' => 'exact'],\n name: 'Acme pricing monitor',\n schedule: ['frequency' => 1, 'type' => 'interval', 'unit' => 'hours'],\n status: 'active',\n tags: ['pricing', 'competitor'],\n target: [\n 'type' => 'page',\n 'url' => 'https://acme.com/pricing',\n 'instructions' => 'Report pricing or plan availability changes. Ignore counters, timestamps, testimonials, and navigation.',\n 'normalizeWhitespace' => true,\n ],\n webhook: [\n 'url' => 'https://example.com/webhook',\n 'events' => ['change.detected', 'run.completed'],\n ],\n);\n\nvar_dump($monitor);", - }, - go: { - method: 'client.Monitors.Update', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tmonitor, err := client.Monitors.Update(\n\t\tcontext.TODO(),\n\t\t"mon_123",\n\t\tcontextdev.MonitorUpdateParams{\n\t\t\tName: contextdev.String("Acme pricing monitor"),\n\t\t\tSchedule: contextdev.MonitorUpdateParamsSchedule{\n\t\t\t\tType: "interval",\n\t\t\t\tFrequency: 1,\n\t\t\t\tUnit: "hours",\n\t\t\t},\n\t\t\tStatus: contextdev.MonitorUpdateParamsStatusActive,\n\t\t\tWebhook: contextdev.MonitorUpdateParamsWebhook{\n\t\t\t\tURL: "https://example.com/webhook",\n\t\t\t},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", monitor.ID)\n}\n', - }, - cli: { - method: 'monitors update', - example: "context-dev monitors update \\\n --api-key 'My API Key' \\\n --monitor-id mon_123", - }, - python: { - method: 'monitors.update', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nmonitor = client.monitors.update(\n monitor_id="mon_123",\n name="Acme pricing monitor",\n schedule={\n "type": "interval",\n "frequency": 1,\n "unit": "hours",\n },\n status="active",\n webhook={\n "url": "https://example.com/webhook"\n },\n)\nprint(monitor.id)', - }, - ruby: { - method: 'monitors.update', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nmonitor = context_dev.monitors.update("mon_123")\n\nputs(monitor)', - }, - typescript: { - method: 'client.monitors.update', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst monitor = await client.monitors.update('mon_123', {\n name: 'Acme pricing monitor',\n schedule: {\n type: 'interval',\n frequency: 1,\n unit: 'hours',\n },\n status: 'active',\n webhook: { url: 'https://example.com/webhook' },\n});\n\nconsole.log(monitor.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/$MONITOR_ID \\\n -X PATCH \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "name": "Acme pricing monitor",\n "schedule": {\n "frequency": 1,\n "type": "interval",\n "unit": "hours"\n },\n "status": "active",\n "tags": [\n "pricing",\n "competitor"\n ],\n "webhook": {\n "url": "https://example.com/webhook"\n }\n }\'', - }, - }, - }, - { - name: 'delete', - endpoint: '/monitors/{monitor_id}', - httpMethod: 'delete', - summary: 'Delete a monitor', - description: 'Delete a monitor', - stainlessPath: '(resource) monitors > (method) delete', - qualified: 'client.monitors.delete', - params: ['monitor_id: string;'], - response: '{ id: string; deleted: boolean; }', - markdown: - "## delete\n\n`client.monitors.delete(monitor_id: string): { id: string; deleted: boolean; }`\n\n**delete** `/monitors/{monitor_id}`\n\nDelete a monitor\n\n### Parameters\n\n- `monitor_id: string`\n\n### Returns\n\n- `{ id: string; deleted: boolean; }`\n\n - `id: string`\n - `deleted: boolean`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst monitor = await client.monitors.delete('mon_123');\n\nconsole.log(monitor);\n```", - perLanguage: { - php: { - method: 'monitors->delete', - example: - "monitors->delete('mon_123');\n\nvar_dump($monitor);", - }, - go: { - method: 'client.Monitors.Delete', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tmonitor, err := client.Monitors.Delete(context.TODO(), "mon_123")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", monitor.ID)\n}\n', - }, - cli: { - method: 'monitors delete', - example: "context-dev monitors delete \\\n --api-key 'My API Key' \\\n --monitor-id mon_123", - }, - python: { - method: 'monitors.delete', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nmonitor = client.monitors.delete(\n "mon_123",\n)\nprint(monitor.id)', - }, - ruby: { - method: 'monitors.delete', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nmonitor = context_dev.monitors.delete("mon_123")\n\nputs(monitor)', - }, - typescript: { - method: 'client.monitors.delete', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst monitor = await client.monitors.delete('mon_123');\n\nconsole.log(monitor.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/$MONITOR_ID \\\n -X DELETE \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'run', - endpoint: '/monitors/{monitor_id}/run', - httpMethod: 'post', - summary: 'Run a monitor now', - description: - 'Triggers an immediate run of the monitor outside its normal schedule. The run is queued and processed asynchronously.', - stainlessPath: '(resource) monitors > (method) run', - qualified: 'client.monitors.run', - params: ['monitor_id: string;'], - response: '{ monitor_id: string; queued: boolean; run_id: string; }', - markdown: - "## run\n\n`client.monitors.run(monitor_id: string): { monitor_id: string; queued: boolean; run_id: string; }`\n\n**post** `/monitors/{monitor_id}/run`\n\nTriggers an immediate run of the monitor outside its normal schedule. The run is queued and processed asynchronously.\n\n### Parameters\n\n- `monitor_id: string`\n\n### Returns\n\n- `{ monitor_id: string; queued: boolean; run_id: string; }`\n\n - `monitor_id: string`\n - `queued: boolean`\n - `run_id: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.run('mon_123');\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->run', - example: - "monitors->run('mon_123');\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.Run', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.Run(context.TODO(), "mon_123")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.MonitorID)\n}\n', - }, - cli: { - method: 'monitors run', - example: "context-dev monitors run \\\n --api-key 'My API Key' \\\n --monitor-id mon_123", - }, - python: { - method: 'monitors.run', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.run(\n "mon_123",\n)\nprint(response.monitor_id)', - }, - ruby: { - method: 'monitors.run', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.run("mon_123")\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.run', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.run('mon_123');\n\nconsole.log(response.monitor_id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/$MONITOR_ID/run \\\n -X POST \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'list_runs', - endpoint: '/monitors/{monitor_id}/runs', - httpMethod: 'get', - summary: 'List monitor runs', - description: 'List monitor runs', - stainlessPath: '(resource) monitors > (method) list_runs', - qualified: 'client.monitors.listRuns', - params: [ - 'monitor_id: string;', - 'cursor?: string;', - 'limit?: number;', - "status?: 'queued' | 'running' | 'completed' | 'failed' | 'skipped';", - ], - response: - "{ data: { id: string; baseline_created: boolean; change_detected: boolean; change_detection_type: 'exact' | 'semantic'; credits_charged: number; monitor_id: string; run_type: 'baseline' | 'scheduled'; status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; target_type: 'page' | 'sitemap' | 'extract'; change_id?: string; completed_at?: string; error?: { code: string; message: string; }; skip_reason?: 'insufficient_credits' | 'monitor_paused' | 'superseded'; started_at?: string; webhook_deliveries?: object[]; webhook_delivery?: object; }[]; has_more: boolean; next_cursor: string; }", - markdown: - "## list_runs\n\n`client.monitors.listRuns(monitor_id: string, cursor?: string, limit?: number, status?: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'): { data: object[]; has_more: boolean; next_cursor: string; }`\n\n**get** `/monitors/{monitor_id}/runs`\n\nList monitor runs\n\n### Parameters\n\n- `monitor_id: string`\n\n- `cursor?: string`\n Opaque pagination cursor from a previous response.\n\n- `limit?: number`\n Maximum number of items to return per page (1-100). Defaults to 25.\n\n- `status?: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'`\n Filter runs by lifecycle status.\n\n### Returns\n\n- `{ data: { id: string; baseline_created: boolean; change_detected: boolean; change_detection_type: 'exact' | 'semantic'; credits_charged: number; monitor_id: string; run_type: 'baseline' | 'scheduled'; status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; target_type: 'page' | 'sitemap' | 'extract'; change_id?: string; completed_at?: string; error?: { code: string; message: string; }; skip_reason?: 'insufficient_credits' | 'monitor_paused' | 'superseded'; started_at?: string; webhook_deliveries?: object[]; webhook_delivery?: object; }[]; has_more: boolean; next_cursor: string; }`\n\n - `data: { id: string; baseline_created: boolean; change_detected: boolean; change_detection_type: 'exact' | 'semantic'; credits_charged: number; monitor_id: string; run_type: 'baseline' | 'scheduled'; status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; target_type: 'page' | 'sitemap' | 'extract'; change_id?: string; completed_at?: string; error?: { code: string; message: string; }; skip_reason?: 'insufficient_credits' | 'monitor_paused' | 'superseded'; started_at?: string; webhook_deliveries?: { attempted_at: string; error: { code: string; message: string; }; event: 'change.detected' | 'run.completed'; event_id: string; http_status: number; status: 'delivered' | 'rejected' | 'failed' | 'skipped_unsafe_url'; }[]; webhook_delivery?: { attempted_at: string; error: { code: string; message: string; }; event: 'change.detected' | 'run.completed'; event_id: string; http_status: number; status: 'delivered' | 'rejected' | 'failed' | 'skipped_unsafe_url'; }; }[]`\n - `has_more: boolean`\n - `next_cursor: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.listRuns('mon_123');\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->listRuns', - example: - "monitors->listRuns(\n 'mon_123', cursor: 'cursor', limit: 1, status: 'queued'\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.ListRuns', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.ListRuns(\n\t\tcontext.TODO(),\n\t\t"mon_123",\n\t\tcontextdev.MonitorListRunsParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Data)\n}\n', - }, - cli: { - method: 'monitors list_runs', - example: "context-dev monitors list-runs \\\n --api-key 'My API Key' \\\n --monitor-id mon_123", - }, - python: { - method: 'monitors.list_runs', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.list_runs(\n monitor_id="mon_123",\n)\nprint(response.data)', - }, - ruby: { - method: 'monitors.list_runs', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.list_runs("mon_123")\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.listRuns', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.listRuns('mon_123');\n\nconsole.log(response.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/$MONITOR_ID/runs \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'list_changes', - endpoint: '/monitors/{monitor_id}/changes', - httpMethod: 'get', - summary: 'List changes for a monitor', - description: 'List changes for a monitor', - stainlessPath: '(resource) monitors > (method) list_changes', - qualified: 'client.monitors.listChanges', - params: [ - 'monitor_id: string;', - 'cursor?: string;', - 'limit?: number;', - 'since?: string;', - 'tag?: string;', - 'until?: string;', - ], - response: - "{ data: { id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; summary: string; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; confidence?: number; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; removed_url_count?: number; tags?: string[]; }[]; has_more: boolean; next_cursor: string; }", - markdown: - "## list_changes\n\n`client.monitors.listChanges(monitor_id: string, cursor?: string, limit?: number, since?: string, tag?: string, until?: string): { data: object[]; has_more: boolean; next_cursor: string; }`\n\n**get** `/monitors/{monitor_id}/changes`\n\nList changes for a monitor\n\n### Parameters\n\n- `monitor_id: string`\n\n- `cursor?: string`\n Opaque pagination cursor from a previous response.\n\n- `limit?: number`\n Maximum number of items to return per page (1-100). Defaults to 25.\n\n- `since?: string`\n Only include items at or after this ISO 8601 timestamp.\n\n- `tag?: string`\n Filter to items that have this tag.\n\n- `until?: string`\n Only include items before this ISO 8601 timestamp.\n\n### Returns\n\n- `{ data: { id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; summary: string; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; confidence?: number; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; removed_url_count?: number; tags?: string[]; }[]; has_more: boolean; next_cursor: string; }`\n\n - `data: { id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; summary: string; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; confidence?: number; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; removed_url_count?: number; tags?: string[]; }[]`\n - `has_more: boolean`\n - `next_cursor: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.listChanges('mon_123');\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->listChanges', - example: - "monitors->listChanges(\n 'mon_123',\n cursor: 'cursor',\n limit: 1,\n since: new \\DateTimeImmutable('2026-06-01T00:00:00Z'),\n tag: 'pricing',\n until: new \\DateTimeImmutable('2026-06-28T00:00:00Z'),\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.ListChanges', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.ListChanges(\n\t\tcontext.TODO(),\n\t\t"mon_123",\n\t\tcontextdev.MonitorListChangesParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Data)\n}\n', - }, - cli: { - method: 'monitors list_changes', - example: "context-dev monitors list-changes \\\n --api-key 'My API Key' \\\n --monitor-id mon_123", - }, - python: { - method: 'monitors.list_changes', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.list_changes(\n monitor_id="mon_123",\n)\nprint(response.data)', - }, - ruby: { - method: 'monitors.list_changes', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.list_changes("mon_123")\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.listChanges', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.listChanges('mon_123');\n\nconsole.log(response.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/$MONITOR_ID/changes \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'list_account_runs', - endpoint: '/monitors/runs', - httpMethod: 'get', - summary: 'List runs', - description: 'Returns an account-wide feed of monitor runs across all monitors.', - stainlessPath: '(resource) monitors > (method) list_account_runs', - qualified: 'client.monitors.listAccountRuns', - params: [ - 'cursor?: string;', - 'limit?: number;', - "status?: 'queued' | 'running' | 'completed' | 'failed' | 'skipped';", - ], - response: - "{ data: { id: string; baseline_created: boolean; change_detected: boolean; change_detection_type: 'exact' | 'semantic'; credits_charged: number; monitor_id: string; run_type: 'baseline' | 'scheduled'; status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; target_type: 'page' | 'sitemap' | 'extract'; change_id?: string; completed_at?: string; error?: { code: string; message: string; }; skip_reason?: 'insufficient_credits' | 'monitor_paused' | 'superseded'; started_at?: string; webhook_deliveries?: object[]; webhook_delivery?: object; }[]; has_more: boolean; next_cursor: string; }", - markdown: - "## list_account_runs\n\n`client.monitors.listAccountRuns(cursor?: string, limit?: number, status?: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'): { data: object[]; has_more: boolean; next_cursor: string; }`\n\n**get** `/monitors/runs`\n\nReturns an account-wide feed of monitor runs across all monitors.\n\n### Parameters\n\n- `cursor?: string`\n Opaque pagination cursor from a previous response.\n\n- `limit?: number`\n Maximum number of items to return per page (1-100). Defaults to 25.\n\n- `status?: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'`\n Filter runs by lifecycle status.\n\n### Returns\n\n- `{ data: { id: string; baseline_created: boolean; change_detected: boolean; change_detection_type: 'exact' | 'semantic'; credits_charged: number; monitor_id: string; run_type: 'baseline' | 'scheduled'; status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; target_type: 'page' | 'sitemap' | 'extract'; change_id?: string; completed_at?: string; error?: { code: string; message: string; }; skip_reason?: 'insufficient_credits' | 'monitor_paused' | 'superseded'; started_at?: string; webhook_deliveries?: object[]; webhook_delivery?: object; }[]; has_more: boolean; next_cursor: string; }`\n\n - `data: { id: string; baseline_created: boolean; change_detected: boolean; change_detection_type: 'exact' | 'semantic'; credits_charged: number; monitor_id: string; run_type: 'baseline' | 'scheduled'; status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; target_type: 'page' | 'sitemap' | 'extract'; change_id?: string; completed_at?: string; error?: { code: string; message: string; }; skip_reason?: 'insufficient_credits' | 'monitor_paused' | 'superseded'; started_at?: string; webhook_deliveries?: { attempted_at: string; error: { code: string; message: string; }; event: 'change.detected' | 'run.completed'; event_id: string; http_status: number; status: 'delivered' | 'rejected' | 'failed' | 'skipped_unsafe_url'; }[]; webhook_delivery?: { attempted_at: string; error: { code: string; message: string; }; event: 'change.detected' | 'run.completed'; event_id: string; http_status: number; status: 'delivered' | 'rejected' | 'failed' | 'skipped_unsafe_url'; }; }[]`\n - `has_more: boolean`\n - `next_cursor: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.listAccountRuns();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->listAccountRuns', - example: - "monitors->listAccountRuns(\n cursor: 'cursor', limit: 1, status: 'queued'\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.ListAccountRuns', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.ListAccountRuns(context.TODO(), contextdev.MonitorListAccountRunsParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Data)\n}\n', - }, - cli: { - method: 'monitors list_account_runs', - example: "context-dev monitors list-account-runs \\\n --api-key 'My API Key'", - }, - python: { - method: 'monitors.list_account_runs', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.list_account_runs()\nprint(response.data)', - }, - ruby: { - method: 'monitors.list_account_runs', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.list_account_runs\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.listAccountRuns', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.listAccountRuns();\n\nconsole.log(response.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/runs \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'list_account_changes', - endpoint: '/monitors/changes', - httpMethod: 'get', - summary: 'List changes', - description: 'Returns an account-wide feed of detected changes across monitors.', - stainlessPath: '(resource) monitors > (method) list_account_changes', - qualified: 'client.monitors.listAccountChanges', - params: [ - "change_detection_type?: 'exact' | 'semantic';", - 'cursor?: string;', - 'limit?: number;', - 'monitor_id?: string;', - 'since?: string;', - 'tag?: string;', - "target_type?: 'page' | 'sitemap' | 'extract';", - 'until?: string;', - ], - response: - "{ data: { id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; summary: string; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; confidence?: number; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; removed_url_count?: number; tags?: string[]; }[]; has_more: boolean; next_cursor: string; }", - markdown: - "## list_account_changes\n\n`client.monitors.listAccountChanges(change_detection_type?: 'exact' | 'semantic', cursor?: string, limit?: number, monitor_id?: string, since?: string, tag?: string, target_type?: 'page' | 'sitemap' | 'extract', until?: string): { data: object[]; has_more: boolean; next_cursor: string; }`\n\n**get** `/monitors/changes`\n\nReturns an account-wide feed of detected changes across monitors.\n\n### Parameters\n\n- `change_detection_type?: 'exact' | 'semantic'`\n Filter by change detection type.\n\n- `cursor?: string`\n Opaque pagination cursor from a previous response.\n\n- `limit?: number`\n Maximum number of items to return per page (1-100). Defaults to 25.\n\n- `monitor_id?: string`\n Filter changes to a single monitor.\n\n- `since?: string`\n Only include items at or after this ISO 8601 timestamp.\n\n- `tag?: string`\n Filter to items that have this tag.\n\n- `target_type?: 'page' | 'sitemap' | 'extract'`\n Filter by target type.\n\n- `until?: string`\n Only include items before this ISO 8601 timestamp.\n\n### Returns\n\n- `{ data: { id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; summary: string; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; confidence?: number; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; removed_url_count?: number; tags?: string[]; }[]; has_more: boolean; next_cursor: string; }`\n\n - `data: { id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; summary: string; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; confidence?: number; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; removed_url_count?: number; tags?: string[]; }[]`\n - `has_more: boolean`\n - `next_cursor: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.listAccountChanges();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->listAccountChanges', - example: - "monitors->listAccountChanges(\n changeDetectionType: 'exact',\n cursor: 'cursor',\n limit: 1,\n monitorID: 'mon_123',\n since: new \\DateTimeImmutable('2026-06-01T00:00:00Z'),\n tag: 'pricing',\n targetType: 'page',\n until: new \\DateTimeImmutable('2026-06-28T00:00:00Z'),\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.ListAccountChanges', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.ListAccountChanges(context.TODO(), contextdev.MonitorListAccountChangesParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Data)\n}\n', - }, - cli: { - method: 'monitors list_account_changes', - example: "context-dev monitors list-account-changes \\\n --api-key 'My API Key'", - }, - python: { - method: 'monitors.list_account_changes', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.list_account_changes()\nprint(response.data)', - }, - ruby: { - method: 'monitors.list_account_changes', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.list_account_changes\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.listAccountChanges', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.listAccountChanges();\n\nconsole.log(response.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/changes \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'retrieve_change', - endpoint: '/monitors/changes/{change_id}', - httpMethod: 'get', - summary: 'Get a change', - description: 'Get a change', - stainlessPath: '(resource) monitors > (method) retrieve_change', - qualified: 'client.monitors.retrieveChange', - params: ['change_id: string;'], - response: - "{ id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; run_id: string; summary: string; tags: string[]; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; added_urls?: string[]; after_text_excerpt?: string; before_text_excerpt?: string; confidence?: number; diff?: string; evidence?: { after: string; before: string; url?: string; }[]; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; matched_urls?: string[]; removed_url_count?: number; removed_urls?: string[]; }", - markdown: - "## retrieve_change\n\n`client.monitors.retrieveChange(change_id: string): { id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; run_id: string; summary: string; tags: string[]; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; added_urls?: string[]; after_text_excerpt?: string; before_text_excerpt?: string; confidence?: number; diff?: string; evidence?: object[]; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; matched_urls?: string[]; removed_url_count?: number; removed_urls?: string[]; }`\n\n**get** `/monitors/changes/{change_id}`\n\nGet a change\n\n### Parameters\n\n- `change_id: string`\n\n### Returns\n\n- `{ id: string; change_detection_type: 'exact' | 'semantic'; detected_at: string; mode: 'web'; monitor_id: string; run_id: string; summary: string; tags: string[]; target_type: 'page' | 'sitemap' | 'extract'; title: string; url: string; added_url_count?: number; added_urls?: string[]; after_text_excerpt?: string; before_text_excerpt?: string; confidence?: number; diff?: string; evidence?: { after: string; before: string; url?: string; }[]; importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; matched_urls?: string[]; removed_url_count?: number; removed_urls?: string[]; }`\n A detected change. `mode` is the constant `web`; `target_type` and `change_detection_type` describe the change, and which optional fields are present depends on them (page: `diff` + excerpts; sitemap: `added_urls`/`removed_urls`; semantic: `confidence`/`importance`/`evidence`/`matched_urls`).\n\n - `id: string`\n - `change_detection_type: 'exact' | 'semantic'`\n - `detected_at: string`\n - `mode: 'web'`\n - `monitor_id: string`\n - `run_id: string`\n - `summary: string`\n - `tags: string[]`\n - `target_type: 'page' | 'sitemap' | 'extract'`\n - `title: string`\n - `url: string`\n - `added_url_count?: number`\n - `added_urls?: string[]`\n - `after_text_excerpt?: string`\n - `before_text_excerpt?: string`\n - `confidence?: number`\n - `diff?: string`\n - `evidence?: { after: string; before: string; url?: string; }[]`\n - `importance?: 'low' | 'medium' | 'high'`\n - `matched_url_count?: number`\n - `matched_urls?: string[]`\n - `removed_url_count?: number`\n - `removed_urls?: string[]`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.retrieveChange('chg_123');\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->retrieveChange', - example: - "monitors->retrieveChange('chg_123');\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.GetChange', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.GetChange(context.TODO(), "chg_123")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.ID)\n}\n', - }, - cli: { - method: 'monitors retrieve_change', - example: - "context-dev monitors retrieve-change \\\n --api-key 'My API Key' \\\n --change-id chg_123", - }, - python: { - method: 'monitors.retrieve_change', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.retrieve_change(\n "chg_123",\n)\nprint(response.id)', - }, - ruby: { - method: 'monitors.retrieve_change', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.retrieve_change("chg_123")\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.retrieveChange', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.retrieveChange('chg_123');\n\nconsole.log(response.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/changes/$CHANGE_ID \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'get_credit_usage', - endpoint: '/monitors/credit-usage', - httpMethod: 'get', - summary: 'Monitor credit usage', - description: - 'Returns credits charged per monitor over an optional [since, until] window, newest spenders first.', - stainlessPath: '(resource) monitors > (method) get_credit_usage', - qualified: 'client.monitors.getCreditUsage', - params: ['since?: string;', 'until?: string;'], - response: - '{ data: { credits: number; monitor_id: string; name: string; runs: number; }[]; total_credits: number; }', - markdown: - "## get_credit_usage\n\n`client.monitors.getCreditUsage(since?: string, until?: string): { data: object[]; total_credits: number; }`\n\n**get** `/monitors/credit-usage`\n\nReturns credits charged per monitor over an optional [since, until] window, newest spenders first.\n\n### Parameters\n\n- `since?: string`\n Only include items at or after this ISO 8601 timestamp.\n\n- `until?: string`\n Only include items before this ISO 8601 timestamp.\n\n### Returns\n\n- `{ data: { credits: number; monitor_id: string; name: string; runs: number; }[]; total_credits: number; }`\n\n - `data: { credits: number; monitor_id: string; name: string; runs: number; }[]`\n - `total_credits: number`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.getCreditUsage();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->getCreditUsage', - example: - "monitors->getCreditUsage(\n since: new \\DateTimeImmutable('2026-06-01T00:00:00Z'),\n until: new \\DateTimeImmutable('2026-06-28T00:00:00Z'),\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.GetCreditUsage', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.GetCreditUsage(context.TODO(), contextdev.MonitorGetCreditUsageParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Data)\n}\n', - }, - cli: { - method: 'monitors get_credit_usage', - example: "context-dev monitors get-credit-usage \\\n --api-key 'My API Key'", - }, - python: { - method: 'monitors.get_credit_usage', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.get_credit_usage()\nprint(response.data)', - }, - ruby: { - method: 'monitors.get_credit_usage', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.get_credit_usage\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.getCreditUsage', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.getCreditUsage();\n\nconsole.log(response.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/credit-usage \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'get_limits', - endpoint: '/monitors/limits', - httpMethod: 'get', - summary: 'Monitor limits', - description: 'Returns how many monitors the account has and the maximum it allows.', - stainlessPath: '(resource) monitors > (method) get_limits', - qualified: 'client.monitors.getLimits', - response: - "{ monitors_limit: number; monitors_used: number; plan: 'free' | 'starter' | 'pro' | 'scale'; }", - markdown: - "## get_limits\n\n`client.monitors.getLimits(): { monitors_limit: number; monitors_used: number; plan: 'free' | 'starter' | 'pro' | 'scale'; }`\n\n**get** `/monitors/limits`\n\nReturns how many monitors the account has and the maximum it allows.\n\n### Returns\n\n- `{ monitors_limit: number; monitors_used: number; plan: 'free' | 'starter' | 'pro' | 'scale'; }`\n\n - `monitors_limit: number`\n - `monitors_used: number`\n - `plan: 'free' | 'starter' | 'pro' | 'scale'`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.monitors.getLimits();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'monitors->getLimits', - example: - "monitors->getLimits();\n\nvar_dump($response);", - }, - go: { - method: 'client.Monitors.GetLimits', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Monitors.GetLimits(context.TODO())\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.MonitorsLimit)\n}\n', - }, - cli: { - method: 'monitors get_limits', - example: "context-dev monitors get-limits \\\n --api-key 'My API Key'", - }, - python: { - method: 'monitors.get_limits', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.monitors.get_limits()\nprint(response.monitors_limit)', - }, - ruby: { - method: 'monitors.get_limits', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.monitors.get_limits\n\nputs(response)', - }, - typescript: { - method: 'client.monitors.getLimits', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.monitors.getLimits();\n\nconsole.log(response.monitors_limit);", - }, - http: { - example: - 'curl https://api.context.dev/v1/monitors/limits \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'submit', - endpoint: '/batch/submit', - httpMethod: 'post', - summary: 'Submit a batch', - description: 'Scrape 25K URLs or crawl large websites asynchronously. ', - stainlessPath: '(resource) batch > (method) submit', - qualified: 'client.batch.submit', - params: [ - "input: { data: { format: 'markdown'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeHTML?: boolean; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'scrape'; } | { data: { format: 'markdown'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeHTML?: boolean; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'crawl'; };", - 'tags?: string[];', - 'webhookUrl?: string;', - 'Idempotency-Key?: string;', - ], - response: - "{ id: string; cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: object | object; url_pattern: string; }; created_at: string; credits: { reserved: number; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; invalid_urls: { reason: string; url: string; }[]; mode: 'scrape' | 'crawl'; status: 'queued'; tags: string[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; webhook_secret?: string; }", - markdown: - "## submit\n\n`client.batch.submit(input: { data: { format: 'markdown'; urls: object[]; options?: object; } | { format: 'html'; urls: object[]; options?: object; }; mode: 'scrape'; } | { data: { format: 'markdown'; source: object | object; options?: object; } | { format: 'html'; source: object | object; options?: object; }; mode: 'crawl'; }, tags?: string[], webhookUrl?: string, Idempotency-Key?: string): { id: string; cache_metadata: object; crawl: crawl_controls; created_at: string; credits: object; format: 'markdown' | 'html'; input: intake; invalid_urls: object[]; mode: 'scrape' | 'crawl'; status: 'queued'; tags: string[]; key_metadata?: object; webhook_secret?: string; }`\n\n**post** `/batch/submit`\n\nScrape 25K URLs or crawl large websites asynchronously. \n\n### Parameters\n\n- `input: { data: { format: 'markdown'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeHTML?: boolean; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'scrape'; } | { data: { format: 'markdown'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeHTML?: boolean; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'crawl'; }`\n Choose a URL list or a site crawl.\n\n- `tags?: string[]`\n Tags stored on the batch. Filter the batch list by them later.\n\n- `webhookUrl?: string`\n URL notified when the batch finishes.\n\n- `Idempotency-Key?: string`\n Any string unique to this submission. Retries with the same key return the original batch.\n\n### Returns\n\n- `{ id: string; cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: object | object; url_pattern: string; }; created_at: string; credits: { reserved: number; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; invalid_urls: { reason: string; url: string; }[]; mode: 'scrape' | 'crawl'; status: 'queued'; tags: string[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; webhook_secret?: string; }`\n\n - `id: string`\n - `cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }`\n - `crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: { type: 'start_url'; url: string; } | { domain: string; type: 'sitemap'; }; url_pattern: string; }`\n - `created_at: string`\n - `credits: { reserved: number; }`\n - `format: 'markdown' | 'html'`\n - `input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }`\n - `invalid_urls: { reason: string; url: string; }[]`\n - `mode: 'scrape' | 'crawl'`\n - `status: 'queued'`\n - `tags: string[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `webhook_secret?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.batch.submit({ input: {\n data: { format: 'markdown', urls: [{ url: 'https://example.com/products/anvil' }, { url: 'https://example.com/products/hammer' }] },\n mode: 'scrape',\n} });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'batch->submit', - example: - "batch->submit(\n input: [\n 'data' => [\n 'format' => 'markdown',\n 'urls' => [\n [\n 'url' => 'https://example.com/products/anvil',\n 'itemID' => 'sku-1',\n 'meta' => ['category' => 'bar'],\n ],\n [\n 'url' => 'https://example.com/products/hammer',\n 'itemID' => 'sku-2',\n 'meta' => ['foo' => 'bar'],\n ],\n ],\n 'options' => [\n 'country' => 'de',\n 'excludeSelectors' => ['x'],\n 'includeHTML' => true,\n 'includeImages' => true,\n 'includeLinks' => true,\n 'includeSelectors' => ['x'],\n 'maxAgeMs' => 0,\n 'pdf' => [\n 'end' => 1, 'ocr' => true, 'shouldParse' => true, 'start' => 1\n ],\n 'settleAnimations' => true,\n 'shortenBase64Images' => true,\n 'useMainContentOnly' => true,\n 'waitForMs' => 0,\n ],\n ],\n 'mode' => 'scrape',\n ],\n tags: ['docs', 'competitor'],\n webhookURL: 'webhookUrl',\n idempotencyKey: 'Idempotency-Key',\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Batch.Submit', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Batch.Submit(context.TODO(), contextdev.BatchSubmitParams{\n\t\tInput: contextdev.BatchSubmitParamsInputUnion{\n\t\t\tOfScrape: &contextdev.BatchSubmitParamsInputScrape{\n\t\t\t\tData: contextdev.BatchSubmitParamsInputScrapeDataUnion{\n\t\t\t\t\tOfMarkdown: &contextdev.BatchSubmitParamsInputScrapeDataMarkdown{\n\t\t\t\t\t\tURLs: []contextdev.BatchSubmitParamsInputScrapeDataMarkdownURL{{\n\t\t\t\t\t\t\tURL: "https://example.com/products/anvil",\n\t\t\t\t\t\t\tItemID: contextdev.String("sku-1"),\n\t\t\t\t\t\t\tMeta: map[string]any{\n\t\t\t\t\t\t\t\t"category": "tools",\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t}, {\n\t\t\t\t\t\t\tURL: "https://example.com/products/hammer",\n\t\t\t\t\t\t\tItemID: contextdev.String("sku-2"),\n\t\t\t\t\t\t}},\n\t\t\t\t\t\tOptions: contextdev.BatchSubmitParamsInputScrapeDataMarkdownOptions{\n\t\t\t\t\t\t\tUseMainContentOnly: contextdev.Bool(true),\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.ID)\n}\n', - }, - cli: { - method: 'batch submit', - example: - "context-dev batch submit \\\n --api-key 'My API Key' \\\n --input '{data: {format: markdown, urls: [{url: https://example.com/products/anvil}, {url: https://example.com/products/hammer}]}, mode: scrape}'", - }, - python: { - method: 'batch.submit', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.batch.submit(\n input={\n "data": {\n "urls": [{\n "url": "https://example.com/products/anvil",\n "item_id": "sku-1",\n "meta": {\n "category": "tools"\n },\n }, {\n "url": "https://example.com/products/hammer",\n "item_id": "sku-2",\n }],\n "options": {\n "use_main_content_only": True\n },\n }\n },\n)\nprint(response.id)', - }, - ruby: { - method: 'batch.submit', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.batch.submit(\n input: {\n data: {\n format: :markdown,\n urls: [{url: "https://example.com/products/anvil"}, {url: "https://example.com/products/hammer"}]\n },\n mode: :scrape\n }\n)\n\nputs(response)', - }, - typescript: { - method: 'client.batch.submit', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.batch.submit({\n input: {\n data: {\n urls: [\n {\n url: 'https://example.com/products/anvil',\n itemId: 'sku-1',\n meta: { category: 'tools' },\n },\n { url: 'https://example.com/products/hammer', itemId: 'sku-2' },\n ],\n options: { useMainContentOnly: true },\n },\n },\n});\n\nconsole.log(response.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/batch/submit \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "input": {\n "data": {\n "format": "markdown",\n "urls": [\n {\n "url": "https://example.com/products/anvil",\n "itemId": "sku-1",\n "meta": {\n "category": "bar"\n }\n },\n {\n "url": "https://example.com/products/hammer",\n "itemId": "sku-2"\n }\n ],\n "options": {\n "useMainContentOnly": true\n }\n },\n "mode": "scrape"\n },\n "tags": [\n "docs",\n "competitor"\n ]\n }\'', - }, - }, - }, - { - name: 'list', - endpoint: '/batch/list', - httpMethod: 'get', - summary: 'List batches', - description: 'List your batches from newest to oldest. Filter by status or continue with a cursor.', - stainlessPath: '(resource) batch > (method) list', - qualified: 'client.batch.list', - params: [ - 'cursor?: string;', - 'limit?: number;', - 'q?: string;', - "search_type?: 'exact' | 'prefix';", - "status?: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed';", - 'tags?: string;', - ], - response: - "{ data?: { id: string; crawl: object; credits: { net: number; ocr_charged: number; refunded: number; reserved: number; }; failure: object; format: 'markdown' | 'html'; input: object; mode: 'scrape' | 'crawl'; page_errors: object[]; progress: { failed: number; pending: number; succeeded: number; }; results: { expires_at: string; files: object[]; }; status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; tags: string[]; timing: { completed_at: string; created_at: string; started_at: string; }; }[]; has_more?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; next_cursor?: string; }", - markdown: - "## list\n\n`client.batch.list(cursor?: string, limit?: number, q?: string, search_type?: 'exact' | 'prefix', status?: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed', tags?: string): { data?: object[]; has_more?: boolean; key_metadata?: object; next_cursor?: string; }`\n\n**get** `/batch/list`\n\nList your batches from newest to oldest. Filter by status or continue with a cursor.\n\n### Parameters\n\n- `cursor?: string`\n Cursor from the previous page.\n\n- `limit?: number`\n Batches per page. Defaults to 25.\n\n- `q?: string`\n Free-text search term, matched against the batch id, crawl source (start URL or sitemap domain), and tags.\n\n- `search_type?: 'exact' | 'prefix'`\n `prefix` for as-you-type prefix matching (default), `exact` for full-token matching.\n\n- `status?: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'`\n Filter by status.\n\n- `tags?: string`\n Comma-separated list of tags to filter by (matches batches having any of them).\n\n### Returns\n\n- `{ data?: { id: string; crawl: object; credits: { net: number; ocr_charged: number; refunded: number; reserved: number; }; failure: object; format: 'markdown' | 'html'; input: object; mode: 'scrape' | 'crawl'; page_errors: object[]; progress: { failed: number; pending: number; succeeded: number; }; results: { expires_at: string; files: object[]; }; status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; tags: string[]; timing: { completed_at: string; created_at: string; started_at: string; }; }[]; has_more?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; next_cursor?: string; }`\n\n - `data?: { id: string; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: { type: 'start_url'; url: string; } | { domain: string; type: 'sitemap'; }; url_pattern: string; }; credits: { net: number; ocr_charged: number; refunded: number; reserved: number; }; failure: { code: string; message: string; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; mode: 'scrape' | 'crawl'; page_errors: { code: string; count: number; }[]; progress: { failed: number; pending: number; succeeded: number; }; results: { expires_at: string; files: { bytes: number; items: number; url: string; }[]; }; status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; tags: string[]; timing: { completed_at: string; created_at: string; started_at: string; }; }[]`\n - `has_more?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `next_cursor?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst batches = await client.batch.list();\n\nconsole.log(batches);\n```", - perLanguage: { - php: { - method: 'batch->list', - example: - "batch->list(\n cursor: 'cursor',\n limit: 1,\n q: 'batch_1a2b',\n searchType: 'exact',\n status: 'queued',\n tags: 'docs,competitor',\n);\n\nvar_dump($batches);", - }, - go: { - method: 'client.Batch.List', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tbatches, err := client.Batch.List(context.TODO(), contextdev.BatchListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", batches.Data)\n}\n', - }, - cli: { - method: 'batch list', - example: "context-dev batch list \\\n --api-key 'My API Key'", - }, - python: { - method: 'batch.list', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nbatches = client.batch.list()\nprint(batches.data)', - }, - ruby: { - method: 'batch.list', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nbatches = context_dev.batch.list\n\nputs(batches)', - }, - typescript: { - method: 'client.batch.list', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst batches = await client.batch.list();\n\nconsole.log(batches.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/batch/list \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'retrieve', - endpoint: '/batch/{batch_id}', - httpMethod: 'get', - summary: 'Get a batch', - description: 'Check progress, and get download links once the batch finishes.', - stainlessPath: '(resource) batch > (method) retrieve', - qualified: 'client.batch.retrieve', - params: ['batch_id: string;'], - response: - "{ id: string; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: object | object; url_pattern: string; }; credits: { net: number; ocr_charged: number; refunded: number; reserved: number; }; failure: { code: string; message: string; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; invalid_urls: { reason: string; url: string; }[]; mode: 'scrape' | 'crawl'; page_errors: { code: string; count: number; }[]; progress: { failed: number; pending: number; succeeded: number; }; results: { expires_at: string; files: { bytes: number; items: number; url: string; }[]; }; status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; tags: string[]; timing: { completed_at: string; created_at: string; started_at: string; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## retrieve\n\n`client.batch.retrieve(batch_id: string): { id: string; crawl: crawl_controls; credits: object; failure: failure; format: 'markdown' | 'html'; input: intake; invalid_urls: object[]; mode: 'scrape' | 'crawl'; page_errors: page_error_count[]; progress: object; results: object; status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; tags: string[]; timing: object; key_metadata?: object; }`\n\n**get** `/batch/{batch_id}`\n\nCheck progress, and get download links once the batch finishes.\n\n### Parameters\n\n- `batch_id: string`\n ID of the batch to retrieve or cancel.\n\n### Returns\n\n- `{ id: string; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: object | object; url_pattern: string; }; credits: { net: number; ocr_charged: number; refunded: number; reserved: number; }; failure: { code: string; message: string; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; invalid_urls: { reason: string; url: string; }[]; mode: 'scrape' | 'crawl'; page_errors: { code: string; count: number; }[]; progress: { failed: number; pending: number; succeeded: number; }; results: { expires_at: string; files: { bytes: number; items: number; url: string; }[]; }; status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; tags: string[]; timing: { completed_at: string; created_at: string; started_at: string; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `id: string`\n - `crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: { type: 'start_url'; url: string; } | { domain: string; type: 'sitemap'; }; url_pattern: string; }`\n - `credits: { net: number; ocr_charged: number; refunded: number; reserved: number; }`\n - `failure: { code: string; message: string; }`\n - `format: 'markdown' | 'html'`\n - `input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }`\n - `invalid_urls: { reason: string; url: string; }[]`\n - `mode: 'scrape' | 'crawl'`\n - `page_errors: { code: string; count: number; }[]`\n - `progress: { failed: number; pending: number; succeeded: number; }`\n - `results: { expires_at: string; files: { bytes: number; items: number; url: string; }[]; }`\n - `status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'`\n - `tags: string[]`\n - `timing: { completed_at: string; created_at: string; started_at: string; }`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst batch = await client.batch.retrieve('batch_9f2c8a');\n\nconsole.log(batch);\n```", - perLanguage: { - php: { - method: 'batch->retrieve', - example: - "batch->retrieve('batch_9f2c8a');\n\nvar_dump($batch);", - }, - go: { - method: 'client.Batch.Get', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tbatch, err := client.Batch.Get(context.TODO(), "batch_9f2c8a")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", batch.ID)\n}\n', - }, - cli: { - method: 'batch retrieve', - example: "context-dev batch retrieve \\\n --api-key 'My API Key' \\\n --batch-id batch_9f2c8a", - }, - python: { - method: 'batch.retrieve', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nbatch = client.batch.retrieve(\n "batch_9f2c8a",\n)\nprint(batch.id)', - }, - ruby: { - method: 'batch.retrieve', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nbatch = context_dev.batch.retrieve("batch_9f2c8a")\n\nputs(batch)', - }, - typescript: { - method: 'client.batch.retrieve', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst batch = await client.batch.retrieve('batch_9f2c8a');\n\nconsole.log(batch.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/batch/$BATCH_ID \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'get_results', - endpoint: '/batch/{batch_id}/results', - httpMethod: 'get', - summary: 'Get batch results', - description: "Page through a finished batch's results as JSON instead of downloading the NDJSON files.", - stainlessPath: '(resource) batch > (method) get_results', - qualified: 'client.batch.getResults', - params: ['batch_id: string;', 'cursor?: string;', 'limit?: number;'], - response: - "{ data?: { cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; final_url: string; http_status: number; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: object[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; status: 'ok'; url: string; html?: string; itemId?: string; markdown?: string; meta?: object; ocr_pages?: number; } | { error_code: string; message: string; status: 'error'; url: string; itemId?: string; meta?: object; }[]; has_more?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; next_cursor?: string; }", - markdown: - "## get_results\n\n`client.batch.getResults(batch_id: string, cursor?: string, limit?: number): { data?: object | object[]; has_more?: boolean; key_metadata?: object; next_cursor?: string; }`\n\n**get** `/batch/{batch_id}/results`\n\nPage through a finished batch's results as JSON instead of downloading the NDJSON files.\n\n### Parameters\n\n- `batch_id: string`\n ID of the batch to retrieve or cancel.\n\n- `cursor?: string`\n next_cursor from the previous page.\n\n- `limit?: number`\n Records per page. Defaults to 25. A page can close early so its payload stays under ~8 MB; rely on next_cursor rather than counting records.\n\n### Returns\n\n- `{ data?: { cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; final_url: string; http_status: number; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: object[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; status: 'ok'; url: string; html?: string; itemId?: string; markdown?: string; meta?: object; ocr_pages?: number; } | { error_code: string; message: string; status: 'error'; url: string; itemId?: string; meta?: object; }[]; has_more?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; next_cursor?: string; }`\n\n - `data?: { cache_metadata: { age_ms: number; status: 'hit' | 'miss' | 'zdr'; }; final_url: string; http_status: number; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; status: 'ok'; url: string; html?: string; itemId?: string; markdown?: string; meta?: object; ocr_pages?: number; } | { error_code: string; message: string; status: 'error'; url: string; itemId?: string; meta?: object; }[]`\n - `has_more?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `next_cursor?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.batch.getResults('batch_9f2c8a');\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'batch->getResults', - example: - "batch->getResults(\n 'batch_9f2c8a', cursor: 'cursor', limit: 1\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.Batch.GetResults', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Batch.GetResults(\n\t\tcontext.TODO(),\n\t\t"batch_9f2c8a",\n\t\tcontextdev.BatchGetResultsParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Data)\n}\n', - }, - cli: { - method: 'batch get_results', - example: "context-dev batch get-results \\\n --api-key 'My API Key' \\\n --batch-id batch_9f2c8a", - }, - python: { - method: 'batch.get_results', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.batch.get_results(\n batch_id="batch_9f2c8a",\n)\nprint(response.data)', - }, - ruby: { - method: 'batch.get_results', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.batch.get_results("batch_9f2c8a")\n\nputs(response)', - }, - typescript: { - method: 'client.batch.getResults', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.batch.getResults('batch_9f2c8a');\n\nconsole.log(response.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/batch/$BATCH_ID/results \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'cancel', - endpoint: '/batch/{batch_id}/cancel', - httpMethod: 'post', - summary: 'Cancel a batch', - description: - 'Stop a batch from starting new pages. In-progress pages finish, and unused credits are refunded.', - stainlessPath: '(resource) batch > (method) cancel', - qualified: 'client.batch.cancel', - params: ['batch_id: string;'], - response: - "{ id: string; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: object | object; url_pattern: string; }; credits: { reserved: number; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; mode: 'scrape' | 'crawl'; page_errors: { code: string; count: number; }[]; progress: { failed: number; pending: number; succeeded: number; }; status: 'cancelling'; tags: string[]; timing: { created_at: string; started_at: string; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## cancel\n\n`client.batch.cancel(batch_id: string): { id: string; crawl: crawl_controls; credits: object; format: 'markdown' | 'html'; input: intake; mode: 'scrape' | 'crawl'; page_errors: page_error_count[]; progress: object; status: 'cancelling'; tags: string[]; timing: object; key_metadata?: object; }`\n\n**post** `/batch/{batch_id}/cancel`\n\nStop a batch from starting new pages. In-progress pages finish, and unused credits are refunded.\n\n### Parameters\n\n- `batch_id: string`\n ID of the batch to retrieve or cancel.\n\n### Returns\n\n- `{ id: string; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: object | object; url_pattern: string; }; credits: { reserved: number; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; mode: 'scrape' | 'crawl'; page_errors: { code: string; count: number; }[]; progress: { failed: number; pending: number; succeeded: number; }; status: 'cancelling'; tags: string[]; timing: { created_at: string; started_at: string; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `id: string`\n - `crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: { type: 'start_url'; url: string; } | { domain: string; type: 'sitemap'; }; url_pattern: string; }`\n - `credits: { reserved: number; }`\n - `format: 'markdown' | 'html'`\n - `input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }`\n - `mode: 'scrape' | 'crawl'`\n - `page_errors: { code: string; count: number; }[]`\n - `progress: { failed: number; pending: number; succeeded: number; }`\n - `status: 'cancelling'`\n - `tags: string[]`\n - `timing: { created_at: string; started_at: string; }`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.batch.cancel('batch_9f2c8a');\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'batch->cancel', - example: - "batch->cancel('batch_9f2c8a');\n\nvar_dump($response);", - }, - go: { - method: 'client.Batch.Cancel', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.Batch.Cancel(context.TODO(), "batch_9f2c8a")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.ID)\n}\n', - }, - cli: { - method: 'batch cancel', - example: "context-dev batch cancel \\\n --api-key 'My API Key' \\\n --batch-id batch_9f2c8a", - }, - python: { - method: 'batch.cancel', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.batch.cancel(\n "batch_9f2c8a",\n)\nprint(response.id)', - }, - ruby: { - method: 'batch.cancel', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.batch.cancel("batch_9f2c8a")\n\nputs(response)', - }, - typescript: { - method: 'client.batch.cancel', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.batch.cancel('batch_9f2c8a');\n\nconsole.log(response.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/batch/$BATCH_ID/cancel \\\n -X POST \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'delete', - endpoint: '/batch/{batch_id}', - httpMethod: 'delete', - summary: 'Delete a batch', - description: - 'Permanently delete a finished batch and its stored results. Active batches must settle first.', - stainlessPath: '(resource) batch > (method) delete', - qualified: 'client.batch.delete', - params: ['batch_id: string;'], - response: - '{ id?: string; deleted?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }', - markdown: - "## delete\n\n`client.batch.delete(batch_id: string): { id?: string; deleted?: boolean; key_metadata?: object; }`\n\n**delete** `/batch/{batch_id}`\n\nPermanently delete a finished batch and its stored results. Active batches must settle first.\n\n### Parameters\n\n- `batch_id: string`\n ID of the batch to retrieve or cancel.\n\n### Returns\n\n- `{ id?: string; deleted?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `id?: string`\n - `deleted?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst batch = await client.batch.delete('batch_9f2c8a');\n\nconsole.log(batch);\n```", - perLanguage: { - php: { - method: 'batch->delete', - example: - "batch->delete('batch_9f2c8a');\n\nvar_dump($batch);", - }, - go: { - method: 'client.Batch.Delete', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tbatch, err := client.Batch.Delete(context.TODO(), "batch_9f2c8a")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", batch.ID)\n}\n', - }, - cli: { - method: 'batch delete', - example: "context-dev batch delete \\\n --api-key 'My API Key' \\\n --batch-id batch_9f2c8a", - }, - python: { - method: 'batch.delete', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nbatch = client.batch.delete(\n "batch_9f2c8a",\n)\nprint(batch.id)', - }, - ruby: { - method: 'batch.delete', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nbatch = context_dev.batch.delete("batch_9f2c8a")\n\nputs(batch)', - }, - typescript: { - method: 'client.batch.delete', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst batch = await client.batch.delete('batch_9f2c8a');\n\nconsole.log(batch.id);", - }, - http: { - example: - 'curl https://api.context.dev/v1/batch/$BATCH_ID \\\n -X DELETE \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"', - }, - }, - }, - { - name: 'enrich', - endpoint: '/people/enrich', - httpMethod: 'post', - summary: 'Enrich Person', - description: - 'Finds and normalizes the best available person candidate from additive identity clues, then assigns an identity match score from 0 to 100. Available on all paid plans. Successful requests cost 20 credits. Disposable and free email addresses (like gmail.com, yahoo.com) will throw a 422 error.', - stainlessPath: '(resource) people > (method) enrich', - qualified: 'client.people.enrich', - params: [ - 'company?: { domain?: string; name?: string; };', - 'education?: { degree?: string; field_of_study?: string; graduation_year?: number; institution?: { domain?: string; name?: string; }; }[];', - 'email?: string;', - 'location?: { city?: string; country?: string; region?: string; };', - 'name?: { first?: string; last?: string; };', - 'social_urls?: string[];', - 'tags?: string[];', - 'timeoutMS?: number;', - ], - response: - "{ match: { person: { current_role_status: 'present' | 'none' | 'unknown'; education: object[]; experience: object[]; skills: string[]; social_urls: string[]; website_urls: string[]; avatar_url?: string; bio?: string; checked_at?: string; current_role?: object; email?: string; last_updated?: string; location?: object; name?: object; }; score: number; status: 'candidate'; } | { person: null; score: null; status: 'not_found'; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## enrich\n\n`client.people.enrich(company?: { domain?: string; name?: string; }, education?: { degree?: string; field_of_study?: string; graduation_year?: number; institution?: { domain?: string; name?: string; }; }[], email?: string, location?: { city?: string; country?: string; region?: string; }, name?: { first?: string; last?: string; }, social_urls?: string[], tags?: string[], timeoutMS?: number): { match: object | object; key_metadata?: object; }`\n\n**post** `/people/enrich`\n\nFinds and normalizes the best available person candidate from additive identity clues, then assigns an identity match score from 0 to 100. Available on all paid plans. Successful requests cost 20 credits. Disposable and free email addresses (like gmail.com, yahoo.com) will throw a 422 error.\n\n### Parameters\n\n- `company?: { domain?: string; name?: string; }`\n - `domain?: string`\n - `name?: string`\n\n- `education?: { degree?: string; field_of_study?: string; graduation_year?: number; institution?: { domain?: string; name?: string; }; }[]`\n\n- `email?: string`\n\n- `location?: { city?: string; country?: string; region?: string; }`\n - `city?: string`\n - `country?: string`\n - `region?: string`\n\n- `name?: { first?: string; last?: string; }`\n - `first?: string`\n - `last?: string`\n\n- `social_urls?: string[]`\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ match: { person: { current_role_status: 'present' | 'none' | 'unknown'; education: object[]; experience: object[]; skills: string[]; social_urls: string[]; website_urls: string[]; avatar_url?: string; bio?: string; checked_at?: string; current_role?: object; email?: string; last_updated?: string; location?: object; name?: object; }; score: number; status: 'candidate'; } | { person: null; score: null; status: 'not_found'; }; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `match: { person: { current_role_status: 'present' | 'none' | 'unknown'; education: { institution: { name: string; domain?: string; }; degree?: string; description?: string; end_date?: { year: number; day?: number; month?: number; }; field_of_study?: string; start_date?: { year: number; day?: number; month?: number; }; }[]; experience: { organization: { name: string; domain?: string; }; title: string; description?: string; end_date?: { year: number; day?: number; month?: number; }; is_current?: boolean; location?: string; start_date?: { year: number; day?: number; month?: number; }; }[]; skills: string[]; social_urls: string[]; website_urls: string[]; avatar_url?: string; bio?: string; checked_at?: string; current_role?: { organization: { name: string; domain?: string; }; title: string; description?: string; end_date?: { year: number; day?: number; month?: number; }; is_current?: boolean; location?: string; start_date?: { year: number; day?: number; month?: number; }; }; email?: string; last_updated?: string; location?: { city?: string; country?: string; country_code?: string; display?: string; region?: string; }; name?: { first?: string; full?: string; last?: string; }; }; score: number; status: 'candidate'; } | { person: null; score: null; status: 'not_found'; }`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.people.enrich();\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'people->enrich', - example: - "people->enrich(\n company: [\n 'domain' => 'analyticalengines.example', 'name' => 'Analytical Engines'\n ],\n education: [\n [\n 'degree' => 'x',\n 'fieldOfStudy' => 'x',\n 'graduationYear' => 1900,\n 'institution' => ['domain' => 'x', 'name' => 'x'],\n ],\n ],\n email: 'dev@stainless.com',\n location: ['city' => 'x', 'country' => 'x', 'region' => 'x'],\n name: ['first' => 'Ada', 'last' => 'Lovelace'],\n socialURLs: ['https://www.linkedin.com/in/ada-lovelace/'],\n tags: ['production', 'team-alpha'],\n timeoutMs: 1000,\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.People.Enrich', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.People.Enrich(context.TODO(), contextdev.PersonEnrichParams{\n\t\tCompany: contextdev.PersonEnrichParamsCompany{\n\t\t\tName: contextdev.String("Analytical Engines"),\n\t\t\tDomain: contextdev.String("analyticalengines.example"),\n\t\t},\n\t\tName: contextdev.PersonEnrichParamsName{\n\t\t\tFirst: contextdev.String("Ada"),\n\t\t\tLast: contextdev.String("Lovelace"),\n\t\t},\n\t\tSocialURLs: []string{"https://www.linkedin.com/in/ada-lovelace/"},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Match)\n}\n', - }, - cli: { - method: 'people enrich', - example: "context-dev people enrich \\\n --api-key 'My API Key'", - }, - python: { - method: 'people.enrich', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.people.enrich(\n company={\n "name": "Analytical Engines",\n "domain": "analyticalengines.example",\n },\n name={\n "first": "Ada",\n "last": "Lovelace",\n },\n social_urls=["https://www.linkedin.com/in/ada-lovelace/"],\n)\nprint(response.match)', - }, - ruby: { - method: 'people.enrich', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.people.enrich\n\nputs(response)', - }, - typescript: { - method: 'client.people.enrich', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.people.enrich({\n company: { name: 'Analytical Engines', domain: 'analyticalengines.example' },\n name: { first: 'Ada', last: 'Lovelace' },\n social_urls: ['https://www.linkedin.com/in/ada-lovelace/'],\n});\n\nconsole.log(response.match);", - }, - http: { - example: - 'curl https://api.context.dev/v1/people/enrich \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "company": {\n "domain": "analyticalengines.example",\n "name": "Analytical Engines"\n },\n "name": {\n "first": "Ada",\n "last": "Lovelace"\n },\n "social_urls": [\n "https://www.linkedin.com/in/ada-lovelace/"\n ],\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, - { - name: 'search', - endpoint: '/news/search', - httpMethod: 'post', - summary: 'Search company news', - description: - 'Searches live and historical company news for one company, identified in searchBy by name, domain, ticker (optionally disambiguated by exchange), or ISIN. Results can be filtered by publisher domain, publisher country, article language, article type, and published-at date, and include stable story IDs, source metadata, verified entity relevance, and cursor pagination.', - stainlessPath: '(resource) news > (method) search', - qualified: 'client.news.search', - params: [ - "searchBy: { entity: { name: string; type: 'name'; } | { domain: string; type: 'domain'; } | { ticker: string; type: 'ticker'; exchange?: string; } | { isin: string; type: 'isin'; }; type: 'entity'; };", - 'cursor?: string;', - "filterBy?: { articleLanguage?: 'ar' | 'de' | 'en' | 'es' | 'fr' | 'hi' | 'it' | 'ja' | 'ko' | 'nl' | 'pt' | 'ru' | 'zh'[]; articleType?: 'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'[]; date?: { from?: number; to?: number; }; sourceCountry?: string[]; sourceDomain?: string[]; };", - 'limit?: number;', - "sortBy?: { type: 'relevance' | 'newest'; };", - 'tags?: string[];', - ], - response: - "{ data: { id: string; authors: string[]; description: string; image_url: string; language: string; match: { confidence: number; level: 'primary' | 'secondary'; }; published_at: string; source: { direct: boolean; domain: string; name: string; }; story_id: string; title: string; type: 'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'; url: string; }[]; has_more: boolean; meta: { count: number; }; next_cursor: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", - markdown: - "## search\n\n`client.news.search(searchBy: { entity: { name: string; type: 'name'; } | { domain: string; type: 'domain'; } | { ticker: string; type: 'ticker'; exchange?: string; } | { isin: string; type: 'isin'; }; type: 'entity'; }, cursor?: string, filterBy?: { articleLanguage?: 'ar' | 'de' | 'en' | 'es' | 'fr' | 'hi' | 'it' | 'ja' | 'ko' | 'nl' | 'pt' | 'ru' | 'zh'[]; articleType?: 'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'[]; date?: { from?: number; to?: number; }; sourceCountry?: string[]; sourceDomain?: string[]; }, limit?: number, sortBy?: { type: 'relevance' | 'newest'; }, tags?: string[]): { data: object[]; has_more: boolean; meta: object; next_cursor: string; key_metadata?: object; }`\n\n**post** `/news/search`\n\nSearches live and historical company news for one company, identified in searchBy by name, domain, ticker (optionally disambiguated by exchange), or ISIN. Results can be filtered by publisher domain, publisher country, article language, article type, and published-at date, and include stable story IDs, source metadata, verified entity relevance, and cursor pagination.\n\n### Parameters\n\n- `searchBy: { entity: { name: string; type: 'name'; } | { domain: string; type: 'domain'; } | { ticker: string; type: 'ticker'; exchange?: string; } | { isin: string; type: 'isin'; }; type: 'entity'; }`\n What to search for.\n - `entity: { name: string; type: 'name'; } | { domain: string; type: 'domain'; } | { ticker: string; type: 'ticker'; exchange?: string; } | { isin: string; type: 'isin'; }`\n The company to search news for, identified by name, domain, ticker, or ISIN.\n - `type: 'entity'`\n How to search. Only entity search is supported.\n\n- `cursor?: string`\n Opaque next_cursor from the previous response, or null for the first page.\n\n- `filterBy?: { articleLanguage?: 'ar' | 'de' | 'en' | 'es' | 'fr' | 'hi' | 'it' | 'ja' | 'ko' | 'nl' | 'pt' | 'ru' | 'zh'[]; articleType?: 'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'[]; date?: { from?: number; to?: number; }; sourceCountry?: string[]; sourceDomain?: string[]; }`\n Optional result filters.\n - `articleLanguage?: 'ar' | 'de' | 'en' | 'es' | 'fr' | 'hi' | 'it' | 'ja' | 'ko' | 'nl' | 'pt' | 'ru' | 'zh'[]`\n Article languages to include. Up to 3.\n - `articleType?: 'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'[]`\n Article types to include. Up to 3.\n - `date?: { from?: number; to?: number; }`\n Published-at window in epoch milliseconds.\n - `sourceCountry?: string[]`\n Publisher countries to include, as lowercase ISO 3166-1 alpha-2 codes. Up to 3.\n - `sourceDomain?: string[]`\n Publisher domains to include. Up to 3.\n\n- `limit?: number`\n Maximum results to return. Defaults to 10.\n\n- `sortBy?: { type: 'relevance' | 'newest'; }`\n Result ordering. Defaults to newest.\n - `type: 'relevance' | 'newest'`\n Result ordering.\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n### Returns\n\n- `{ data: { id: string; authors: string[]; description: string; image_url: string; language: string; match: { confidence: number; level: 'primary' | 'secondary'; }; published_at: string; source: { direct: boolean; domain: string; name: string; }; story_id: string; title: string; type: 'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'; url: string; }[]; has_more: boolean; meta: { count: number; }; next_cursor: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `data: { id: string; authors: string[]; description: string; image_url: string; language: string; match: { confidence: number; level: 'primary' | 'secondary'; }; published_at: string; source: { direct: boolean; domain: string; name: string; }; story_id: string; title: string; type: 'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'; url: string; }[]`\n - `has_more: boolean`\n - `meta: { count: number; }`\n - `next_cursor: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.news.search({ searchBy: {\n entity: { name: 'xx', type: 'name' },\n type: 'entity',\n} });\n\nconsole.log(response);\n```", - perLanguage: { - php: { - method: 'news->search', - example: - "news->search(\n searchBy: [\n 'entity' => ['name' => 'xx', 'type' => 'name'], 'type' => 'entity'\n ],\n cursor: 'cursor',\n filterBy: [\n 'articleLanguage' => ['ar'],\n 'articleType' => ['editorial'],\n 'date' => ['from' => 0, 'to' => 0],\n 'sourceCountry' => ['ae'],\n 'sourceDomain' => ['x'],\n ],\n limit: 1,\n sortBy: ['type' => 'relevance'],\n tags: ['production', 'team-alpha'],\n);\n\nvar_dump($response);", - }, - go: { - method: 'client.News.Search', - example: - 'package main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"),\n\t)\n\tresponse, err := client.News.Search(context.TODO(), contextdev.NewsSearchParams{\n\t\tSearchBy: contextdev.NewsSearchParamsSearchBy{\n\t\t\tEntity: contextdev.NewsSearchParamsSearchByEntityUnion{\n\t\t\t\tOfName: &contextdev.NewsSearchParamsSearchByEntityName{\n\t\t\t\t\tName: "xx",\n\t\t\t\t},\n\t\t\t},\n\t\t\tType: "entity",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", response.Data)\n}\n', - }, - cli: { - method: 'news search', - example: - "context-dev news search \\\n --api-key 'My API Key' \\\n --search-by '{entity: {name: xx, type: name}, type: entity}'", - }, - python: { - method: 'news.search', - example: - 'import os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\nresponse = client.news.search(\n search_by={\n "entity": {\n "name": "xx",\n "type": "name",\n },\n "type": "entity",\n },\n)\nprint(response.data)', - }, - ruby: { - method: 'news.search', - example: - 'require "context_dev"\n\ncontext_dev = ContextDev::Client.new(api_key: "My API Key")\n\nresponse = context_dev.news.search(search_by: {entity: {name: "xx", type: :name}, type: :entity})\n\nputs(response)', - }, - typescript: { - method: 'client.news.search', - example: - "import ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.news.search({\n searchBy: {\n entity: { name: 'xx', type: 'name' },\n type: 'entity',\n },\n});\n\nconsole.log(response.data);", - }, - http: { - example: - 'curl https://api.context.dev/v1/news/search \\\n -H \'Content-Type: application/json\' \\\n -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \\\n -d \'{\n "searchBy": {\n "entity": {\n "name": "xx",\n "type": "name"\n },\n "type": "entity"\n },\n "tags": [\n "production",\n "team-alpha"\n ]\n }\'', - }, - }, - }, -]; - -const EMBEDDED_READMES: { language: string; content: string }[] = [ - { - language: 'php', - content: - "# Context Dev PHP API Library\n\nThe Context Dev PHP library provides convenient access to the Context Dev REST API from any PHP 8.1.0+ application.\n\n## Installation\n\n\n```\ncomposer require \"context-dev/context-dev-php 2.13.0\"\n```\n\n\n## Usage\n\n```php\nbrand->retrieve(domain: 'REPLACE_ME', type: 'by_domain');\n\nvar_dump($brand->cache_metadata);\n```", - }, - { - language: 'go', - content: - '# Context Dev Go API Library\n\nGo Reference\n\nThe Context Dev Go library provides convenient access to the [Context Dev REST API](https://docs.context.dev/)\nfrom applications written in Go.\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n## MCP Server\n\nUse the Context Dev MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0)\n[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D)\n\n> Note: You may need to set environment variables in your MCP client.\n\n## Installation\n\n\n\n```go\nimport (\n\t"github.com/context-dot-dev/context-go-sdk/v2" // imported as SDK_PackageName\n)\n```\n\n\n\nOr to pin the version:\n\n\n\n```sh\ngo get -u \'github.com/context-dot-dev/context-go-sdk/v2@v2.13.0\'\n```\n\n\n\n## Requirements\n\nThis library requires Go 1.22+.\n\n## Usage\n\nThe full API of this library can be found in [api.md](api.md).\n\n```go\npackage main\n\nimport (\n\t"context"\n\t"fmt"\n\n\t"github.com/context-dot-dev/context-go-sdk/v2"\n\t"github.com/context-dot-dev/context-go-sdk/v2/option"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey("My API Key"), // defaults to os.LookupEnv("CONTEXT_DEV_API_KEY")\n\t)\n\tbrand, err := client.Brand.Get(context.TODO(), contextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf("%+v\\n", brand.CacheMetadata)\n}\n\n```\n\n### Request fields\n\nAll request parameters are wrapped in a generic `Field` type,\nwhich we use to distinguish zero values from null or omitted fields.\n\nThis prevents accidentally sending a zero value if you forget a required parameter,\nand enables explicitly sending `null`, `false`, `\'\'`, or `0` on optional parameters.\nAny field not specified is not sent.\n\nTo construct fields with values, use the helpers `String()`, `Int()`, `Float()`, or most commonly, the generic `F[T]()`.\nTo send a null, use `Null[T]()`, and to send a nonconforming value, use `Raw[T](any)`. For example:\n\n```go\nparams := FooParams{\n\tName: SDK_PackageName.F("hello"),\n\n\t// Explicitly send `"description": null`\n\tDescription: SDK_PackageName.Null[string](),\n\n\tPoint: SDK_PackageName.F(SDK_PackageName.Point{\n\t\tX: SDK_PackageName.Int(0),\n\t\tY: SDK_PackageName.Int(1),\n\n\t\t// In cases where the API specifies a given type,\n\t\t// but you want to send something else, use `Raw`:\n\t\tZ: SDK_PackageName.Raw[int64](0.01), // sends a float\n\t}),\n}\n```\n\n### Response objects\n\nAll fields in response structs are value types (not pointers or wrappers).\n\nIf a given field is `null`, not present, or invalid, the corresponding field\nwill simply be its zero value.\n\nAll response structs also include a special `JSON` field, containing more detailed\ninformation about each property, which you can use like so:\n\n```go\nif res.Name == "" {\n\t// true if `"name"` is either not present or explicitly null\n\tres.JSON.Name.IsNull()\n\n\t// true if the `"name"` key was not present in the response JSON at all\n\tres.JSON.Name.IsMissing()\n\n\t// When the API returns data that cannot be coerced to the expected type:\n\tif res.JSON.Name.IsInvalid() {\n\t\traw := res.JSON.Name.Raw()\n\n\t\tlegacyName := struct{\n\t\t\tFirst string `json:"first"`\n\t\t\tLast string `json:"last"`\n\t\t}{}\n\t\tjson.Unmarshal([]byte(raw), &legacyName)\n\t\tname = legacyName.First + " " + legacyName.Last\n\t}\n}\n```\n\nThese `.JSON` structs also include an `Extras` map containing\nany properties in the json response that were not specified\nin the struct. This can be useful for API features not yet\npresent in the SDK.\n\n```go\nbody := res.JSON.ExtraFields["my_unexpected_field"].Raw()\n```\n\n### RequestOptions\n\nThis library uses the functional options pattern. Functions defined in the\n`SDK_PackageOptionName` package return a `RequestOption`, which is a closure that mutates a\n`RequestConfig`. These options can be supplied to the client or at individual\nrequests. For example:\n\n```go\nclient := SDK_PackageName.SDK_ClientInitializerName(\n\t// Adds a header to every request made by the client\n\tSDK_PackageOptionName.WithHeader("X-Some-Header", "custom_header_info"),\n)\n\nclient.Brand.Get(context.TODO(), ...,\n\t// Override the header\n\tSDK_PackageOptionName.WithHeader("X-Some-Header", "some_other_custom_header_info"),\n\t// Add an undocumented field to the request body, using sjson syntax\n\tSDK_PackageOptionName.WithJSONSet("some.json.path", map[string]string{"my": "object"}),\n)\n```\n\nSee the [full list of request options](https://pkg.go.dev/github.com/context-dot-dev/context-go-sdk/v2/SDK_PackageOptionName).\n\n### Pagination\n\nThis library provides some conveniences for working with paginated list endpoints.\n\nYou can use `.ListAutoPaging()` methods to iterate through items across all pages:\n\n\n\nOr you can use simple `.List()` methods to fetch a single page and receive a standard response object\nwith additional helper methods like `.GetNextPage()`, e.g.:\n\n\n\n### Errors\n\nWhen the API returns a non-success status code, we return an error with type\n`*SDK_PackageName.Error`. This contains the `StatusCode`, `*http.Request`, and\n`*http.Response` values of the request, as well as the JSON of the error body\n(much like other response objects in the SDK).\n\nTo handle errors, we recommend that you use the `errors.As` pattern:\n\n```go\n_, err := client.Brand.Get(context.TODO(), contextdev.BrandGetParams{\n\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\tDomain: "stripe.com",\n\t},\n})\nif err != nil {\n\tvar apierr *contextdev.Error\n\tif errors.As(err, &apierr) {\n\t\tprintln(string(apierr.DumpRequest(true))) // Prints the serialized HTTP request\n\t\tprintln(string(apierr.DumpResponse(true))) // Prints the serialized HTTP response\n\t}\n\tpanic(err.Error()) // GET "/brand/retrieve": 400 Bad Request { ... }\n}\n```\n\nWhen other errors occur, they are returned unwrapped; for example,\nif HTTP transport fails, you might receive `*url.Error` wrapping `*net.OpError`.\n\n### Timeouts\n\nRequests do not time out by default; use context to configure a timeout for a request lifecycle.\n\nNote that if a request is [retried](#retries), the context timeout does not start over.\nTo set a per-retry timeout, use `SDK_PackageOptionName.WithRequestTimeout()`.\n\n```go\n// This sets the timeout for the request, including all the retries.\nctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)\ndefer cancel()\nclient.Brand.Get(\n\tctx,\n\tcontextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t},\n\t// This sets the per-retry timeout\n\toption.WithRequestTimeout(20*time.Second),\n)\n```\n\n### File uploads\n\nRequest parameters that correspond to file uploads in multipart requests are typed as\n`param.Field[io.Reader]`. The contents of the `io.Reader` will by default be sent as a multipart form\npart with the file name of "anonymous_file" and content-type of "application/octet-stream".\n\nThe file name and content-type can be customized by implementing `Name() string` or `ContentType()\nstring` on the run-time type of `io.Reader`. Note that `os.File` implements `Name() string`, so a\nfile returned by `os.Open` will be sent with the file name on disk.\n\nWe also provide a helper `SDK_PackageName.FileParam(reader io.Reader, filename string, contentType string)`\nwhich can be used to wrap any `io.Reader` with the appropriate file name and content type.\n\n\n\n### Retries\n\nCertain errors will be automatically retried 2 times by default, with a short exponential backoff.\nWe retry by default all connection errors, 408 Request Timeout, 409 Conflict, 429 Rate Limit,\nand >=500 Internal errors.\n\nYou can use the `WithMaxRetries` option to configure or disable this:\n\n```go\n// Configure the default for all requests:\nclient := contextdev.NewClient(\n\toption.WithMaxRetries(0), // default is 2\n)\n\n// Override per-request:\nclient.Brand.Get(\n\tcontext.TODO(),\n\tcontextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t},\n\toption.WithMaxRetries(5),\n)\n```\n\n\n### Accessing raw response data (e.g. response headers)\n\nYou can access the raw HTTP response data by using the `option.WithResponseInto()` request option. This is useful when\nyou need to examine response headers, status codes, or other details.\n\n```go\n// Create a variable to store the HTTP response\nvar response *http.Response\nbrand, err := client.Brand.Get(\n\tcontext.TODO(),\n\tcontextdev.BrandGetParams{\n\t\tOfByDomain: &contextdev.BrandGetParamsBodyByDomain{\n\t\t\tDomain: "stripe.com",\n\t\t},\n\t},\n\toption.WithResponseInto(&response),\n)\nif err != nil {\n\t// handle error\n}\nfmt.Printf("%+v\\n", brand)\n\nfmt.Printf("Status Code: %d\\n", response.StatusCode)\nfmt.Printf("Headers: %+#v\\n", response.Header)\n```\n\n### Making custom/undocumented requests\n\nThis library is typed for convenient access to the documented API. If you need to access undocumented\nendpoints, params, or response properties, the library can still be used.\n\n#### Undocumented endpoints\n\nTo make requests to undocumented endpoints, you can use `client.Get`, `client.Post`, and other HTTP verbs.\n`RequestOptions` on the client, such as retries, will be respected when making these requests.\n\n```go\nvar (\n // params can be an io.Reader, a []byte, an encoding/json serializable object,\n // or a "…Params" struct defined in this library.\n params map[string]interface{}\n\n // result can be an []byte, *http.Response, a encoding/json deserializable object,\n // or a model defined in this library.\n result *http.Response\n)\nerr := client.Post(context.Background(), "/unspecified", params, &result)\nif err != nil {\n …\n}\n```\n\n#### Undocumented request params\n\nTo make requests using undocumented parameters, you may use either the `SDK_PackageOptionName.WithQuerySet()`\nor the `SDK_PackageOptionName.WithJSONSet()` methods.\n\n```go\nparams := FooNewParams{\n ID: SDK_PackageName.F("id_xxxx"),\n Data: SDK_PackageName.F(FooNewParamsData{\n FirstName: SDK_PackageName.F("John"),\n }),\n}\nclient.Foo.New(context.Background(), params, SDK_PackageOptionName.WithJSONSet("data.last_name", "Doe"))\n```\n\n#### Undocumented response properties\n\nTo access undocumented response properties, you may either access the raw JSON of the response as a string\nwith `result.JSON.RawJSON()`, or get the raw JSON of a particular field on the result with\n`result.JSON.Foo.Raw()`.\n\nAny fields that are not present on the response struct will be saved and can be accessed by `result.JSON.ExtraFields()` which returns the extra fields as a `map[string]Field`.\n\n### Middleware\n\nWe provide `SDK_PackageOptionName.WithMiddleware` which applies the given\nmiddleware to requests.\n\n```go\nfunc Logger(req *http.Request, next SDK_PackageOptionName.MiddlewareNext) (res *http.Response, err error) {\n\t// Before the request\n\tstart := time.Now()\n\tLogReq(req)\n\n\t// Forward the request to the next handler\n\tres, err = next(req)\n\n\t// Handle stuff after the request\n\tend := time.Now()\n\tLogRes(res, err, start - end)\n\n return res, err\n}\n\nclient := SDK_PackageName.SDK_ClientInitializerName(\n\tSDK_PackageOptionName.WithMiddleware(Logger),\n)\n```\n\nWhen multiple middlewares are provided as variadic arguments, the middlewares\nare applied left to right. If `SDK_PackageOptionName.WithMiddleware` is given\nmultiple times, for example first in the client then the method, the\nmiddleware in the client will run first and the middleware given in the method\nwill run next.\n\nYou may also replace the default `http.Client` with\n`SDK_PackageOptionName.WithHTTPClient(client)`. Only one http client is\naccepted (this overwrites any previous client) and receives requests after any\nmiddleware has been applied.\n\n## Semantic versioning\n\nThis package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:\n\n1. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_\n2. Changes that we do not expect to impact the vast majority of users in practice.\n\nWe take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.\n\nWe are keen for your feedback; please open an [issue](https://www.github.com/context-dot-dev/context-go-sdk/issues) with questions, bugs, or suggestions.\n\n## Contributing\n\nSee [the contributing documentation](./CONTRIBUTING.md).\n', - }, - { - language: 'cli', - content: - "# Context Dev CLI\n\nThe official CLI for the [Context Dev REST API](https://docs.context.dev/).\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n\n\n## Installation\n\n### Installing with Go\n\nTo test or install the CLI locally, you need [Go](https://go.dev/doc/install) version 1.22 or later installed.\n\n~~~sh\ngo install 'github.com/context-dot-dev/context-dev-cli/cmd/context-dev@latest'\n~~~\n\nOnce you have run `go install`, the binary is placed in your Go bin directory:\n\n- **Default location**: `$HOME/go/bin` (or `$GOPATH/bin` if GOPATH is set)\n- **Check your path**: Run `go env GOPATH` to see the base directory\n\nIf commands aren't found after installation, add the Go bin directory to your PATH:\n\n~~~sh\n# Add to your shell profile (.zshrc, .bashrc, etc.)\nexport PATH=\"$PATH:$(go env GOPATH)/bin\"\n~~~\n\n\n\n### Running Locally\n\nAfter cloning the git repository for this project, you can use the\n`scripts/run` script to run the tool locally:\n\n~~~sh\n./scripts/run args...\n~~~\n\n## Usage\n\nThe CLI follows a resource-based command structure:\n\n~~~sh\ncontext-dev [resource] [flags...]\n~~~\n\n~~~sh\ncontext-dev brand retrieve \\\n --api-key 'My API Key' \\\n --domain REPLACE_ME \\\n --type by_domain\n~~~\n\nFor details about specific commands, use the `--help` flag.\n\n### Environment variables\n\n| Environment variable | Required |\n| --------------------- | -------- |\n| `CONTEXT_DEV_API_KEY` | yes |\n\n### Global flags\n\n- `--api-key` (can also be set with `CONTEXT_DEV_API_KEY` env var)\n- `--help` - Show command line usage\n- `--debug` - Enable debug logging (includes HTTP request/response details)\n- `--version`, `-v` - Show the CLI version\n- `--base-url` - Use a custom API backend URL\n- `--format` - Change the output format (`auto`, `explore`, `json`, `jsonl`, `pretty`, `raw`, `yaml`)\n- `--format-error` - Change the output format for errors (`auto`, `explore`, `json`, `jsonl`, `pretty`, `raw`, `yaml`)\n- `--transform` - Transform the data output using [GJSON syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)\n- `--transform-error` - Transform the error output using [GJSON syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)\n\n### Passing files as arguments\n\nTo pass files to your API, you can use the `@myfile.ext` syntax:\n\n~~~bash\ncontext-dev --arg @abe.jpg\n~~~\n\nFiles can also be passed inside JSON or YAML blobs:\n\n~~~bash\ncontext-dev --arg '{image: \"@abe.jpg\"}'\n# Equivalent:\ncontext-dev < --username '\\@abe'\n~~~\n\n#### Explicit encoding\n\nFor JSON endpoints, the CLI tool does filetype sniffing to determine whether the\nfile contents should be sent as a string literal (for plain text files) or as a\nbase64-encoded string literal (for binary files). If you need to explicitly send\nthe file as either plain text or base64-encoded data, you can use\n`@file://myfile.txt` (for string encoding) or `@data://myfile.dat` (for\nbase64-encoding). Note that absolute paths will begin with `@file://` or\n`@data://`, followed by a third `/` (for example, `@file:///tmp/file.txt`).\n\n~~~bash\ncontext-dev --arg @data://file.txt\n~~~\n\n## Linking different Go SDK versions\n\nYou can link the CLI against a different version of the Context Dev Go SDK\nfor development purposes using the `./scripts/link` script.\n\nTo link to a specific version from a repository (version can be a branch,\ngit tag, or commit hash):\n\n~~~bash\n./scripts/link github.com/org/repo@version\n~~~\n\nTo link to a local copy of the SDK:\n\n~~~bash\n./scripts/link ../path/to/contextdev-go\n~~~\n\nIf you run the link script without any arguments, it will default to `../contextdev-go`.\n", - }, - { - language: 'python', - content: - '# Context Dev Python API library\n\n\n[![PyPI version](https://img.shields.io/pypi/v/context.dev.svg?label=pypi%20(stable))](https://pypi.org/project/context.dev/)\n\nThe Context Dev Python library provides convenient access to the Context Dev REST API from any Python 3.9+\napplication. The library includes type definitions for all request params and response fields,\nand offers both synchronous and asynchronous clients powered by [httpx](https://github.com/encode/httpx).\n\n\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n## MCP Server\n\nUse the Context Dev MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0)\n[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D)\n\n> Note: You may need to set environment variables in your MCP client.\n\n## Documentation\n\nThe REST API documentation can be found on [docs.context.dev](https://docs.context.dev/). The full API of this library can be found in [api.md](api.md).\n\n## Installation\n\n```sh\n# install from PyPI\npip install context.dev\n```\n\n## Usage\n\nThe full API of this library can be found in [api.md](api.md).\n\n```python\nimport os\nfrom context.dev import ContextDev\n\nclient = ContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\n\nbrand = client.brand.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n)\nprint(brand.cache_metadata)\n```\n\nWhile you can provide an `api_key` keyword argument,\nwe recommend using [python-dotenv](https://pypi.org/project/python-dotenv/)\nto add `CONTEXT_DEV_API_KEY="My API Key"` to your `.env` file\nso that your API Key is not stored in source control.\n\n## Async usage\n\nSimply import `AsyncContextDev` instead of `ContextDev` and use `await` with each API call:\n\n```python\nimport os\nimport asyncio\nfrom context.dev import AsyncContextDev\n\nclient = AsyncContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n)\n\nasync def main() -> None:\n brand = await client.brand.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n )\n print(brand.cache_metadata)\n\nasyncio.run(main())\n```\n\nFunctionality between the synchronous and asynchronous clients is otherwise identical.\n\n### With aiohttp\n\nBy default, the async client uses `httpx` for HTTP requests. However, for improved concurrency performance you may also use `aiohttp` as the HTTP backend.\n\nYou can enable this by installing `aiohttp`:\n\n```sh\n# install from PyPI\npip install context.dev[aiohttp]\n```\n\nThen you can enable it by instantiating the client with `http_client=DefaultAioHttpClient()`:\n\n```python\nimport os\nimport asyncio\nfrom context.dev import DefaultAioHttpClient\nfrom context.dev import AsyncContextDev\n\nasync def main() -> None:\n async with AsyncContextDev(\n api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted\n http_client=DefaultAioHttpClient(),\n) as client:\n brand = await client.brand.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n )\n print(brand.cache_metadata)\n\nasyncio.run(main())\n```\n\n\n\n## Using types\n\nNested request parameters are [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict). Responses are [Pydantic models](https://docs.pydantic.dev) which also provide helper methods for things like:\n\n- Serializing back into JSON, `model.to_json()`\n- Converting to a dictionary, `model.to_dict()`\n\nTyped requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `basic`.\n\n\n\n## Nested params\n\nNested parameters are dictionaries, typed using `TypedDict`, for example:\n\n```python\nfrom context.dev import ContextDev\n\nclient = ContextDev()\n\nresponse = client.parse.handle(\n body=b"Example data",\n pdf={},\n)\nprint(response.pdf)\n```\n\n\n\n## Handling errors\n\nWhen the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of `context.dev.APIConnectionError` is raised.\n\nWhen the API returns a non-success status code (that is, 4xx or 5xx\nresponse), a subclass of `context.dev.APIStatusError` is raised, containing `status_code` and `response` properties.\n\nAll errors inherit from `context.dev.APIError`.\n\n```python\nimport context.dev\nfrom context.dev import ContextDev\n\nclient = ContextDev()\n\ntry:\n client.brand.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n )\nexcept context.dev.APIConnectionError as e:\n print("The server could not be reached")\n print(e.__cause__) # an underlying Exception, likely raised within httpx.\nexcept context.dev.RateLimitError as e:\n print("A 429 status code was received; we should back off a bit.")\nexcept context.dev.APIStatusError as e:\n print("Another non-200-range status code was received")\n print(e.status_code)\n print(e.response)\n```\n\nError codes are as follows:\n\n| Status Code | Error Type |\n| ----------- | -------------------------- |\n| 400 | `BadRequestError` |\n| 401 | `AuthenticationError` |\n| 403 | `PermissionDeniedError` |\n| 404 | `NotFoundError` |\n| 422 | `UnprocessableEntityError` |\n| 429 | `RateLimitError` |\n| >=500 | `InternalServerError` |\n| N/A | `APIConnectionError` |\n\n### Retries\n\nCertain errors are automatically retried 2 times by default, with a short exponential backoff.\nConnection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,\n429 Rate Limit, and >=500 Internal errors are all retried by default.\n\nYou can use the `max_retries` option to configure or disable retry settings:\n\n```python\nfrom context.dev import ContextDev\n\n# Configure the default for all requests:\nclient = ContextDev(\n # default is 2\n max_retries=0,\n)\n\n# Or, configure per-request:\nclient.with_options(max_retries = 5).brand.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n)\n```\n\n### Timeouts\n\nBy default requests time out after 1 minute. You can configure this with a `timeout` option,\nwhich accepts a float or an [`httpx.Timeout`](https://www.python-httpx.org/advanced/timeouts/#fine-tuning-the-configuration) object:\n\n```python\nfrom context.dev import ContextDev\n\n# Configure the default for all requests:\nclient = ContextDev(\n # 20 seconds (default is 1 minute)\n timeout=20.0,\n)\n\n# More granular control:\nclient = ContextDev(\n timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),\n)\n\n# Override per-request:\nclient.with_options(timeout = 5.0).brand.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n)\n```\n\nOn timeout, an `APITimeoutError` is thrown.\n\nNote that requests that time out are [retried twice by default](#retries).\n\n\n\n## Advanced\n\n### Logging\n\nWe use the standard library [`logging`](https://docs.python.org/3/library/logging.html) module.\n\nYou can enable logging by setting the environment variable `CONTEXT_DEV_LOG` to `info`.\n\n```shell\n$ export CONTEXT_DEV_LOG=info\n```\n\nOr to `debug` for more verbose logging.\n\n### How to tell whether `None` means `null` or missing\n\nIn an API response, a field may be explicitly `null`, or missing entirely; in either case, its value is `None` in this library. You can differentiate the two cases with `.model_fields_set`:\n\n```py\nif response.my_field is None:\n if \'my_field\' not in response.model_fields_set:\n print(\'Got json like {}, without a "my_field" key present at all.\')\n else:\n print(\'Got json like {"my_field": null}.\')\n```\n\n### Accessing raw response data (e.g. headers)\n\nThe "raw" Response object can be accessed by prefixing `.with_raw_response.` to any HTTP method call, e.g.,\n\n```py\nfrom context.dev import ContextDev\n\nclient = ContextDev()\nresponse = client.brand.with_raw_response.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n)\nprint(response.headers.get(\'X-My-Header\'))\n\nbrand = response.parse() # get the object that `brand.retrieve()` would have returned\nprint(brand.cache_metadata)\n```\n\nThese methods return an [`APIResponse`](https://github.com/context-dot-dev/context-python-sdk/tree/main/src/context/dev/_response.py) object.\n\nThe async client returns an [`AsyncAPIResponse`](https://github.com/context-dot-dev/context-python-sdk/tree/main/src/context/dev/_response.py) with the same structure, the only difference being `await`able methods for reading the response content.\n\n#### `.with_streaming_response`\n\nThe above interface eagerly reads the full response body when you make the request, which may not always be what you want.\n\nTo stream the response body, use `.with_streaming_response` instead, which requires a context manager and only reads the response body once you call `.read()`, `.text()`, `.json()`, `.iter_bytes()`, `.iter_text()`, `.iter_lines()` or `.parse()`. In the async client, these are async methods.\n\n```python\nwith client.brand.with_streaming_response.retrieve(\n domain="REPLACE_ME",\n type="by_domain",\n) as response :\n print(response.headers.get(\'X-My-Header\'))\n\n for line in response.iter_lines():\n print(line)\n```\n\nThe context manager is required so that the response will reliably be closed.\n\n### Making custom/undocumented requests\n\nThis library is typed for convenient access to the documented API.\n\nIf you need to access undocumented endpoints, params, or response properties, the library can still be used.\n\n#### Undocumented endpoints\n\nTo make requests to undocumented endpoints, you can make requests using `client.get`, `client.post`, and other\nhttp verbs. Options on the client will be respected (such as retries) when making this request.\n\n```py\nimport httpx\n\nresponse = client.post(\n "/foo",\n cast_to=httpx.Response,\n body={"my_param": True},\n)\n\nprint(response.headers.get("x-foo"))\n```\n\n#### Undocumented request params\n\nIf you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` request\noptions.\n\n#### Undocumented response properties\n\nTo access undocumented response properties, you can access the extra fields like `response.unknown_prop`. You\ncan also get all the extra fields on the Pydantic model as a dict with\n[`response.model_extra`](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_extra).\n\n### Configuring the HTTP client\n\nYou can directly override the [httpx client](https://www.python-httpx.org/api/#client) to customize it for your use case, including:\n\n- Support for [proxies](https://www.python-httpx.org/advanced/proxies/)\n- Custom [transports](https://www.python-httpx.org/advanced/transports/)\n- Additional [advanced](https://www.python-httpx.org/advanced/clients/) functionality\n\n```python\nimport httpx\nfrom context.dev import ContextDev, DefaultHttpxClient\n\nclient = ContextDev(\n # Or use the `CONTEXT_DEV_BASE_URL` env var\n base_url="http://my.test.server.example.com:8083",\n http_client=DefaultHttpxClient(proxy="http://my.test.proxy.example.com", transport=httpx.HTTPTransport(local_address="0.0.0.0")),\n)\n```\n\nYou can also customize the client on a per-request basis by using `with_options()`:\n\n```python\nclient.with_options(http_client=DefaultHttpxClient(...))\n```\n\n### Managing HTTP resources\n\nBy default the library closes underlying HTTP connections whenever the client is [garbage collected](https://docs.python.org/3/reference/datamodel.html#object.__del__). You can manually close the client using the `.close()` method if desired, or with a context manager that closes when exiting.\n\n```py\nfrom context.dev import ContextDev\n\nwith ContextDev() as client:\n # make requests here\n ...\n\n# HTTP client is now closed\n```\n\n## Versioning\n\nThis package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:\n\n1. Changes that only affect static types, without breaking runtime behavior.\n2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_\n3. Changes that we do not expect to impact the vast majority of users in practice.\n\nWe take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.\n\nWe are keen for your feedback; please open an [issue](https://www.github.com/context-dot-dev/context-python-sdk/issues) with questions, bugs, or suggestions.\n\n### Determining the installed version\n\nIf you\'ve upgraded to the latest version but aren\'t seeing any new features you were expecting then your python environment is likely still using an older version.\n\nYou can determine the version that is being used at runtime with:\n\n```py\nimport context.dev\nprint(context.dev.__version__)\n```\n\n## Requirements\n\nPython 3.9 or higher.\n\n## Contributing\n\nSee [the contributing documentation](./CONTRIBUTING.md).\n', - }, - { - language: 'ruby', - content: - '# Context Dev Ruby API library\n\nThe Context Dev Ruby library provides convenient access to the Context Dev REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/context-dot-dev/context-ruby-sdk#Sorbet) for usage with Sorbet. The standard library\'s `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.\n\n\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n## MCP Server\n\nUse the Context Dev MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0)\n[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D)\n\n> Note: You may need to set environment variables in your MCP client.\n\n## Documentation\n\nDocumentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/context.dev).\n\nThe REST API documentation can be found on [docs.context.dev](https://docs.context.dev/).\n\n## Installation\n\nTo use this gem, install via Bundler by adding the following to your application\'s `Gemfile`:\n\n\n\n```ruby\ngem "context.dev", "~> 2.13.0"\n```\n\n\n\n## Usage\n\n```ruby\nrequire "bundler/setup"\nrequire "context_dev"\n\ncontext_dev = ContextDev::Client.new(\n api_key: ENV["CONTEXT_DEV_API_KEY"] # This is the default and can be omitted\n)\n\nbrand = context_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"})\n\nputs(brand.cache_metadata)\n```\n\n\n\n\n\n\n\n### Handling errors\n\nWhen the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `ContextDev::Errors::APIError` will be thrown:\n\n```ruby\nbegin\n brand = context_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"})\nrescue ContextDev::Errors::APIConnectionError => e\n puts("The server could not be reached")\n puts(e.cause) # an underlying Exception, likely raised within `net/http`\nrescue ContextDev::Errors::RateLimitError => e\n puts("A 429 status code was received; we should back off a bit.")\nrescue ContextDev::Errors::APIStatusError => e\n puts("Another non-200-range status code was received")\n puts(e.status)\nend\n```\n\nError codes are as follows:\n\n| Cause | Error Type |\n| ---------------- | -------------------------- |\n| HTTP 400 | `BadRequestError` |\n| HTTP 401 | `AuthenticationError` |\n| HTTP 403 | `PermissionDeniedError` |\n| HTTP 404 | `NotFoundError` |\n| HTTP 409 | `ConflictError` |\n| HTTP 422 | `UnprocessableEntityError` |\n| HTTP 429 | `RateLimitError` |\n| HTTP >= 500 | `InternalServerError` |\n| Other HTTP error | `APIStatusError` |\n| Timeout | `APITimeoutError` |\n| Network error | `APIConnectionError` |\n\n### Retries\n\nCertain errors will be automatically retried 2 times by default, with a short exponential backoff.\n\nConnection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.\n\nYou can use the `max_retries` option to configure or disable this:\n\n```ruby\n# Configure the default for all requests:\ncontext_dev = ContextDev::Client.new(\n max_retries: 0 # default is 2\n)\n\n# Or, configure per-request:\ncontext_dev.brand.retrieve(\n body: {domain: "stripe.com", type: "by_domain"},\n request_options: {max_retries: 5}\n)\n```\n\n### Timeouts\n\nBy default, requests will time out after 60 seconds. You can use the timeout option to configure or disable this:\n\n```ruby\n# Configure the default for all requests:\ncontext_dev = ContextDev::Client.new(\n timeout: nil # default is 60\n)\n\n# Or, configure per-request:\ncontext_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"}, request_options: {timeout: 5})\n```\n\nOn timeout, `ContextDev::Errors::APITimeoutError` is raised.\n\nNote that requests that time out are retried by default.\n\n## Advanced concepts\n\n### BaseModel\n\nAll parameter and response objects inherit from `ContextDev::Internal::Type::BaseModel`, which provides several conveniences, including:\n\n1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.\n\n2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.\n\n3. Both instances and the classes themselves can be pretty-printed.\n\n4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.\n\n### Making custom or undocumented requests\n\n#### Undocumented properties\n\nYou can send undocumented parameters to any endpoint, and read undocumented response properties, like so:\n\nNote: the `extra_` parameters of the same name overrides the documented parameters.\n\n```ruby\nbrand =\n context_dev.brand.retrieve(\n body: {domain: "stripe.com", type: "by_domain"},\n request_options: {\n extra_query: {my_query_parameter: value},\n extra_body: {my_body_parameter: value},\n extra_headers: {"my-header": value}\n }\n )\n\nputs(brand[:my_undocumented_property])\n```\n\n#### Undocumented request params\n\nIf you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request, as seen in the examples above.\n\n#### Undocumented endpoints\n\nTo make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using `client.request`, like so:\n\n```ruby\nresponse = client.request(\n method: :post,\n path: \'/undocumented/endpoint\',\n query: {"dog": "woof"},\n headers: {"useful-header": "interesting-value"},\n body: {"hello": "world"}\n)\n```\n\n### Concurrency & connection pooling\n\nThe `ContextDev::Client` instances are threadsafe, but are only are fork-safe when there are no in-flight HTTP requests.\n\nEach instance of `ContextDev::Client` has its own HTTP connection pool with a default size of 99. As such, we recommend instantiating the client once per application in most settings.\n\nWhen all available connections from the pool are checked out, requests wait for a new connection to become available, with queue time counting towards the request timeout.\n\nUnless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.\n\n## Sorbet\n\nThis library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.\n\nYou can provide typesafe request parameters like so:\n\n```ruby\ncontext_dev.brand.retrieve(\n body: ContextDev::BrandRetrieveParams::Body::ByDomain.new(domain: "stripe.com")\n)\n```\n\nOr, equivalently:\n\n```ruby\n# Hashes work, but are not typesafe:\ncontext_dev.brand.retrieve(body: {domain: "stripe.com", type: "by_domain"})\n\n# You can also splat a full Params class:\nparams = ContextDev::BrandRetrieveParams.new(\n body: ContextDev::BrandRetrieveParams::Body::ByDomain.new(domain: "stripe.com")\n)\ncontext_dev.brand.retrieve(**params)\n```\n\n### Enums\n\nSince this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:\n\n```ruby\n# :txt\nputs(ContextDev::ParseHandleParams::Extension::TXT)\n\n# Revealed type: `T.all(ContextDev::ParseHandleParams::Extension, Symbol)`\nT.reveal_type(ContextDev::ParseHandleParams::Extension::TXT)\n```\n\nEnum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:\n\n```ruby\n# Using the enum constants preserves the tagged type information:\ncontext_dev.parse.handle(\n extension: ContextDev::ParseHandleParams::Extension::TXT,\n # …\n)\n\n# Literal values are also permissible:\ncontext_dev.parse.handle(\n extension: :txt,\n # …\n)\n```\n\n## Versioning\n\nThis package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.\n\nThis package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.\n\n## Requirements\n\nRuby 3.2.0 or higher.\n\n## Contributing\n\nSee [the contributing documentation](https://github.com/context-dot-dev/context-ruby-sdk/tree/main/CONTRIBUTING.md).\n', - }, - { - language: 'typescript', - content: - "# Context Dev TypeScript API Library\n\n[![NPM version](https://img.shields.io/npm/v/context.dev.svg?label=npm%20(stable))](https://npmjs.org/package/context.dev) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/context.dev)\n\nThis library provides convenient access to the Context Dev REST API from server-side TypeScript or JavaScript.\n\n\n\nThe REST API documentation can be found on [docs.context.dev](https://docs.context.dev/). The full API of this library can be found in [api.md](api.md).\n\nIt is generated with [Stainless](https://www.stainless.com/).\n\n## MCP Server\n\nUse the Context Dev MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=context.dev-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvbnRleHQuZGV2LW1jcCJdLCJlbnYiOnsiQ09OVEVYVF9ERVZfQVBJX0tFWSI6Ik15IEFQSSBLZXkifX0)\n[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22context.dev-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22context.dev-mcp%22%5D%2C%22env%22%3A%7B%22CONTEXT_DEV_API_KEY%22%3A%22My%20API%20Key%22%7D%7D)\n\n> Note: You may need to set environment variables in your MCP client.\n\n## Installation\n\n```sh\nnpm install context.dev\n```\n\n\n\n## Usage\n\nThe full API of this library can be found in [api.md](api.md).\n\n\n```js\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst brand = await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' });\n\nconsole.log(brand.cache_metadata);\n```\n\n\n\n### Request & Response types\n\nThis library includes TypeScript definitions for all request params and response fields. You may import and use them like so:\n\n\n```ts\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted\n});\n\nconst params: ContextDev.BrandRetrieveParams = { domain: 'REPLACE_ME', type: 'by_domain' };\nconst brand: ContextDev.BrandRetrieveResponse = await client.brand.retrieve(params);\n```\n\nDocumentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.\n\n\n\n\n\n## Handling errors\n\nWhen the library is unable to connect to the API,\nor if the API returns a non-success status code (i.e., 4xx or 5xx response),\na subclass of `APIError` will be thrown:\n\n\n```ts\nconst brand = await client.brand\n .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' })\n .catch(async (err) => {\n if (err instanceof ContextDev.APIError) {\n console.log(err.status); // 400\n console.log(err.name); // BadRequestError\n console.log(err.headers); // {server: 'nginx', ...}\n } else {\n throw err;\n }\n });\n```\n\nError codes are as follows:\n\n| Status Code | Error Type |\n| ----------- | -------------------------- |\n| 400 | `BadRequestError` |\n| 401 | `AuthenticationError` |\n| 403 | `PermissionDeniedError` |\n| 404 | `NotFoundError` |\n| 422 | `UnprocessableEntityError` |\n| 429 | `RateLimitError` |\n| >=500 | `InternalServerError` |\n| N/A | `APIConnectionError` |\n\n### Retries\n\nCertain errors will be automatically retried 2 times by default, with a short exponential backoff.\nConnection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,\n429 Rate Limit, and >=500 Internal errors will all be retried by default.\n\nYou can use the `maxRetries` option to configure or disable this:\n\n\n```js\n// Configure the default for all requests:\nconst client = new ContextDev({\n maxRetries: 0, // default is 2\n});\n\n// Or, configure per-request:\nawait client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }, {\n maxRetries: 5,\n});\n```\n\n### Timeouts\n\nRequests time out after 1 minute by default. You can configure this with a `timeout` option:\n\n\n```ts\n// Configure the default for all requests:\nconst client = new ContextDev({\n timeout: 20 * 1000, // 20 seconds (default is 1 minute)\n});\n\n// Override per-request:\nawait client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }, {\n timeout: 5 * 1000,\n});\n```\n\nOn timeout, an `APIConnectionTimeoutError` is thrown.\n\nNote that requests which time out will be [retried twice by default](#retries).\n\n\n\n\n\n## Advanced Usage\n\n### Accessing raw Response data (e.g., headers)\n\nThe \"raw\" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.\nThis method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.\n\nYou can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.\nUnlike `.asResponse()` this method consumes the body, returning once it is parsed.\n\n\n```ts\nconst client = new ContextDev();\n\nconst response = await client.brand\n .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' })\n .asResponse();\nconsole.log(response.headers.get('X-My-Header'));\nconsole.log(response.statusText); // access the underlying Response object\n\nconst { data: brand, response: raw } = await client.brand\n .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' })\n .withResponse();\nconsole.log(raw.headers.get('X-My-Header'));\nconsole.log(brand.cache_metadata);\n```\n\n### Logging\n\n> [!IMPORTANT]\n> All log messages are intended for debugging only. The format and content of log messages\n> may change between releases.\n\n#### Log levels\n\nThe log level can be configured in two ways:\n\n1. Via the `CONTEXT_DEV_LOG` environment variable\n2. Using the `logLevel` client option (overrides the environment variable if set)\n\n```ts\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n logLevel: 'debug', // Show all log messages\n});\n```\n\nAvailable log levels, from most to least verbose:\n\n- `'debug'` - Show debug messages, info, warnings, and errors\n- `'info'` - Show info messages, warnings, and errors\n- `'warn'` - Show warnings and errors (default)\n- `'error'` - Show only errors\n- `'off'` - Disable all logging\n\nAt the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.\nSome authentication-related headers are redacted, but sensitive data in request and response bodies\nmay still be visible.\n\n#### Custom logger\n\nBy default, this library logs to `globalThis.console`. You can also provide a custom logger.\nMost logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.\n\nWhen providing a custom logger, the `logLevel` option still controls which messages are emitted, messages\nbelow the configured level will not be sent to your logger.\n\n```ts\nimport ContextDev from 'context.dev';\nimport pino from 'pino';\n\nconst logger = pino();\n\nconst client = new ContextDev({\n logger: logger.child({ name: 'ContextDev' }),\n logLevel: 'debug', // Send all messages to pino, allowing it to filter\n});\n```\n\n### Making custom/undocumented requests\n\nThis library is typed for convenient access to the documented API. If you need to access undocumented\nendpoints, params, or response properties, the library can still be used.\n\n#### Undocumented endpoints\n\nTo make requests to undocumented endpoints, you can use `client.get`, `client.post`, and other HTTP verbs.\nOptions on the client, such as retries, will be respected when making these requests.\n\n```ts\nawait client.post('/some/path', {\n body: { some_prop: 'foo' },\n query: { some_query_arg: 'bar' },\n});\n```\n\n#### Undocumented request params\n\nTo make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented\nparameter. This library doesn't validate at runtime that the request matches the type, so any extra values you\nsend will be sent as-is.\n\n```ts\nclient.brand.retrieve({\n // ...\n // @ts-expect-error baz is not yet public\n baz: 'undocumented option',\n});\n```\n\nFor requests with the `GET` verb, any extra params will be in the query, all other requests will send the\nextra param in the body.\n\nIf you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request\noptions.\n\n#### Undocumented response properties\n\nTo access undocumented response properties, you may access the response object with `// @ts-expect-error` on\nthe response object, or cast the response object to the requisite type. Like the request params, we do not\nvalidate or strip extra properties from the response from the API.\n\n### Customizing the fetch client\n\nBy default, this library expects a global `fetch` function is defined.\n\nIf you want to use a different `fetch` function, you can either polyfill the global:\n\n```ts\nimport fetch from 'my-fetch';\n\nglobalThis.fetch = fetch;\n```\n\nOr pass it to the client:\n\n```ts\nimport ContextDev from 'context.dev';\nimport fetch from 'my-fetch';\n\nconst client = new ContextDev({ fetch });\n```\n\n### Fetch options\n\nIf you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)\n\n```ts\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n fetchOptions: {\n // `RequestInit` options\n },\n});\n```\n\n#### Configuring proxies\n\nTo modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy\noptions to requests:\n\n **Node** [[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]\n\n```ts\nimport ContextDev from 'context.dev';\nimport * as undici from 'undici';\n\nconst proxyAgent = new undici.ProxyAgent('http://localhost:8888');\nconst client = new ContextDev({\n fetchOptions: {\n dispatcher: proxyAgent,\n },\n});\n```\n\n **Bun** [[docs](https://bun.sh/guides/http/proxy)]\n\n```ts\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev({\n fetchOptions: {\n proxy: 'http://localhost:8888',\n },\n});\n```\n\n **Deno** [[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]\n\n```ts\nimport ContextDev from 'npm:context.dev';\n\nconst httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });\nconst client = new ContextDev({\n fetchOptions: {\n client: httpClient,\n },\n});\n```\n\n## Frequently Asked Questions\n\n## Semantic versioning\n\nThis package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:\n\n1. Changes that only affect static types, without breaking runtime behavior.\n2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_\n3. Changes that we do not expect to impact the vast majority of users in practice.\n\nWe take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.\n\nWe are keen for your feedback; please open an [issue](https://www.github.com/context-dot-dev/context-typescript-sdk/issues) with questions, bugs, or suggestions.\n\n## Requirements\n\nTypeScript >= 4.9 is supported.\n\nThe following runtimes are supported:\n\n- Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)\n- Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.\n- Deno v1.28.0 or higher.\n- Bun 1.0 or later.\n- Cloudflare Workers.\n- Vercel Edge Runtime.\n- Jest 28 or greater with the `\"node\"` environment (`\"jsdom\"` is not supported at this time).\n- Nitro v2.6 or greater.\n\nNote that React Native is not supported at this time.\n\nIf you are interested in other runtime environments, please open or upvote an issue on GitHub.\n\n## Contributing\n\nSee [the contributing documentation](./CONTRIBUTING.md).\n", - }, -]; - -const INDEX_OPTIONS = { - fields: [ - 'name', - 'endpoint', - 'summary', - 'description', - 'qualified', - 'stainlessPath', - 'content', - 'sectionContext', - ], - storeFields: ['kind', '_original'], - searchOptions: { - prefix: true, - fuzzy: 0.1, - boost: { - name: 5, - stainlessPath: 3, - endpoint: 3, - qualified: 3, - summary: 2, - content: 1, - description: 1, - } as Record, - }, -}; - -/** - * Self-contained local search engine backed by MiniSearch. - * Method data is embedded at SDK build time; prose documents - * can be loaded from an optional docs directory at runtime. - */ -export class LocalDocsSearch { - private methodIndex: MiniSearch; - private proseIndex: MiniSearch; - - private constructor() { - this.methodIndex = new MiniSearch(INDEX_OPTIONS); - this.proseIndex = new MiniSearch(INDEX_OPTIONS); - } - - static async create(opts?: { docsDir?: string }): Promise { - const instance = new LocalDocsSearch(); - instance.indexMethods(EMBEDDED_METHODS); - for (const readme of EMBEDDED_READMES) { - instance.indexProse(readme.content, `readme:${readme.language}`); - } - if (opts?.docsDir) { - await instance.loadDocsDirectory(opts.docsDir); - } - return instance; - } - - search(props: { - query: string; - language?: string; - detail?: string; - maxResults?: number; - maxLength?: number; - }): SearchResult { - const { query, language = 'typescript', detail = 'default', maxResults = 5, maxLength = 100_000 } = props; - - const useMarkdown = detail === 'verbose' || detail === 'high'; - - // Search both indices and merge results by score. - // Filter prose hits so language-tagged content (READMEs and docs with - // frontmatter) only matches the requested language. - const methodHits = this.methodIndex - .search(query) - .map((hit) => ({ ...hit, _kind: 'http_method' as const })); - const proseHits = this.proseIndex - .search(query) - .filter((hit) => { - const source = ((hit as Record)['_original'] as ProseChunk | undefined)?.source; - if (!source) return true; - // Check for language-tagged sources: "readme:" or "lang::" - let taggedLang: string | undefined; - if (source.startsWith('readme:')) taggedLang = source.slice('readme:'.length); - else if (source.startsWith('lang:')) taggedLang = source.split(':')[1]; - if (!taggedLang) return true; - return taggedLang === language || (language === 'javascript' && taggedLang === 'typescript'); - }) - .map((hit) => ({ ...hit, _kind: 'prose' as const })); - const merged = [...methodHits, ...proseHits].sort((a, b) => b.score - a.score); - const top = merged.slice(0, maxResults); - - const fullResults: (string | Record)[] = []; - - for (const hit of top) { - const original = (hit as Record)['_original']; - if (hit._kind === 'http_method') { - const m = original as MethodEntry; - if (useMarkdown && m.markdown) { - fullResults.push(m.markdown); - } else { - // Use per-language data when available, falling back to the - // top-level fields (which are TypeScript-specific in the - // legacy codepath). - const langData = m.perLanguage?.[language]; - fullResults.push({ - method: langData?.method ?? m.qualified, - summary: m.summary, - description: m.description, - endpoint: `${m.httpMethod.toUpperCase()} ${m.endpoint}`, - ...(langData?.example ? { example: langData.example } : {}), - ...(m.params ? { params: m.params } : {}), - ...(m.response ? { response: m.response } : {}), - }); - } - } else { - const c = original as ProseChunk; - fullResults.push({ - content: c.content, - ...(c.source ? { source: c.source } : {}), - }); - } - } - - let totalLength = 0; - const results: (string | Record)[] = []; - for (const result of fullResults) { - const len = typeof result === 'string' ? result.length : JSON.stringify(result).length; - totalLength += len; - if (totalLength > maxLength) break; - results.push(result); - } - - if (results.length < fullResults.length) { - results.unshift(`Truncated; showing ${results.length} of ${fullResults.length} results.`); - } - - return { results }; - } - - private indexMethods(methods: MethodEntry[]): void { - const docs: MiniSearchDocument[] = methods.map((m, i) => ({ - id: `method-${i}`, - kind: 'http_method' as const, - name: m.name, - endpoint: m.endpoint, - summary: m.summary, - description: m.description, - qualified: m.qualified, - stainlessPath: m.stainlessPath, - _original: m as unknown as Record, - })); - if (docs.length > 0) { - this.methodIndex.addAll(docs); - } - } - - private async loadDocsDirectory(docsDir: string): Promise { - let entries; - try { - entries = await fs.readdir(docsDir, { withFileTypes: true }); - } catch (err) { - getLogger().warn({ err, docsDir }, 'Could not read docs directory'); - return; - } - - const files = entries - .filter((e) => e.isFile()) - .filter((e) => e.name.endsWith('.md') || e.name.endsWith('.markdown') || e.name.endsWith('.json')); - - for (const file of files) { - try { - const filePath = path.join(docsDir, file.name); - const content = await fs.readFile(filePath, 'utf-8'); - - if (file.name.endsWith('.json')) { - const texts = extractTexts(JSON.parse(content)); - if (texts.length > 0) { - this.indexProse(texts.join('\n\n'), file.name); - } - } else { - // Parse optional YAML frontmatter for language tagging. - // Files with a "language" field in frontmatter will only - // surface in searches for that language. - // - // Example: - // --- - // language: python - // --- - // # Error handling in Python - // ... - const frontmatter = parseFrontmatter(content); - const source = frontmatter.language ? `lang:${frontmatter.language}:${file.name}` : file.name; - this.indexProse(content, source); - } - } catch (err) { - getLogger().warn({ err, file: file.name }, 'Failed to index docs file'); - } - } - } - - private indexProse(markdown: string, source: string): void { - const chunks = chunkMarkdown(markdown); - const baseId = this.proseIndex.documentCount; - - const docs: MiniSearchDocument[] = chunks.map((chunk, i) => ({ - id: `prose-${baseId + i}`, - kind: 'prose' as const, - content: chunk.content, - ...(chunk.sectionContext != null ? { sectionContext: chunk.sectionContext } : {}), - _original: { ...chunk, source } as unknown as Record, - })); - - if (docs.length > 0) { - this.proseIndex.addAll(docs); - } - } -} - -/** Lightweight markdown chunker — splits on headers, chunks by word count. */ -function chunkMarkdown(markdown: string): { content: string; tag: string; sectionContext?: string }[] { - // Strip YAML frontmatter - const stripped = markdown.replace(/^---\n[\s\S]*?\n---\n?/, ''); - const lines = stripped.split('\n'); - - const chunks: { content: string; tag: string; sectionContext?: string }[] = []; - const headers: string[] = []; - let current: string[] = []; - - const flush = () => { - const text = current.join('\n').trim(); - if (!text) return; - const sectionContext = headers.length > 0 ? headers.join(' > ') : undefined; - // Split into ~200-word chunks - const words = text.split(/\s+/); - for (let i = 0; i < words.length; i += 200) { - const slice = words.slice(i, i + 200).join(' '); - if (slice) { - chunks.push({ content: slice, tag: 'p', ...(sectionContext != null ? { sectionContext } : {}) }); - } - } - current = []; - }; - - for (const line of lines) { - const headerMatch = line.match(/^(#{1,6})\s+(.+)/); - if (headerMatch) { - flush(); - const level = headerMatch[1]!.length; - const text = headerMatch[2]!.trim(); - while (headers.length >= level) headers.pop(); - headers.push(text); - } else { - current.push(line); - } - } - flush(); - - return chunks; -} - -/** Recursively extracts string values from a JSON structure. */ -function extractTexts(data: unknown, depth = 0): string[] { - if (depth > 10) return []; - if (typeof data === 'string') return data.trim() ? [data] : []; - if (Array.isArray(data)) return data.flatMap((item) => extractTexts(item, depth + 1)); - if (typeof data === 'object' && data !== null) { - return Object.values(data).flatMap((v) => extractTexts(v, depth + 1)); - } - return []; -} - -/** Parses YAML frontmatter from a markdown string, extracting the language field if present. */ -function parseFrontmatter(markdown: string): { language?: string } { - const match = markdown.match(/^---\n([\s\S]*?)\n---/); - if (!match) return {}; - const body = match[1] ?? ''; - const langMatch = body.match(/^language:\s*(.+)$/m); - return langMatch ? { language: langMatch[1]!.trim() } : {}; -} diff --git a/packages/mcp-server/src/logger.ts b/packages/mcp-server/src/logger.ts deleted file mode 100644 index 29dab11c..00000000 --- a/packages/mcp-server/src/logger.ts +++ /dev/null @@ -1,28 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { pino, type Level, type Logger } from 'pino'; -import pretty from 'pino-pretty'; - -let _logger: Logger | undefined; - -export function configureLogger({ level, pretty: usePretty }: { level: Level; pretty: boolean }): void { - _logger = pino( - { - level, - timestamp: pino.stdTimeFunctions.isoTime, - formatters: { - level(label) { - return { level: label }; - }, - }, - }, - usePretty ? pretty({ colorize: true, levelFirst: true, destination: 2 }) : process.stderr, - ); -} - -export function getLogger(): Logger { - if (!_logger) { - throw new Error('Logger has not been configured. Call configureLogger() before using the logger.'); - } - return _logger; -} diff --git a/packages/mcp-server/src/methods.ts b/packages/mcp-server/src/methods.ts deleted file mode 100644 index 71e4da35..00000000 --- a/packages/mcp-server/src/methods.ts +++ /dev/null @@ -1,332 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { McpOptions } from './options'; - -export type SdkMethod = { - clientCallName: string; - fullyQualifiedName: string; - httpMethod?: 'get' | 'post' | 'put' | 'patch' | 'delete' | 'query'; - httpPath?: string; -}; - -export const sdkMethods: SdkMethod[] = [ - { - clientCallName: 'client.parse.handle', - fullyQualifiedName: 'parse.handle', - httpMethod: 'post', - httpPath: '/parse', - }, - { - clientCallName: 'client.web.extract', - fullyQualifiedName: 'web.extract', - httpMethod: 'post', - httpPath: '/web/extract', - }, - { - clientCallName: 'client.web.extractCompetitors', - fullyQualifiedName: 'web.extractCompetitors', - httpMethod: 'get', - httpPath: '/web/competitors', - }, - { - clientCallName: 'client.web.extractFonts', - fullyQualifiedName: 'web.extractFonts', - httpMethod: 'get', - httpPath: '/web/fonts', - }, - { - clientCallName: 'client.web.extractStyleguide', - fullyQualifiedName: 'web.extractStyleguide', - httpMethod: 'get', - httpPath: '/web/styleguide', - }, - { - clientCallName: 'client.web.screenshot', - fullyQualifiedName: 'web.screenshot', - httpMethod: 'get', - httpPath: '/web/screenshot', - }, - { - clientCallName: 'client.web.search', - fullyQualifiedName: 'web.search', - httpMethod: 'post', - httpPath: '/web/search', - }, - { - clientCallName: 'client.web.webCrawlMd', - fullyQualifiedName: 'web.webCrawlMd', - httpMethod: 'post', - httpPath: '/web/crawl', - }, - { - clientCallName: 'client.web.webScrapeHTML', - fullyQualifiedName: 'web.webScrapeHTML', - httpMethod: 'get', - httpPath: '/web/scrape/html', - }, - { - clientCallName: 'client.web.webScrapeImages', - fullyQualifiedName: 'web.webScrapeImages', - httpMethod: 'get', - httpPath: '/web/scrape/images', - }, - { - clientCallName: 'client.web.webScrapeMd', - fullyQualifiedName: 'web.webScrapeMd', - httpMethod: 'get', - httpPath: '/web/scrape/markdown', - }, - { - clientCallName: 'client.web.webScrapeSitemap', - fullyQualifiedName: 'web.webScrapeSitemap', - httpMethod: 'get', - httpPath: '/web/scrape/sitemap', - }, - { - clientCallName: 'client.ai.extractProduct', - fullyQualifiedName: 'ai.extractProduct', - httpMethod: 'post', - httpPath: '/brand/ai/product', - }, - { - clientCallName: 'client.ai.extractProducts', - fullyQualifiedName: 'ai.extractProducts', - httpMethod: 'post', - httpPath: '/brand/ai/products', - }, - { - clientCallName: 'client.brand.retrieve', - fullyQualifiedName: 'brand.retrieve', - httpMethod: 'post', - httpPath: '/brand/retrieve', - }, - { - clientCallName: 'client.brand.retrieveSimplified', - fullyQualifiedName: 'brand.retrieveSimplified', - httpMethod: 'get', - httpPath: '/brand/retrieve-simplified', - }, - { - clientCallName: 'client.brand.search', - fullyQualifiedName: 'brand.search', - httpMethod: 'get', - httpPath: '/brand/search', - }, - { - clientCallName: 'client.industry.retrieveNaics', - fullyQualifiedName: 'industry.retrieveNaics', - httpMethod: 'get', - httpPath: '/web/naics', - }, - { - clientCallName: 'client.industry.retrieveSic', - fullyQualifiedName: 'industry.retrieveSic', - httpMethod: 'get', - httpPath: '/web/sic', - }, - { - clientCallName: 'client.utility.prefetch', - fullyQualifiedName: 'utility.prefetch', - httpMethod: 'post', - httpPath: '/utility/prefetch', - }, - { - clientCallName: 'client.monitors.create', - fullyQualifiedName: 'monitors.create', - httpMethod: 'post', - httpPath: '/monitors', - }, - { - clientCallName: 'client.monitors.retrieve', - fullyQualifiedName: 'monitors.retrieve', - httpMethod: 'get', - httpPath: '/monitors/{monitor_id}', - }, - { - clientCallName: 'client.monitors.update', - fullyQualifiedName: 'monitors.update', - httpMethod: 'patch', - httpPath: '/monitors/{monitor_id}', - }, - { - clientCallName: 'client.monitors.list', - fullyQualifiedName: 'monitors.list', - httpMethod: 'get', - httpPath: '/monitors', - }, - { - clientCallName: 'client.monitors.delete', - fullyQualifiedName: 'monitors.delete', - httpMethod: 'delete', - httpPath: '/monitors/{monitor_id}', - }, - { - clientCallName: 'client.monitors.getCreditUsage', - fullyQualifiedName: 'monitors.getCreditUsage', - httpMethod: 'get', - httpPath: '/monitors/credit-usage', - }, - { - clientCallName: 'client.monitors.getLimits', - fullyQualifiedName: 'monitors.getLimits', - httpMethod: 'get', - httpPath: '/monitors/limits', - }, - { - clientCallName: 'client.monitors.listAccountChanges', - fullyQualifiedName: 'monitors.listAccountChanges', - httpMethod: 'get', - httpPath: '/monitors/changes', - }, - { - clientCallName: 'client.monitors.listAccountRuns', - fullyQualifiedName: 'monitors.listAccountRuns', - httpMethod: 'get', - httpPath: '/monitors/runs', - }, - { - clientCallName: 'client.monitors.listChanges', - fullyQualifiedName: 'monitors.listChanges', - httpMethod: 'get', - httpPath: '/monitors/{monitor_id}/changes', - }, - { - clientCallName: 'client.monitors.listRuns', - fullyQualifiedName: 'monitors.listRuns', - httpMethod: 'get', - httpPath: '/monitors/{monitor_id}/runs', - }, - { - clientCallName: 'client.monitors.retrieveChange', - fullyQualifiedName: 'monitors.retrieveChange', - httpMethod: 'get', - httpPath: '/monitors/changes/{change_id}', - }, - { - clientCallName: 'client.monitors.run', - fullyQualifiedName: 'monitors.run', - httpMethod: 'post', - httpPath: '/monitors/{monitor_id}/run', - }, - { - clientCallName: 'client.batch.retrieve', - fullyQualifiedName: 'batch.retrieve', - httpMethod: 'get', - httpPath: '/batch/{batch_id}', - }, - { - clientCallName: 'client.batch.list', - fullyQualifiedName: 'batch.list', - httpMethod: 'get', - httpPath: '/batch/list', - }, - { - clientCallName: 'client.batch.delete', - fullyQualifiedName: 'batch.delete', - httpMethod: 'delete', - httpPath: '/batch/{batch_id}', - }, - { - clientCallName: 'client.batch.cancel', - fullyQualifiedName: 'batch.cancel', - httpMethod: 'post', - httpPath: '/batch/{batch_id}/cancel', - }, - { - clientCallName: 'client.batch.getResults', - fullyQualifiedName: 'batch.getResults', - httpMethod: 'get', - httpPath: '/batch/{batch_id}/results', - }, - { - clientCallName: 'client.batch.submit', - fullyQualifiedName: 'batch.submit', - httpMethod: 'post', - httpPath: '/batch/submit', - }, - { - clientCallName: 'client.people.enrich', - fullyQualifiedName: 'people.enrich', - httpMethod: 'post', - httpPath: '/people/enrich', - }, - { - clientCallName: 'client.news.search', - fullyQualifiedName: 'news.search', - httpMethod: 'post', - httpPath: '/news/search', - }, -]; - -function allowedMethodsForCodeTool(options: McpOptions | undefined): SdkMethod[] | undefined { - if (!options) { - return undefined; - } - - let allowedMethods: SdkMethod[]; - - if (options.codeAllowHttpGets || options.codeAllowedMethods) { - // Start with nothing allowed and then add into it from options - let allowedMethodsSet = new Set(); - - if (options.codeAllowHttpGets) { - // Add all methods that map to an HTTP GET - sdkMethods - .filter((method) => method.httpMethod === 'get') - .forEach((method) => allowedMethodsSet.add(method)); - } - - if (options.codeAllowedMethods) { - // Add all methods that match any of the allowed regexps - const allowedRegexps = options.codeAllowedMethods.map((pattern) => { - try { - return new RegExp(pattern); - } catch (e) { - throw new Error( - `Invalid regex pattern for allowed method: "${pattern}": ${e instanceof Error ? e.message : e}`, - ); - } - }); - - sdkMethods - .filter((method) => allowedRegexps.some((regexp) => regexp.test(method.fullyQualifiedName))) - .forEach((method) => allowedMethodsSet.add(method)); - } - - allowedMethods = Array.from(allowedMethodsSet); - } else { - // Start with everything allowed - allowedMethods = [...sdkMethods]; - } - - if (options.codeBlockedMethods) { - // Filter down based on blocked regexps - const blockedRegexps = options.codeBlockedMethods.map((pattern) => { - try { - return new RegExp(pattern); - } catch (e) { - throw new Error( - `Invalid regex pattern for blocked method: "${pattern}": ${e instanceof Error ? e.message : e}`, - ); - } - }); - - allowedMethods = allowedMethods.filter( - (method) => !blockedRegexps.some((regexp) => regexp.test(method.fullyQualifiedName)), - ); - } - - return allowedMethods; -} - -export function blockedMethodsForCodeTool(options: McpOptions | undefined): SdkMethod[] | undefined { - const allowedMethods = allowedMethodsForCodeTool(options); - if (!allowedMethods) { - return undefined; - } - - const allowedSet = new Set(allowedMethods.map((method) => method.fullyQualifiedName)); - - // Return any methods that are not explicitly allowed - return sdkMethods.filter((method) => !allowedSet.has(method.fullyQualifiedName)); -} diff --git a/packages/mcp-server/src/options.ts b/packages/mcp-server/src/options.ts deleted file mode 100644 index ff817c70..00000000 --- a/packages/mcp-server/src/options.ts +++ /dev/null @@ -1,185 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import qs from 'qs'; -import yargs from 'yargs'; -import { hideBin } from 'yargs/helpers'; -import z from 'zod'; -import { readEnv } from './util'; - -export type CLIOptions = McpOptions & { - debug: boolean; - logFormat: 'json' | 'pretty'; - transport: 'stdio' | 'http'; - port: number | undefined; - socket: string | undefined; -}; - -export type McpOptions = { - includeCodeTool?: boolean | undefined; - includeDocsTools?: boolean | undefined; - stainlessApiKey?: string | undefined; - docsSearchMode?: 'local' | undefined; - docsDir?: string | undefined; - codeAllowHttpGets?: boolean | undefined; - codeAllowedMethods?: string[] | undefined; - codeBlockedMethods?: string[] | undefined; - codeExecutionMode: McpCodeExecutionMode; - customInstructionsPath?: string | undefined; -}; - -export type McpCodeExecutionMode = 'local'; - -export function parseCLIOptions(): CLIOptions { - const opts = yargs(hideBin(process.argv)) - .option('code-allow-http-gets', { - type: 'boolean', - description: - 'Allow all code tool methods that map to HTTP GET operations. If all code-allow-* flags are unset, then everything is allowed.', - }) - .option('code-allowed-methods', { - type: 'string', - array: true, - description: - 'Methods to explicitly allow for code tool. Evaluated as regular expressions against method fully qualified names. If all code-allow-* flags are unset, then everything is allowed.', - }) - .option('code-blocked-methods', { - type: 'string', - array: true, - description: - 'Methods to explicitly block for code tool. Evaluated as regular expressions against method fully qualified names. If all code-allow-* flags are unset, then everything is allowed.', - }) - .option('code-execution-mode', { - type: 'string', - choices: ['local'], - default: 'local', - description: - 'The server was generated without access to the Stainless API, so code execution can only run locally on the MCP server machine.', - }) - .option('custom-instructions-path', { - type: 'string', - description: 'Path to custom instructions for the MCP server', - }) - .option('debug', { type: 'boolean', description: 'Enable debug logging' }) - .option('docs-dir', { - type: 'string', - description: - 'Path to a directory of local documentation files (markdown/JSON) to include in local docs search.', - }) - .option('docs-search-mode', { - type: 'string', - choices: ['local'], - default: 'local', - description: - "Documentation search will use an in-memory search index built from embedded SDK method data and optional local docs files; the 'stainless-api' option is unavailable.", - }) - .option('log-format', { - type: 'string', - choices: ['json', 'pretty'], - description: 'Format for log output; defaults to json unless tty is detected', - }) - .option('no-tools', { - type: 'string', - array: true, - choices: ['code', 'docs'], - description: 'Tools to explicitly disable', - }) - .option('port', { - type: 'number', - default: 3000, - description: 'Port to serve on if using http transport', - }) - .option('socket', { type: 'string', description: 'Unix socket to serve on if using http transport' }) - .option('stainless-api-key', { - type: 'string', - default: readEnv('STAINLESS_API_KEY'), - description: - 'API key for Stainless. Used to authenticate requests to Stainless-hosted tools endpoints.', - }) - .option('tools', { - type: 'string', - array: true, - choices: ['code', 'docs'], - description: 'Tools to explicitly enable', - }) - .option('transport', { - type: 'string', - choices: ['stdio', 'http'], - default: 'stdio', - description: 'What transport to use; stdio for local servers or http for remote servers', - }) - .env('MCP_SERVER') - .version(true) - .help(); - - const argv = opts.parseSync(); - - const shouldIncludeToolType = (toolType: 'code' | 'docs') => - argv.noTools?.includes(toolType) ? false - : argv.tools?.includes(toolType) ? true - : undefined; - - const includeCodeTool = shouldIncludeToolType('code'); - const includeDocsTools = shouldIncludeToolType('docs'); - - const transport = argv.transport as 'stdio' | 'http'; - const logFormat = - argv.logFormat ? (argv.logFormat as 'json' | 'pretty') - : process.stderr.isTTY ? 'pretty' - : 'json'; - - return { - ...(includeCodeTool !== undefined && { includeCodeTool }), - ...(includeDocsTools !== undefined && { includeDocsTools }), - debug: !!argv.debug, - stainlessApiKey: argv.stainlessApiKey, - docsSearchMode: argv.docsSearchMode as 'local' | undefined, - docsDir: argv.docsDir, - codeAllowHttpGets: argv.codeAllowHttpGets, - codeAllowedMethods: argv.codeAllowedMethods, - codeBlockedMethods: argv.codeBlockedMethods, - codeExecutionMode: argv.codeExecutionMode as McpCodeExecutionMode, - customInstructionsPath: argv.customInstructionsPath, - transport, - logFormat, - port: argv.port, - socket: argv.socket, - }; -} - -const coerceArray = (zodType: T) => - z.preprocess( - (val) => - Array.isArray(val) ? val - : val ? [val] - : val, - z.array(zodType).optional(), - ); - -const QueryOptions = z.object({ - tools: coerceArray(z.enum(['code', 'docs'])).describe('Specify which MCP tools to use'), - no_tools: coerceArray(z.enum(['code', 'docs'])).describe('Specify which MCP tools to not use.'), - tool: coerceArray(z.string()).describe('Include tools matching the specified names'), -}); - -export function parseQueryOptions(defaultOptions: McpOptions, query: unknown): McpOptions { - const queryObject = typeof query === 'string' ? qs.parse(query) : query; - const queryOptions = QueryOptions.parse(queryObject); - - let codeTool: boolean | undefined = - queryOptions.no_tools && queryOptions.no_tools?.includes('code') ? false - : queryOptions.tools?.includes('code') ? true - : defaultOptions.includeCodeTool; - - let docsTools: boolean | undefined = - queryOptions.no_tools && queryOptions.no_tools?.includes('docs') ? false - : queryOptions.tools?.includes('docs') ? true - : defaultOptions.includeDocsTools; - - return { - ...(codeTool !== undefined && { includeCodeTool: codeTool }), - ...(docsTools !== undefined && { includeDocsTools: docsTools }), - codeExecutionMode: defaultOptions.codeExecutionMode, - docsSearchMode: defaultOptions.docsSearchMode, - docsDir: defaultOptions.docsDir, - }; -} diff --git a/packages/mcp-server/src/server.ts b/packages/mcp-server/src/server.ts deleted file mode 100644 index 31404104..00000000 --- a/packages/mcp-server/src/server.ts +++ /dev/null @@ -1,208 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { Server } from '@modelcontextprotocol/sdk/server/index.js'; -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { - CallToolRequestSchema, - ListToolsRequestSchema, - SetLevelRequestSchema, -} from '@modelcontextprotocol/sdk/types.js'; -import { ClientOptions } from 'context.dev'; -import ContextDev from 'context.dev'; -import { codeTool } from './code-tool'; -import docsSearchTool from './docs-search-tool'; -import { setLocalSearch } from './docs-search-tool'; -import { LocalDocsSearch } from './local-docs-search'; -import { getInstructions } from './instructions'; -import { McpOptions } from './options'; -import { blockedMethodsForCodeTool } from './methods'; -import { HandlerFunction, McpRequestContext, ToolCallResult, McpTool } from './types'; - -export const newMcpServer = async ({ - stainlessApiKey, - customInstructionsPath, -}: { - stainlessApiKey?: string | undefined; - customInstructionsPath?: string | undefined; -}) => - new McpServer( - { - name: 'context_dev_api', - version: '2.14.0', - }, - { - instructions: await getInstructions({ stainlessApiKey, customInstructionsPath }), - capabilities: { tools: {}, logging: {} }, - }, - ); - -/** - * Initializes the provided MCP Server with the given tools and handlers. - * If not provided, the default client, tools and handlers will be used. - */ -export async function initMcpServer(params: { - server: Server | McpServer; - clientOptions?: ClientOptions; - mcpOptions?: McpOptions; - stainlessApiKey?: string | undefined; - upstreamClientEnvs?: Record | undefined; - mcpSessionId?: string | undefined; - mcpClientInfo?: { name: string; version: string } | undefined; -}) { - const server = params.server instanceof McpServer ? params.server.server : params.server; - - const logAtLevel = - (level: 'debug' | 'info' | 'warning' | 'error') => - (message: string, ...rest: unknown[]) => { - void server.sendLoggingMessage({ - level, - data: { message, rest }, - }); - }; - const logger = { - debug: logAtLevel('debug'), - info: logAtLevel('info'), - warn: logAtLevel('warning'), - error: logAtLevel('error'), - }; - - if (params.mcpOptions?.docsSearchMode === 'local') { - const docsDir = params.mcpOptions?.docsDir; - const localSearch = await LocalDocsSearch.create(docsDir ? { docsDir } : undefined); - setLocalSearch(localSearch); - } - - let _client: ContextDev | undefined; - let _clientError: Error | undefined; - let _logLevel: 'debug' | 'info' | 'warn' | 'error' | 'off' | undefined; - - const getClient = (): ContextDev => { - if (_clientError) throw _clientError; - if (!_client) { - try { - _client = new ContextDev({ - logger, - ...params.clientOptions, - defaultHeaders: { - ...params.clientOptions?.defaultHeaders, - 'X-Stainless-MCP': 'true', - }, - }); - if (_logLevel) { - _client = _client.withOptions({ logLevel: _logLevel }); - } - } catch (e) { - _clientError = e instanceof Error ? e : new Error(String(e)); - throw _clientError; - } - } - return _client; - }; - - const providedTools = selectTools(params.mcpOptions); - const toolMap = Object.fromEntries(providedTools.map((mcpTool) => [mcpTool.tool.name, mcpTool])); - - server.setRequestHandler(ListToolsRequestSchema, async () => { - return { - tools: providedTools.map((mcpTool) => mcpTool.tool), - }; - }); - - server.setRequestHandler(CallToolRequestSchema, async (request) => { - const { name, arguments: args } = request.params; - const mcpTool = toolMap[name]; - if (!mcpTool) { - throw new Error(`Unknown tool: ${name}`); - } - - let client: ContextDev; - try { - client = getClient(); - } catch (error) { - return { - content: [ - { - type: 'text' as const, - text: `Failed to initialize client: ${error instanceof Error ? error.message : String(error)}`, - }, - ], - isError: true, - }; - } - - return executeHandler({ - handler: mcpTool.handler, - reqContext: { - client, - stainlessApiKey: params.stainlessApiKey ?? params.mcpOptions?.stainlessApiKey, - upstreamClientEnvs: params.upstreamClientEnvs, - mcpSessionId: params.mcpSessionId, - mcpClientInfo: params.mcpClientInfo, - }, - args, - }); - }); - - server.setRequestHandler(SetLevelRequestSchema, async (request) => { - const { level } = request.params; - let logLevel: 'debug' | 'info' | 'warn' | 'error' | 'off'; - switch (level) { - case 'debug': - logLevel = 'debug'; - break; - case 'info': - logLevel = 'info'; - break; - case 'notice': - case 'warning': - logLevel = 'warn'; - break; - case 'error': - logLevel = 'error'; - break; - default: - logLevel = 'off'; - break; - } - _logLevel = logLevel; - if (_client) { - _client = _client.withOptions({ logLevel }); - } - return {}; - }); -} - -/** - * Selects the tools to include in the MCP Server based on the provided options. - */ -export function selectTools(options?: McpOptions): McpTool[] { - const includedTools = []; - - if (options?.includeCodeTool ?? true) { - includedTools.push( - codeTool({ - blockedMethods: blockedMethodsForCodeTool(options), - codeExecutionMode: options?.codeExecutionMode ?? 'local', - }), - ); - } - if (options?.includeDocsTools ?? true) { - includedTools.push(docsSearchTool); - } - return includedTools; -} - -/** - * Runs the provided handler with the given client and arguments. - */ -export async function executeHandler({ - handler, - reqContext, - args, -}: { - handler: HandlerFunction; - reqContext: McpRequestContext; - args: Record | undefined; -}): Promise { - return await handler({ reqContext, args: args || {} }); -} diff --git a/packages/mcp-server/src/stdio.ts b/packages/mcp-server/src/stdio.ts deleted file mode 100644 index b04a5441..00000000 --- a/packages/mcp-server/src/stdio.ts +++ /dev/null @@ -1,17 +0,0 @@ -import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; -import { McpOptions } from './options'; -import { initMcpServer, newMcpServer } from './server'; -import { getLogger } from './logger'; - -export const launchStdioServer = async (mcpOptions: McpOptions) => { - const server = await newMcpServer({ - stainlessApiKey: mcpOptions.stainlessApiKey, - customInstructionsPath: mcpOptions.customInstructionsPath, - }); - - await initMcpServer({ server, mcpOptions, stainlessApiKey: mcpOptions.stainlessApiKey }); - - const transport = new StdioServerTransport(); - await server.connect(transport); - getLogger().info('MCP Server running on stdio'); -}; diff --git a/packages/mcp-server/src/types.ts b/packages/mcp-server/src/types.ts deleted file mode 100644 index dd1e4dee..00000000 --- a/packages/mcp-server/src/types.ts +++ /dev/null @@ -1,126 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import ContextDev from 'context.dev'; -import { Tool } from '@modelcontextprotocol/sdk/types.js'; - -type TextContentBlock = { - type: 'text'; - text: string; -}; - -type ImageContentBlock = { - type: 'image'; - data: string; - mimeType: string; -}; - -type AudioContentBlock = { - type: 'audio'; - data: string; - mimeType: string; -}; - -type ResourceContentBlock = { - type: 'resource'; - resource: - | { - uri: string; - mimeType: string; - text: string; - } - | { - uri: string; - mimeType: string; - blob: string; - }; -}; - -export type ContentBlock = TextContentBlock | ImageContentBlock | AudioContentBlock | ResourceContentBlock; - -export type ToolCallResult = { - content: ContentBlock[]; - isError?: boolean; -}; - -export type McpRequestContext = { - client: ContextDev; - stainlessApiKey?: string | undefined; - upstreamClientEnvs?: Record | undefined; - mcpSessionId?: string | undefined; - mcpClientInfo?: { name: string; version: string } | undefined; -}; - -export type HandlerFunction = ({ - reqContext, - args, -}: { - reqContext: McpRequestContext; - args: Record | undefined; -}) => Promise; - -export function asTextContentResult(result: unknown): ToolCallResult { - return { - content: [ - { - type: 'text', - text: JSON.stringify(result, null, 2), - }, - ], - }; -} - -export async function asBinaryContentResult(response: Response): Promise { - const blob = await response.blob(); - const mimeType = blob.type; - const data = Buffer.from(await blob.arrayBuffer()).toString('base64'); - if (mimeType.startsWith('image/')) { - return { - content: [{ type: 'image', mimeType, data }], - }; - } else if (mimeType.startsWith('audio/')) { - return { - content: [{ type: 'audio', mimeType, data }], - }; - } else { - return { - content: [ - { - type: 'resource', - resource: { - // We must give a URI, even though this isn't actually an MCP resource. - uri: 'resource://tool-response', - mimeType, - blob: data, - }, - }, - ], - }; - } -} - -export function asErrorResult(message: string): ToolCallResult { - return { - content: [ - { - type: 'text', - text: message, - }, - ], - isError: true, - }; -} - -export type Metadata = { - resource: string; - operation: 'read' | 'write'; - tags: string[]; - httpMethod?: string; - httpPath?: string; - operationId?: string; -}; - -export type McpTool = { - metadata: Metadata; - tool: Tool; - handler: HandlerFunction; -}; diff --git a/packages/mcp-server/src/util.ts b/packages/mcp-server/src/util.ts deleted file mode 100644 index 069a2b47..00000000 --- a/packages/mcp-server/src/util.ts +++ /dev/null @@ -1,25 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -export const readEnv = (env: string): string | undefined => { - if (typeof (globalThis as any).process !== 'undefined') { - return (globalThis as any).process.env?.[env]?.trim() || undefined; - } else if (typeof (globalThis as any).Deno !== 'undefined') { - return (globalThis as any).Deno.env?.get?.(env)?.trim() || undefined; - } - return; -}; - -export const readEnvOrError = (env: string): string => { - let envValue = readEnv(env); - if (envValue === undefined) { - throw new Error(`Environment variable ${env} is not set`); - } - return envValue; -}; - -export const requireValue = (value: T | undefined, description: string): T => { - if (value === undefined) { - throw new Error(`Missing required value: ${description}`); - } - return value; -}; diff --git a/packages/mcp-server/tests/options.test.ts b/packages/mcp-server/tests/options.test.ts deleted file mode 100644 index 17306295..00000000 --- a/packages/mcp-server/tests/options.test.ts +++ /dev/null @@ -1,32 +0,0 @@ -import { parseCLIOptions } from '../src/options'; - -// Mock process.argv -const mockArgv = (args: string[]) => { - const originalArgv = process.argv; - process.argv = ['node', 'test.js', ...args]; - return () => { - process.argv = originalArgv; - }; -}; - -describe('parseCLIOptions', () => { - it('default parsing should be stdio', () => { - const cleanup = mockArgv([]); - - const result = parseCLIOptions(); - - expect(result.transport).toBe('stdio'); - - cleanup(); - }); - - it('using http transport with a port', () => { - const cleanup = mockArgv(['--transport=http', '--port=2222']); - - const result = parseCLIOptions(); - - expect(result.transport).toBe('http'); - expect(result.port).toBe(2222); - cleanup(); - }); -}); diff --git a/packages/mcp-server/tsc-multi.json b/packages/mcp-server/tsc-multi.json deleted file mode 100644 index 4facad5a..00000000 --- a/packages/mcp-server/tsc-multi.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "targets": [ - { "extname": ".js", "module": "commonjs" }, - { "extname": ".mjs", "module": "esnext" } - ], - "projects": ["tsconfig.build.json"] -} diff --git a/packages/mcp-server/tsconfig.build.json b/packages/mcp-server/tsconfig.build.json deleted file mode 100644 index 28285988..00000000 --- a/packages/mcp-server/tsconfig.build.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "extends": "./tsconfig.json", - "include": ["dist/src"], - "exclude": [], - "compilerOptions": { - "rootDir": "./dist/src", - "paths": { - "context.dev-mcp/*": ["./dist/src/*"], - "context.dev-mcp": ["./dist/src/index.ts"] - }, - "noEmit": false, - "declaration": true, - "declarationMap": true, - "outDir": "dist", - "pretty": true, - "sourceMap": true - } -} diff --git a/packages/mcp-server/tsconfig.dist-src.json b/packages/mcp-server/tsconfig.dist-src.json deleted file mode 100644 index e9f2d70b..00000000 --- a/packages/mcp-server/tsconfig.dist-src.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - // this config is included in the published src directory to prevent TS errors - // from appearing when users go to source, and VSCode opens the source .ts file - // via declaration maps - "include": ["index.ts"], - "compilerOptions": { - "target": "es2015", - "lib": ["DOM"], - "moduleResolution": "node" - } -} diff --git a/packages/mcp-server/tsconfig.json b/packages/mcp-server/tsconfig.json deleted file mode 100644 index dbbee1a6..00000000 --- a/packages/mcp-server/tsconfig.json +++ /dev/null @@ -1,36 +0,0 @@ -{ - "include": ["src", "tests", "examples"], - "exclude": [], - "compilerOptions": { - "target": "es2022", - "lib": ["es2022"], - "module": "commonjs", - "moduleResolution": "node", - "esModuleInterop": true, - "paths": { - "context.dev-mcp/*": ["./src/*"], - "context.dev-mcp": ["./src/index.ts"] - }, - "noEmit": true, - - "resolveJsonModule": true, - - "forceConsistentCasingInFileNames": true, - - "strict": true, - "noImplicitAny": true, - "strictNullChecks": true, - "strictFunctionTypes": true, - "strictBindCallApply": true, - "strictPropertyInitialization": true, - "noImplicitThis": true, - "noImplicitReturns": true, - "alwaysStrict": true, - "exactOptionalPropertyTypes": true, - "noUncheckedIndexedAccess": true, - "noImplicitOverride": true, - "noPropertyAccessFromIndexSignature": true, - - "skipLibCheck": true - } -} diff --git a/packages/mcp-server/yarn.lock b/packages/mcp-server/yarn.lock deleted file mode 100644 index c6b17b02..00000000 --- a/packages/mcp-server/yarn.lock +++ /dev/null @@ -1,4169 +0,0 @@ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. -# yarn lockfile v1 - - -"@anthropic-ai/mcpb@^2.1.2": - version "2.1.2" - resolved "https://registry.yarnpkg.com/@anthropic-ai/mcpb/-/mcpb-2.1.2.tgz#cf02801929734b8810961f22e2eb72758c27d527" - integrity sha512-goRbBC8ySo7SWb7tRzr+tL6FxDc4JPTRCdgfD2omba7freofvjq5rom1lBnYHZHo6Mizs1jAHJeN53aZbDoy8A== - dependencies: - "@inquirer/prompts" "^6.0.1" - commander "^13.1.0" - fflate "^0.8.2" - galactus "^1.0.0" - ignore "^7.0.5" - node-forge "^1.3.2" - pretty-bytes "^5.6.0" - zod "^3.25.67" - zod-to-json-schema "^3.24.6" - -"@babel/code-frame@^7.0.0", "@babel/code-frame@^7.12.13", "@babel/code-frame@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/code-frame/-/code-frame-7.28.6.tgz#72499312ec58b1e2245ba4a4f550c132be4982f7" - integrity sha512-JYgintcMjRiCvS8mMECzaEn+m3PfoQiyqukOMCCVQtoJGYJw8j/8LBJEiqkHLkfwCcs74E3pbAUFNg7d9VNJ+Q== - dependencies: - "@babel/helper-validator-identifier" "^7.28.5" - js-tokens "^4.0.0" - picocolors "^1.1.1" - -"@babel/compat-data@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/compat-data/-/compat-data-7.28.6.tgz#103f466803fa0f059e82ccac271475470570d74c" - integrity sha512-2lfu57JtzctfIrcGMz992hyLlByuzgIk58+hhGCxjKZ3rWI82NnVLjXcaTqkI2NvlcvOskZaiZ5kjUALo3Lpxg== - -"@babel/core@^7.11.6", "@babel/core@^7.12.3", "@babel/core@^7.23.9": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/core/-/core-7.28.6.tgz#531bf883a1126e53501ba46eb3bb414047af507f" - integrity sha512-H3mcG6ZDLTlYfaSNi0iOKkigqMFvkTKlGUYlD8GW7nNOYRrevuA46iTypPyv+06V3fEmvvazfntkBU34L0azAw== - dependencies: - "@babel/code-frame" "^7.28.6" - "@babel/generator" "^7.28.6" - "@babel/helper-compilation-targets" "^7.28.6" - "@babel/helper-module-transforms" "^7.28.6" - "@babel/helpers" "^7.28.6" - "@babel/parser" "^7.28.6" - "@babel/template" "^7.28.6" - "@babel/traverse" "^7.28.6" - "@babel/types" "^7.28.6" - "@jridgewell/remapping" "^2.3.5" - convert-source-map "^2.0.0" - debug "^4.1.0" - gensync "^1.0.0-beta.2" - json5 "^2.2.3" - semver "^6.3.1" - -"@babel/generator@^7.28.6", "@babel/generator@^7.7.2": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/generator/-/generator-7.28.6.tgz#48dcc65d98fcc8626a48f72b62e263d25fc3c3f1" - integrity sha512-lOoVRwADj8hjf7al89tvQ2a1lf53Z+7tiXMgpZJL3maQPDxh0DgLMN62B2MKUOFcoodBHLMbDM6WAbKgNy5Suw== - dependencies: - "@babel/parser" "^7.28.6" - "@babel/types" "^7.28.6" - "@jridgewell/gen-mapping" "^0.3.12" - "@jridgewell/trace-mapping" "^0.3.28" - jsesc "^3.0.2" - -"@babel/helper-compilation-targets@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/helper-compilation-targets/-/helper-compilation-targets-7.28.6.tgz#32c4a3f41f12ed1532179b108a4d746e105c2b25" - integrity sha512-JYtls3hqi15fcx5GaSNL7SCTJ2MNmjrkHXg4FSpOA/grxK8KwyZ5bubHsCq8FXCkua6xhuaaBit+3b7+VZRfcA== - dependencies: - "@babel/compat-data" "^7.28.6" - "@babel/helper-validator-option" "^7.27.1" - browserslist "^4.24.0" - lru-cache "^5.1.1" - semver "^6.3.1" - -"@babel/helper-globals@^7.28.0": - version "7.28.0" - resolved "https://registry.yarnpkg.com/@babel/helper-globals/-/helper-globals-7.28.0.tgz#b9430df2aa4e17bc28665eadeae8aa1d985e6674" - integrity sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw== - -"@babel/helper-module-imports@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/helper-module-imports/-/helper-module-imports-7.28.6.tgz#60632cbd6ffb70b22823187201116762a03e2d5c" - integrity sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw== - dependencies: - "@babel/traverse" "^7.28.6" - "@babel/types" "^7.28.6" - -"@babel/helper-module-transforms@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/helper-module-transforms/-/helper-module-transforms-7.28.6.tgz#9312d9d9e56edc35aeb6e95c25d4106b50b9eb1e" - integrity sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA== - dependencies: - "@babel/helper-module-imports" "^7.28.6" - "@babel/helper-validator-identifier" "^7.28.5" - "@babel/traverse" "^7.28.6" - -"@babel/helper-plugin-utils@^7.0.0", "@babel/helper-plugin-utils@^7.10.4", "@babel/helper-plugin-utils@^7.12.13", "@babel/helper-plugin-utils@^7.14.5", "@babel/helper-plugin-utils@^7.28.6", "@babel/helper-plugin-utils@^7.8.0": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/helper-plugin-utils/-/helper-plugin-utils-7.28.6.tgz#6f13ea251b68c8532e985fd532f28741a8af9ac8" - integrity sha512-S9gzZ/bz83GRysI7gAD4wPT/AI3uCnY+9xn+Mx/KPs2JwHJIz1W8PZkg2cqyt3RNOBM8ejcXhV6y8Og7ly/Dug== - -"@babel/helper-string-parser@^7.27.1": - version "7.27.1" - resolved "https://registry.yarnpkg.com/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz#54da796097ab19ce67ed9f88b47bb2ec49367687" - integrity sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA== - -"@babel/helper-validator-identifier@^7.28.5": - version "7.28.5" - resolved "https://registry.yarnpkg.com/@babel/helper-validator-identifier/-/helper-validator-identifier-7.28.5.tgz#010b6938fab7cb7df74aa2bbc06aa503b8fe5fb4" - integrity sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q== - -"@babel/helper-validator-option@^7.27.1": - version "7.27.1" - resolved "https://registry.yarnpkg.com/@babel/helper-validator-option/-/helper-validator-option-7.27.1.tgz#fa52f5b1e7db1ab049445b421c4471303897702f" - integrity sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg== - -"@babel/helpers@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/helpers/-/helpers-7.28.6.tgz#fca903a313ae675617936e8998b814c415cbf5d7" - integrity sha512-xOBvwq86HHdB7WUDTfKfT/Vuxh7gElQ+Sfti2Cy6yIWNW05P8iUslOVcZ4/sKbE+/jQaukQAdz/gf3724kYdqw== - dependencies: - "@babel/template" "^7.28.6" - "@babel/types" "^7.28.6" - -"@babel/parser@^7.1.0", "@babel/parser@^7.14.7", "@babel/parser@^7.20.7", "@babel/parser@^7.23.9", "@babel/parser@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/parser/-/parser-7.28.6.tgz#f01a8885b7fa1e56dd8a155130226cd698ef13fd" - integrity sha512-TeR9zWR18BvbfPmGbLampPMW+uW1NZnJlRuuHso8i87QZNq2JRF9i6RgxRqtEq+wQGsS19NNTWr2duhnE49mfQ== - dependencies: - "@babel/types" "^7.28.6" - -"@babel/plugin-syntax-async-generators@^7.8.4": - version "7.8.4" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-async-generators/-/plugin-syntax-async-generators-7.8.4.tgz#a983fb1aeb2ec3f6ed042a210f640e90e786fe0d" - integrity sha512-tycmZxkGfZaxhMRbXlPXuVFpdWlXpir2W4AMhSJgRKzk/eDlIXOhb2LHWoLpDF7TEHylV5zNhykX6KAgHJmTNw== - dependencies: - "@babel/helper-plugin-utils" "^7.8.0" - -"@babel/plugin-syntax-bigint@^7.8.3": - version "7.8.3" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-bigint/-/plugin-syntax-bigint-7.8.3.tgz#4c9a6f669f5d0cdf1b90a1671e9a146be5300cea" - integrity sha512-wnTnFlG+YxQm3vDxpGE57Pj0srRU4sHE/mDkt1qv2YJJSeUAec2ma4WLUnUPeKjyrfntVwe/N6dCXpU+zL3Npg== - dependencies: - "@babel/helper-plugin-utils" "^7.8.0" - -"@babel/plugin-syntax-class-properties@^7.12.13": - version "7.12.13" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-class-properties/-/plugin-syntax-class-properties-7.12.13.tgz#b5c987274c4a3a82b89714796931a6b53544ae10" - integrity sha512-fm4idjKla0YahUNgFNLCB0qySdsoPiZP3iQE3rky0mBUtMZ23yDJ9SJdg6dXTSDnulOVqiF3Hgr9nbXvXTQZYA== - dependencies: - "@babel/helper-plugin-utils" "^7.12.13" - -"@babel/plugin-syntax-class-static-block@^7.14.5": - version "7.14.5" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-class-static-block/-/plugin-syntax-class-static-block-7.14.5.tgz#195df89b146b4b78b3bf897fd7a257c84659d406" - integrity sha512-b+YyPmr6ldyNnM6sqYeMWE+bgJcJpO6yS4QD7ymxgH34GBPNDM/THBh8iunyvKIZztiwLH4CJZ0RxTk9emgpjw== - dependencies: - "@babel/helper-plugin-utils" "^7.14.5" - -"@babel/plugin-syntax-import-attributes@^7.24.7": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-import-attributes/-/plugin-syntax-import-attributes-7.28.6.tgz#b71d5914665f60124e133696f17cd7669062c503" - integrity sha512-jiLC0ma9XkQT3TKJ9uYvlakm66Pamywo+qwL+oL8HJOvc6TWdZXVfhqJr8CCzbSGUAbDOzlGHJC1U+vRfLQDvw== - dependencies: - "@babel/helper-plugin-utils" "^7.28.6" - -"@babel/plugin-syntax-import-meta@^7.10.4": - version "7.10.4" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-import-meta/-/plugin-syntax-import-meta-7.10.4.tgz#ee601348c370fa334d2207be158777496521fd51" - integrity sha512-Yqfm+XDx0+Prh3VSeEQCPU81yC+JWZ2pDPFSS4ZdpfZhp4MkFMaDC1UqseovEKwSUpnIL7+vK+Clp7bfh0iD7g== - dependencies: - "@babel/helper-plugin-utils" "^7.10.4" - -"@babel/plugin-syntax-json-strings@^7.8.3": - version "7.8.3" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-json-strings/-/plugin-syntax-json-strings-7.8.3.tgz#01ca21b668cd8218c9e640cb6dd88c5412b2c96a" - integrity sha512-lY6kdGpWHvjoe2vk4WrAapEuBR69EMxZl+RoGRhrFGNYVK8mOPAW8VfbT/ZgrFbXlDNiiaxQnAtgVCZ6jv30EA== - dependencies: - "@babel/helper-plugin-utils" "^7.8.0" - -"@babel/plugin-syntax-jsx@^7.7.2": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-jsx/-/plugin-syntax-jsx-7.28.6.tgz#f8ca28bbd84883b5fea0e447c635b81ba73997ee" - integrity sha512-wgEmr06G6sIpqr8YDwA2dSRTE3bJ+V0IfpzfSY3Lfgd7YWOaAdlykvJi13ZKBt8cZHfgH1IXN+CL656W3uUa4w== - dependencies: - "@babel/helper-plugin-utils" "^7.28.6" - -"@babel/plugin-syntax-logical-assignment-operators@^7.10.4": - version "7.10.4" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-logical-assignment-operators/-/plugin-syntax-logical-assignment-operators-7.10.4.tgz#ca91ef46303530448b906652bac2e9fe9941f699" - integrity sha512-d8waShlpFDinQ5MtvGU9xDAOzKH47+FFoney2baFIoMr952hKOLp1HR7VszoZvOsV/4+RRszNY7D17ba0te0ig== - dependencies: - "@babel/helper-plugin-utils" "^7.10.4" - -"@babel/plugin-syntax-nullish-coalescing-operator@^7.8.3": - version "7.8.3" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-nullish-coalescing-operator/-/plugin-syntax-nullish-coalescing-operator-7.8.3.tgz#167ed70368886081f74b5c36c65a88c03b66d1a9" - integrity sha512-aSff4zPII1u2QD7y+F8oDsz19ew4IGEJg9SVW+bqwpwtfFleiQDMdzA/R+UlWDzfnHFCxxleFT0PMIrR36XLNQ== - dependencies: - "@babel/helper-plugin-utils" "^7.8.0" - -"@babel/plugin-syntax-numeric-separator@^7.10.4": - version "7.10.4" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-numeric-separator/-/plugin-syntax-numeric-separator-7.10.4.tgz#b9b070b3e33570cd9fd07ba7fa91c0dd37b9af97" - integrity sha512-9H6YdfkcK/uOnY/K7/aA2xpzaAgkQn37yzWUMRK7OaPOqOpGS1+n0H5hxT9AUw9EsSjPW8SVyMJwYRtWs3X3ug== - dependencies: - "@babel/helper-plugin-utils" "^7.10.4" - -"@babel/plugin-syntax-object-rest-spread@^7.8.3": - version "7.8.3" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-object-rest-spread/-/plugin-syntax-object-rest-spread-7.8.3.tgz#60e225edcbd98a640332a2e72dd3e66f1af55871" - integrity sha512-XoqMijGZb9y3y2XskN+P1wUGiVwWZ5JmoDRwx5+3GmEplNyVM2s2Dg8ILFQm8rWM48orGy5YpI5Bl8U1y7ydlA== - dependencies: - "@babel/helper-plugin-utils" "^7.8.0" - -"@babel/plugin-syntax-optional-catch-binding@^7.8.3": - version "7.8.3" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-optional-catch-binding/-/plugin-syntax-optional-catch-binding-7.8.3.tgz#6111a265bcfb020eb9efd0fdfd7d26402b9ed6c1" - integrity sha512-6VPD0Pc1lpTqw0aKoeRTMiB+kWhAoT24PA+ksWSBrFtl5SIRVpZlwN3NNPQjehA2E/91FV3RjLWoVTglWcSV3Q== - dependencies: - "@babel/helper-plugin-utils" "^7.8.0" - -"@babel/plugin-syntax-optional-chaining@^7.8.3": - version "7.8.3" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-optional-chaining/-/plugin-syntax-optional-chaining-7.8.3.tgz#4f69c2ab95167e0180cd5336613f8c5788f7d48a" - integrity sha512-KoK9ErH1MBlCPxV0VANkXW2/dw4vlbGDrFgz8bmUsBGYkFRcbRwMh6cIJubdPrkxRwuGdtCk0v/wPTKbQgBjkg== - dependencies: - "@babel/helper-plugin-utils" "^7.8.0" - -"@babel/plugin-syntax-private-property-in-object@^7.14.5": - version "7.14.5" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-private-property-in-object/-/plugin-syntax-private-property-in-object-7.14.5.tgz#0dc6671ec0ea22b6e94a1114f857970cd39de1ad" - integrity sha512-0wVnp9dxJ72ZUJDV27ZfbSj6iHLoytYZmh3rFcxNnvsJF3ktkzLDZPy/mA17HGsaQT3/DQsWYX1f1QGWkCoVUg== - dependencies: - "@babel/helper-plugin-utils" "^7.14.5" - -"@babel/plugin-syntax-top-level-await@^7.14.5": - version "7.14.5" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-top-level-await/-/plugin-syntax-top-level-await-7.14.5.tgz#c1cfdadc35a646240001f06138247b741c34d94c" - integrity sha512-hx++upLv5U1rgYfwe1xBQUhRmU41NEvpUvrp8jkrSCdvGSnM5/qdRMtylJ6PG5OFkBaHkbTAKTnd3/YyESRHFw== - dependencies: - "@babel/helper-plugin-utils" "^7.14.5" - -"@babel/plugin-syntax-typescript@^7.7.2": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-typescript/-/plugin-syntax-typescript-7.28.6.tgz#c7b2ddf1d0a811145b1de800d1abd146af92e3a2" - integrity sha512-+nDNmQye7nlnuuHDboPbGm00Vqg3oO8niRRL27/4LYHUsHYh0zJ1xWOz0uRwNFmM1Avzk8wZbc6rdiYhomzv/A== - dependencies: - "@babel/helper-plugin-utils" "^7.28.6" - -"@babel/template@^7.28.6", "@babel/template@^7.3.3": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/template/-/template-7.28.6.tgz#0e7e56ecedb78aeef66ce7972b082fce76a23e57" - integrity sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ== - dependencies: - "@babel/code-frame" "^7.28.6" - "@babel/parser" "^7.28.6" - "@babel/types" "^7.28.6" - -"@babel/traverse@^7.28.6": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/traverse/-/traverse-7.28.6.tgz#871ddc79a80599a5030c53b1cc48cbe3a5583c2e" - integrity sha512-fgWX62k02qtjqdSNTAGxmKYY/7FSL9WAS1o2Hu5+I5m9T0yxZzr4cnrfXQ/MX0rIifthCSs6FKTlzYbJcPtMNg== - dependencies: - "@babel/code-frame" "^7.28.6" - "@babel/generator" "^7.28.6" - "@babel/helper-globals" "^7.28.0" - "@babel/parser" "^7.28.6" - "@babel/template" "^7.28.6" - "@babel/types" "^7.28.6" - debug "^4.3.1" - -"@babel/types@^7.0.0", "@babel/types@^7.20.7", "@babel/types@^7.28.2", "@babel/types@^7.28.6", "@babel/types@^7.3.3": - version "7.28.6" - resolved "https://registry.yarnpkg.com/@babel/types/-/types-7.28.6.tgz#c3e9377f1b155005bcc4c46020e7e394e13089df" - integrity sha512-0ZrskXVEHSWIqZM/sQZ4EV3jZJXRkio/WCxaqKZP1g//CEWEPSfeZFcms4XeKBCHU0ZKnIkdJeU/kF+eRp5lBg== - dependencies: - "@babel/helper-string-parser" "^7.27.1" - "@babel/helper-validator-identifier" "^7.28.5" - -"@bcoe/v8-coverage@^0.2.3": - version "0.2.3" - resolved "https://registry.yarnpkg.com/@bcoe/v8-coverage/-/v8-coverage-0.2.3.tgz#75a2e8b51cb758a7553d6804a5932d7aace75c39" - integrity sha512-0hYQ8SB4Db5zvZB4axdMHGwEaQjkZzFjQiN9LVYvIFB2nSUHW9tYpxWriPrWDASIxiaXax83REcLxuSdnGPZtw== - -"@cloudflare/cabidela@^0.2.4": - version "0.2.4" - resolved "https://registry.yarnpkg.com/@cloudflare/cabidela/-/cabidela-0.2.4.tgz#9a3e9212e636a24d796a8f16741c24885b326a1a" - integrity sha512-u/1OwwqfcMvjmUFOcb6QtFzVVGpncHJxwl254wjzp0JC5CUlBkV6r5BbRrHI5ZYJEAgu8NeeorirxngmMFPZjQ== - -"@cspotcode/source-map-support@^0.8.0": - version "0.8.1" - resolved "https://registry.yarnpkg.com/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz#00629c35a688e05a88b1cda684fb9d5e73f000a1" - integrity sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw== - dependencies: - "@jridgewell/trace-mapping" "0.3.9" - -"@eslint-community/eslint-utils@^4.4.0", "@eslint-community/eslint-utils@^4.8.0": - version "4.9.1" - resolved "https://registry.yarnpkg.com/@eslint-community/eslint-utils/-/eslint-utils-4.9.1.tgz#4e90af67bc51ddee6cdef5284edf572ec376b595" - integrity sha512-phrYmNiYppR7znFEdqgfWHXR6NCkZEK7hwWDHZUjit/2/U0r6XvkDl0SYnoM51Hq7FhCGdLDT6zxCCOY1hexsQ== - dependencies: - eslint-visitor-keys "^3.4.3" - -"@eslint-community/regexpp@^4.10.0", "@eslint-community/regexpp@^4.12.1": - version "4.12.2" - resolved "https://registry.yarnpkg.com/@eslint-community/regexpp/-/regexpp-4.12.2.tgz#bccdf615bcf7b6e8db830ec0b8d21c9a25de597b" - integrity sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew== - -"@eslint/config-array@^0.21.2": - version "0.21.2" - resolved "https://registry.yarnpkg.com/@eslint/config-array/-/config-array-0.21.2.tgz#f29e22057ad5316cf23836cee9a34c81fffcb7e6" - integrity sha512-nJl2KGTlrf9GjLimgIru+V/mzgSK0ABCDQRvxw5BjURL7WfH5uoWmizbH7QB6MmnMBd8cIC9uceWnezL1VZWWw== - dependencies: - "@eslint/object-schema" "^2.1.7" - debug "^4.3.1" - minimatch "^3.1.5" - -"@eslint/config-helpers@^0.4.2": - version "0.4.2" - resolved "https://registry.yarnpkg.com/@eslint/config-helpers/-/config-helpers-0.4.2.tgz#1bd006ceeb7e2e55b2b773ab318d300e1a66aeda" - integrity sha512-gBrxN88gOIf3R7ja5K9slwNayVcZgK6SOUORm2uBzTeIEfeVaIhOpCtTox3P6R7o2jLFwLFTLnC7kU/RGcYEgw== - dependencies: - "@eslint/core" "^0.17.0" - -"@eslint/core@^0.17.0": - version "0.17.0" - resolved "https://registry.yarnpkg.com/@eslint/core/-/core-0.17.0.tgz#77225820413d9617509da9342190a2019e78761c" - integrity sha512-yL/sLrpmtDaFEiUj1osRP4TI2MDz1AddJL+jZ7KSqvBuliN4xqYY54IfdN8qD8Toa6g1iloph1fxQNkjOxrrpQ== - dependencies: - "@types/json-schema" "^7.0.15" - -"@eslint/eslintrc@^3.3.5": - version "3.3.5" - resolved "https://registry.yarnpkg.com/@eslint/eslintrc/-/eslintrc-3.3.5.tgz#c131793cfc1a7b96f24a83e0a8bbd4b881558c60" - integrity sha512-4IlJx0X0qftVsN5E+/vGujTRIFtwuLbNsVUe7TO6zYPDR1O6nFwvwhIKEKSrl6dZchmYBITazxKoUYOjdtjlRg== - dependencies: - ajv "^6.14.0" - debug "^4.3.2" - espree "^10.0.1" - globals "^14.0.0" - ignore "^5.2.0" - import-fresh "^3.2.1" - js-yaml "^4.1.1" - minimatch "^3.1.5" - strip-json-comments "^3.1.1" - -"@eslint/js@9.39.4": - version "9.39.4" - resolved "https://registry.yarnpkg.com/@eslint/js/-/js-9.39.4.tgz#a3f83bfc6fd9bf33a853dfacd0b49b398eb596c1" - integrity sha512-nE7DEIchvtiFTwBw4Lfbu59PG+kCofhjsKaCWzxTpt4lfRjRMqG6uMBzKXuEcyXhOHoUp9riAm7/aWYGhXZ9cw== - -"@eslint/object-schema@^2.1.7": - version "2.1.7" - resolved "https://registry.yarnpkg.com/@eslint/object-schema/-/object-schema-2.1.7.tgz#6e2126a1347e86a4dedf8706ec67ff8e107ebbad" - integrity sha512-VtAOaymWVfZcmZbp6E2mympDIHvyjXs/12LqWYjVw6qjrfF+VK+fyG33kChz3nnK+SU5/NeHOqrTEHS8sXO3OA== - -"@eslint/plugin-kit@^0.4.1": - version "0.4.1" - resolved "https://registry.yarnpkg.com/@eslint/plugin-kit/-/plugin-kit-0.4.1.tgz#9779e3fd9b7ee33571a57435cf4335a1794a6cb2" - integrity sha512-43/qtrDUokr7LJqoF2c3+RInu/t4zfrpYdoSDfYyhg52rwLV6TnOvdG4fXm7IkSB3wErkcmJS9iEhjVtOSEjjA== - dependencies: - "@eslint/core" "^0.17.0" - levn "^0.4.1" - -"@hono/node-server@^1.19.10", "@hono/node-server@^1.19.9": - version "1.19.11" - resolved "https://registry.yarnpkg.com/@hono/node-server/-/node-server-1.19.11.tgz#dc419f0826dd2504e9fc86ad289d5636a0444e2f" - integrity sha512-dr8/3zEaB+p0D2n/IUrlPF1HZm586qgJNXK1a9fhg/PzdtkK7Ksd5l312tJX2yBuALqDYBlG20QEbayqPyxn+g== - -"@humanfs/core@^0.19.1": - version "0.19.1" - resolved "https://registry.yarnpkg.com/@humanfs/core/-/core-0.19.1.tgz#17c55ca7d426733fe3c561906b8173c336b40a77" - integrity sha512-5DyQ4+1JEUzejeK1JGICcideyfUbGixgS9jNgex5nqkW+cY7WZhxBigmieN5Qnw9ZosSNVC9KQKyb+GUaGyKUA== - -"@humanfs/node@^0.16.6": - version "0.16.7" - resolved "https://registry.yarnpkg.com/@humanfs/node/-/node-0.16.7.tgz#822cb7b3a12c5a240a24f621b5a2413e27a45f26" - integrity sha512-/zUx+yOsIrG4Y43Eh2peDeKCxlRt/gET6aHfaKpuq267qXdYDFViVHfMaLyygZOnl0kGWxFIgsBy8QFuTLUXEQ== - dependencies: - "@humanfs/core" "^0.19.1" - "@humanwhocodes/retry" "^0.4.0" - -"@humanwhocodes/module-importer@^1.0.1": - version "1.0.1" - resolved "https://registry.yarnpkg.com/@humanwhocodes/module-importer/-/module-importer-1.0.1.tgz#af5b2691a22b44be847b0ca81641c5fb6ad0172c" - integrity sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA== - -"@humanwhocodes/retry@^0.4.0", "@humanwhocodes/retry@^0.4.2": - version "0.4.3" - resolved "https://registry.yarnpkg.com/@humanwhocodes/retry/-/retry-0.4.3.tgz#c2b9d2e374ee62c586d3adbea87199b1d7a7a6ba" - integrity sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ== - -"@inquirer/checkbox@^3.0.1": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/checkbox/-/checkbox-3.0.1.tgz#0a57f704265f78c36e17f07e421b98efb4b9867b" - integrity sha512-0hm2nrToWUdD6/UHnel/UKGdk1//ke5zGUpHIvk5ZWmaKezlGxZkOJXNSWsdxO/rEqTkbB3lNC2J6nBElV2aAQ== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/figures" "^1.0.6" - "@inquirer/type" "^2.0.0" - ansi-escapes "^4.3.2" - yoctocolors-cjs "^2.1.2" - -"@inquirer/confirm@^4.0.1": - version "4.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/confirm/-/confirm-4.0.1.tgz#9106d6bffa0b2fdd0e4f60319b6f04f2e06e6e25" - integrity sha512-46yL28o2NJ9doViqOy0VDcoTzng7rAb6yPQKU7VDLqkmbCaH4JqK4yk4XqlzNWy9PVC5pG1ZUXPBQv+VqnYs2w== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/type" "^2.0.0" - -"@inquirer/core@^9.2.1": - version "9.2.1" - resolved "https://registry.yarnpkg.com/@inquirer/core/-/core-9.2.1.tgz#677c49dee399c9063f31e0c93f0f37bddc67add1" - integrity sha512-F2VBt7W/mwqEU4bL0RnHNZmC/OxzNx9cOYxHqnXX3MP6ruYvZUZAW9imgN9+h/uBT/oP8Gh888J2OZSbjSeWcg== - dependencies: - "@inquirer/figures" "^1.0.6" - "@inquirer/type" "^2.0.0" - "@types/mute-stream" "^0.0.4" - "@types/node" "^22.5.5" - "@types/wrap-ansi" "^3.0.0" - ansi-escapes "^4.3.2" - cli-width "^4.1.0" - mute-stream "^1.0.0" - signal-exit "^4.1.0" - strip-ansi "^6.0.1" - wrap-ansi "^6.2.0" - yoctocolors-cjs "^2.1.2" - -"@inquirer/editor@^3.0.1": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/editor/-/editor-3.0.1.tgz#d109f21e050af6b960725388cb1c04214ed7c7bc" - integrity sha512-VA96GPFaSOVudjKFraokEEmUQg/Lub6OXvbIEZU1SDCmBzRkHGhxoFAVaF30nyiB4m5cEbDgiI2QRacXZ2hw9Q== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/type" "^2.0.0" - external-editor "^3.1.0" - -"@inquirer/expand@^3.0.1": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/expand/-/expand-3.0.1.tgz#aed9183cac4d12811be47a4a895ea8e82a17e22c" - integrity sha512-ToG8d6RIbnVpbdPdiN7BCxZGiHOTomOX94C2FaT5KOHupV40tKEDozp12res6cMIfRKrXLJyexAZhWVHgbALSQ== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/type" "^2.0.0" - yoctocolors-cjs "^2.1.2" - -"@inquirer/figures@^1.0.6": - version "1.0.15" - resolved "https://registry.yarnpkg.com/@inquirer/figures/-/figures-1.0.15.tgz#dbb49ed80df11df74268023b496ac5d9acd22b3a" - integrity sha512-t2IEY+unGHOzAaVM5Xx6DEWKeXlDDcNPeDyUpsRc6CUhBfU3VQOEl+Vssh7VNp1dR8MdUJBWhuObjXCsVpjN5g== - -"@inquirer/input@^3.0.1": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/input/-/input-3.0.1.tgz#de63d49e516487388508d42049deb70f2cb5f28e" - integrity sha512-BDuPBmpvi8eMCxqC5iacloWqv+5tQSJlUafYWUe31ow1BVXjW2a5qe3dh4X/Z25Wp22RwvcaLCc2siHobEOfzg== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/type" "^2.0.0" - -"@inquirer/number@^2.0.1": - version "2.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/number/-/number-2.0.1.tgz#b9863080d02ab7dc2e56e16433d83abea0f2a980" - integrity sha512-QpR8jPhRjSmlr/mD2cw3IR8HRO7lSVOnqUvQa8scv1Lsr3xoAMMworcYW3J13z3ppjBFBD2ef1Ci6AE5Qn8goQ== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/type" "^2.0.0" - -"@inquirer/password@^3.0.1": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/password/-/password-3.0.1.tgz#2a9a9143591088336bbd573bcb05d5bf080dbf87" - integrity sha512-haoeEPUisD1NeE2IanLOiFr4wcTXGWrBOyAyPZi1FfLJuXOzNmxCJPgUrGYKVh+Y8hfGJenIfz5Wb/DkE9KkMQ== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/type" "^2.0.0" - ansi-escapes "^4.3.2" - -"@inquirer/prompts@^6.0.1": - version "6.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/prompts/-/prompts-6.0.1.tgz#43f5c0ed35c5ebfe52f1d43d46da2d363d950071" - integrity sha512-yl43JD/86CIj3Mz5mvvLJqAOfIup7ncxfJ0Btnl0/v5TouVUyeEdcpknfgc+yMevS/48oH9WAkkw93m7otLb/A== - dependencies: - "@inquirer/checkbox" "^3.0.1" - "@inquirer/confirm" "^4.0.1" - "@inquirer/editor" "^3.0.1" - "@inquirer/expand" "^3.0.1" - "@inquirer/input" "^3.0.1" - "@inquirer/number" "^2.0.1" - "@inquirer/password" "^3.0.1" - "@inquirer/rawlist" "^3.0.1" - "@inquirer/search" "^2.0.1" - "@inquirer/select" "^3.0.1" - -"@inquirer/rawlist@^3.0.1": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/rawlist/-/rawlist-3.0.1.tgz#729def358419cc929045f264131878ed379e0af3" - integrity sha512-VgRtFIwZInUzTiPLSfDXK5jLrnpkuSOh1ctfaoygKAdPqjcjKYmGh6sCY1pb0aGnCGsmhUxoqLDUAU0ud+lGXQ== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/type" "^2.0.0" - yoctocolors-cjs "^2.1.2" - -"@inquirer/search@^2.0.1": - version "2.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/search/-/search-2.0.1.tgz#69b774a0a826de2e27b48981d01bc5ad81e73721" - integrity sha512-r5hBKZk3g5MkIzLVoSgE4evypGqtOannnB3PKTG9NRZxyFRKcfzrdxXXPcoJQsxJPzvdSU2Rn7pB7lw0GCmGAg== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/figures" "^1.0.6" - "@inquirer/type" "^2.0.0" - yoctocolors-cjs "^2.1.2" - -"@inquirer/select@^3.0.1": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@inquirer/select/-/select-3.0.1.tgz#1df9ed27fb85a5f526d559ac5ce7cc4e9dc4e7ec" - integrity sha512-lUDGUxPhdWMkN/fHy1Lk7pF3nK1fh/gqeyWXmctefhxLYxlDsc7vsPBEpxrfVGDsVdyYJsiJoD4bJ1b623cV1Q== - dependencies: - "@inquirer/core" "^9.2.1" - "@inquirer/figures" "^1.0.6" - "@inquirer/type" "^2.0.0" - ansi-escapes "^4.3.2" - yoctocolors-cjs "^2.1.2" - -"@inquirer/type@^2.0.0": - version "2.0.0" - resolved "https://registry.yarnpkg.com/@inquirer/type/-/type-2.0.0.tgz#08fa513dca2cb6264fe1b0a2fabade051444e3f6" - integrity sha512-XvJRx+2KR3YXyYtPUUy+qd9i7p+GO9Ko6VIIpWlBrpWwXDv8WLFeHTxz35CfQFUiBMLXlGHhGzys7lqit9gWag== - dependencies: - mute-stream "^1.0.0" - -"@istanbuljs/load-nyc-config@^1.0.0": - version "1.1.0" - resolved "https://registry.yarnpkg.com/@istanbuljs/load-nyc-config/-/load-nyc-config-1.1.0.tgz#fd3db1d59ecf7cf121e80650bb86712f9b55eced" - integrity sha512-VjeHSlIzpv/NyD3N0YuHfXOPDIixcA1q2ZV98wsMqcYlPmv2n3Yb2lYP9XMElnaFVXg5A7YLTeLu6V84uQDjmQ== - dependencies: - camelcase "^5.3.1" - find-up "^4.1.0" - get-package-type "^0.1.0" - js-yaml "^3.13.1" - resolve-from "^5.0.0" - -"@istanbuljs/schema@^0.1.2", "@istanbuljs/schema@^0.1.3": - version "0.1.3" - resolved "https://registry.yarnpkg.com/@istanbuljs/schema/-/schema-0.1.3.tgz#e45e384e4b8ec16bce2fd903af78450f6bf7ec98" - integrity sha512-ZXRY4jNvVgSVQ8DL3LTcakaAtXwTVUxE81hslsyD2AtoXW/wVob10HkOJ1X/pAlcI7D+2YoZKg5do8G/w6RYgA== - -"@jest/console@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/console/-/console-29.7.0.tgz#cd4822dbdb84529265c5a2bdb529a3c9cc950ffc" - integrity sha512-5Ni4CU7XHQi32IJ398EEP4RrB8eV09sXP2ROqD4bksHrnTree52PsxvX8tpL8LvTZ3pFzXyPbNQReSN41CAhOg== - dependencies: - "@jest/types" "^29.6.3" - "@types/node" "*" - chalk "^4.0.0" - jest-message-util "^29.7.0" - jest-util "^29.7.0" - slash "^3.0.0" - -"@jest/core@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/core/-/core-29.7.0.tgz#b6cccc239f30ff36609658c5a5e2291757ce448f" - integrity sha512-n7aeXWKMnGtDA48y8TLWJPJmLmmZ642Ceo78cYWEpiD7FzDgmNDV/GCVRorPABdXLJZ/9wzzgZAlHjXjxDHGsg== - dependencies: - "@jest/console" "^29.7.0" - "@jest/reporters" "^29.7.0" - "@jest/test-result" "^29.7.0" - "@jest/transform" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/node" "*" - ansi-escapes "^4.2.1" - chalk "^4.0.0" - ci-info "^3.2.0" - exit "^0.1.2" - graceful-fs "^4.2.9" - jest-changed-files "^29.7.0" - jest-config "^29.7.0" - jest-haste-map "^29.7.0" - jest-message-util "^29.7.0" - jest-regex-util "^29.6.3" - jest-resolve "^29.7.0" - jest-resolve-dependencies "^29.7.0" - jest-runner "^29.7.0" - jest-runtime "^29.7.0" - jest-snapshot "^29.7.0" - jest-util "^29.7.0" - jest-validate "^29.7.0" - jest-watcher "^29.7.0" - micromatch "^4.0.4" - pretty-format "^29.7.0" - slash "^3.0.0" - strip-ansi "^6.0.0" - -"@jest/environment@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/environment/-/environment-29.7.0.tgz#24d61f54ff1f786f3cd4073b4b94416383baf2a7" - integrity sha512-aQIfHDq33ExsN4jP1NWGXhxgQ/wixs60gDiKO+XVMd8Mn0NWPWgc34ZQDTb2jKaUWQ7MuwoitXAsN2XVXNMpAw== - dependencies: - "@jest/fake-timers" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/node" "*" - jest-mock "^29.7.0" - -"@jest/expect-utils@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/expect-utils/-/expect-utils-29.7.0.tgz#023efe5d26a8a70f21677d0a1afc0f0a44e3a1c6" - integrity sha512-GlsNBWiFQFCVi9QVSx7f5AgMeLxe9YCCs5PuP2O2LdjDAA8Jh9eX7lA1Jq/xdXw3Wb3hyvlFNfZIfcRetSzYcA== - dependencies: - jest-get-type "^29.6.3" - -"@jest/expect@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/expect/-/expect-29.7.0.tgz#76a3edb0cb753b70dfbfe23283510d3d45432bf2" - integrity sha512-8uMeAMycttpva3P1lBHB8VciS9V0XAr3GymPpipdyQXbBcuhkLQOSe8E/p92RyAdToS6ZD1tFkX+CkhoECE0dQ== - dependencies: - expect "^29.7.0" - jest-snapshot "^29.7.0" - -"@jest/fake-timers@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/fake-timers/-/fake-timers-29.7.0.tgz#fd91bf1fffb16d7d0d24a426ab1a47a49881a565" - integrity sha512-q4DH1Ha4TTFPdxLsqDXK1d3+ioSL7yL5oCMJZgDYm6i+6CygW5E5xVr/D1HdsGxjt1ZWSfUAs9OxSB/BNelWrQ== - dependencies: - "@jest/types" "^29.6.3" - "@sinonjs/fake-timers" "^10.0.2" - "@types/node" "*" - jest-message-util "^29.7.0" - jest-mock "^29.7.0" - jest-util "^29.7.0" - -"@jest/globals@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/globals/-/globals-29.7.0.tgz#8d9290f9ec47ff772607fa864ca1d5a2efae1d4d" - integrity sha512-mpiz3dutLbkW2MNFubUGUEVLkTGiqW6yLVTA+JbP6fI6J5iL9Y0Nlg8k95pcF8ctKwCS7WVxteBs29hhfAotzQ== - dependencies: - "@jest/environment" "^29.7.0" - "@jest/expect" "^29.7.0" - "@jest/types" "^29.6.3" - jest-mock "^29.7.0" - -"@jest/reporters@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/reporters/-/reporters-29.7.0.tgz#04b262ecb3b8faa83b0b3d321623972393e8f4c7" - integrity sha512-DApq0KJbJOEzAFYjHADNNxAE3KbhxQB1y5Kplb5Waqw6zVbuWatSnMjE5gs8FUgEPmNsnZA3NCWl9NG0ia04Pg== - dependencies: - "@bcoe/v8-coverage" "^0.2.3" - "@jest/console" "^29.7.0" - "@jest/test-result" "^29.7.0" - "@jest/transform" "^29.7.0" - "@jest/types" "^29.6.3" - "@jridgewell/trace-mapping" "^0.3.18" - "@types/node" "*" - chalk "^4.0.0" - collect-v8-coverage "^1.0.0" - exit "^0.1.2" - glob "^7.1.3" - graceful-fs "^4.2.9" - istanbul-lib-coverage "^3.0.0" - istanbul-lib-instrument "^6.0.0" - istanbul-lib-report "^3.0.0" - istanbul-lib-source-maps "^4.0.0" - istanbul-reports "^3.1.3" - jest-message-util "^29.7.0" - jest-util "^29.7.0" - jest-worker "^29.7.0" - slash "^3.0.0" - string-length "^4.0.1" - strip-ansi "^6.0.0" - v8-to-istanbul "^9.0.1" - -"@jest/schemas@^29.6.3": - version "29.6.3" - resolved "https://registry.yarnpkg.com/@jest/schemas/-/schemas-29.6.3.tgz#430b5ce8a4e0044a7e3819663305a7b3091c8e03" - integrity sha512-mo5j5X+jIZmJQveBKeS/clAueipV7KgiX1vMgCxam1RNYiqE1w62n0/tJJnHtjW8ZHcQco5gY85jA3mi0L+nSA== - dependencies: - "@sinclair/typebox" "^0.27.8" - -"@jest/source-map@^29.6.3": - version "29.6.3" - resolved "https://registry.yarnpkg.com/@jest/source-map/-/source-map-29.6.3.tgz#d90ba772095cf37a34a5eb9413f1b562a08554c4" - integrity sha512-MHjT95QuipcPrpLM+8JMSzFx6eHp5Bm+4XeFDJlwsvVBjmKNiIAvasGK2fxz2WbGRlnvqehFbh07MMa7n3YJnw== - dependencies: - "@jridgewell/trace-mapping" "^0.3.18" - callsites "^3.0.0" - graceful-fs "^4.2.9" - -"@jest/test-result@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/test-result/-/test-result-29.7.0.tgz#8db9a80aa1a097bb2262572686734baed9b1657c" - integrity sha512-Fdx+tv6x1zlkJPcWXmMDAG2HBnaR9XPSd5aDWQVsfrZmLVT3lU1cwyxLgRmXR9yrq4NBoEm9BMsfgFzTQAbJYA== - dependencies: - "@jest/console" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/istanbul-lib-coverage" "^2.0.0" - collect-v8-coverage "^1.0.0" - -"@jest/test-sequencer@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/test-sequencer/-/test-sequencer-29.7.0.tgz#6cef977ce1d39834a3aea887a1726628a6f072ce" - integrity sha512-GQwJ5WZVrKnOJuiYiAF52UNUJXgTZx1NHjFSEB0qEMmSZKAkdMoIzw/Cj6x6NF4AvV23AUqDpFzQkN/eYCYTxw== - dependencies: - "@jest/test-result" "^29.7.0" - graceful-fs "^4.2.9" - jest-haste-map "^29.7.0" - slash "^3.0.0" - -"@jest/transform@^29.7.0": - version "29.7.0" - resolved "https://registry.yarnpkg.com/@jest/transform/-/transform-29.7.0.tgz#df2dd9c346c7d7768b8a06639994640c642e284c" - integrity sha512-ok/BTPFzFKVMwO5eOHRrvnBVHdRy9IrsrW1GpMaQ9MCnilNLXQKmAX8s1YXDFaai9xJpac2ySzV0YeRRECr2Vw== - dependencies: - "@babel/core" "^7.11.6" - "@jest/types" "^29.6.3" - "@jridgewell/trace-mapping" "^0.3.18" - babel-plugin-istanbul "^6.1.1" - chalk "^4.0.0" - convert-source-map "^2.0.0" - fast-json-stable-stringify "^2.1.0" - graceful-fs "^4.2.9" - jest-haste-map "^29.7.0" - jest-regex-util "^29.6.3" - jest-util "^29.7.0" - micromatch "^4.0.4" - pirates "^4.0.4" - slash "^3.0.0" - write-file-atomic "^4.0.2" - -"@jest/types@^29.6.3": - version "29.6.3" - resolved "https://registry.yarnpkg.com/@jest/types/-/types-29.6.3.tgz#1131f8cf634e7e84c5e77bab12f052af585fba59" - integrity sha512-u3UPsIilWKOM3F9CXtrG8LEJmNxwoCQC/XVj4IKYXvvpx7QIi/Kg1LI5uDmDpKlac62NUtX7eLjRh+jVZcLOzw== - dependencies: - "@jest/schemas" "^29.6.3" - "@types/istanbul-lib-coverage" "^2.0.0" - "@types/istanbul-reports" "^3.0.0" - "@types/node" "*" - "@types/yargs" "^17.0.8" - chalk "^4.0.0" - -"@jridgewell/gen-mapping@^0.3.12", "@jridgewell/gen-mapping@^0.3.5": - version "0.3.13" - resolved "https://registry.yarnpkg.com/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz#6342a19f44347518c93e43b1ac69deb3c4656a1f" - integrity sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA== - dependencies: - "@jridgewell/sourcemap-codec" "^1.5.0" - "@jridgewell/trace-mapping" "^0.3.24" - -"@jridgewell/remapping@^2.3.5": - version "2.3.5" - resolved "https://registry.yarnpkg.com/@jridgewell/remapping/-/remapping-2.3.5.tgz#375c476d1972947851ba1e15ae8f123047445aa1" - integrity sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ== - dependencies: - "@jridgewell/gen-mapping" "^0.3.5" - "@jridgewell/trace-mapping" "^0.3.24" - -"@jridgewell/resolve-uri@^3.0.3", "@jridgewell/resolve-uri@^3.1.0": - version "3.1.2" - resolved "https://registry.yarnpkg.com/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz#7a0ee601f60f99a20c7c7c5ff0c80388c1189bd6" - integrity sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw== - -"@jridgewell/sourcemap-codec@^1.4.10", "@jridgewell/sourcemap-codec@^1.4.14", "@jridgewell/sourcemap-codec@^1.5.0": - version "1.5.5" - resolved "https://registry.yarnpkg.com/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz#6912b00d2c631c0d15ce1a7ab57cd657f2a8f8ba" - integrity sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og== - -"@jridgewell/trace-mapping@0.3.9": - version "0.3.9" - resolved "https://registry.yarnpkg.com/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz#6534fd5933a53ba7cbf3a17615e273a0d1273ff9" - integrity sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ== - dependencies: - "@jridgewell/resolve-uri" "^3.0.3" - "@jridgewell/sourcemap-codec" "^1.4.10" - -"@jridgewell/trace-mapping@^0.3.12", "@jridgewell/trace-mapping@^0.3.18", "@jridgewell/trace-mapping@^0.3.24", "@jridgewell/trace-mapping@^0.3.28": - version "0.3.31" - resolved "https://registry.yarnpkg.com/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz#db15d6781c931f3a251a3dac39501c98a6082fd0" - integrity sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw== - dependencies: - "@jridgewell/resolve-uri" "^3.1.0" - "@jridgewell/sourcemap-codec" "^1.4.14" - -"@modelcontextprotocol/sdk@^1.27.1": - version "1.27.1" - resolved "https://registry.yarnpkg.com/@modelcontextprotocol/sdk/-/sdk-1.27.1.tgz#a602cf823bf8a68e13e7112f50aeb02b09fb83b9" - integrity sha512-sr6GbP+4edBwFndLbM60gf07z0FQ79gaExpnsjMGePXqFcSSb7t6iscpjk9DhFhwd+mTEQrzNafGP8/iGGFYaA== - dependencies: - "@hono/node-server" "^1.19.9" - ajv "^8.17.1" - ajv-formats "^3.0.1" - content-type "^1.0.5" - cors "^2.8.5" - cross-spawn "^7.0.5" - eventsource "^3.0.2" - eventsource-parser "^3.0.0" - express "^5.2.1" - express-rate-limit "^8.2.1" - hono "^4.11.4" - jose "^6.1.3" - json-schema-typed "^8.0.2" - pkce-challenge "^5.0.0" - raw-body "^3.0.0" - zod "^3.25 || ^4.0" - zod-to-json-schema "^3.25.1" - -"@nodelib/fs.scandir@2.1.5": - version "2.1.5" - resolved "https://registry.yarnpkg.com/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz#7619c2eb21b25483f6d167548b4cfd5a7488c3d5" - integrity sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g== - dependencies: - "@nodelib/fs.stat" "2.0.5" - run-parallel "^1.1.9" - -"@nodelib/fs.stat@2.0.5", "@nodelib/fs.stat@^2.0.2": - version "2.0.5" - resolved "https://registry.yarnpkg.com/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz#5bd262af94e9d25bd1e71b05deed44876a222e8b" - integrity sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A== - -"@nodelib/fs.walk@^1.2.3": - version "1.2.8" - resolved "https://registry.yarnpkg.com/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz#e95737e8bb6746ddedf69c556953494f196fe69a" - integrity sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg== - dependencies: - "@nodelib/fs.scandir" "2.1.5" - fastq "^1.6.0" - -"@pinojs/redact@^0.4.0": - version "0.4.0" - resolved "https://registry.yarnpkg.com/@pinojs/redact/-/redact-0.4.0.tgz#c3de060dd12640dcc838516aa2a6803cc7b2e9d6" - integrity sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg== - -"@pkgr/core@^0.2.9": - version "0.2.9" - resolved "https://registry.yarnpkg.com/@pkgr/core/-/core-0.2.9.tgz#d229a7b7f9dac167a156992ef23c7f023653f53b" - integrity sha512-QNqXyfVS2wm9hweSYD2O7F0G06uurj9kZ96TRQE5Y9hU7+tgdZwIkbAKc5Ocy1HxEY2kuDQa6cQ1WRs/O5LFKA== - -"@sinclair/typebox@^0.27.8": - version "0.27.8" - resolved "https://registry.yarnpkg.com/@sinclair/typebox/-/typebox-0.27.8.tgz#6667fac16c436b5434a387a34dedb013198f6e6e" - integrity sha512-+Fj43pSMwJs4KRrH/938Uf+uAELIgVBmQzg/q1YG10djyfA3TnrU8N8XzqCh/okZdszqBQTZf96idMfE5lnwTA== - -"@sinonjs/commons@^3.0.0": - version "3.0.1" - resolved "https://registry.yarnpkg.com/@sinonjs/commons/-/commons-3.0.1.tgz#1029357e44ca901a615585f6d27738dbc89084cd" - integrity sha512-K3mCHKQ9sVh8o1C9cxkwxaOmXoAMlDxC1mYyHrjqOWEcBjYr76t96zL2zlj5dUGZ3HSw240X1qgH3Mjf1yJWpQ== - dependencies: - type-detect "4.0.8" - -"@sinonjs/fake-timers@^10.0.2": - version "10.3.0" - resolved "https://registry.yarnpkg.com/@sinonjs/fake-timers/-/fake-timers-10.3.0.tgz#55fdff1ecab9f354019129daf4df0dd4d923ea66" - integrity sha512-V4BG07kuYSUkTCSBHG8G8TNhM+F19jXFWnQtzj+we8DrkpSBCee9Z3Ms8yiGer/dlmhe35/Xdgyo3/0rQKg7YA== - dependencies: - "@sinonjs/commons" "^3.0.0" - -"@ts-morph/common@~0.20.0": - version "0.20.0" - resolved "https://registry.yarnpkg.com/@ts-morph/common/-/common-0.20.0.tgz#3f161996b085ba4519731e4d24c35f6cba5b80af" - integrity sha512-7uKjByfbPpwuzkstL3L5MQyuXPSKdoNG93Fmi2JoDcTf3pEP731JdRFAduRVkOs8oqxPsXKA+ScrWkdQ8t/I+Q== - dependencies: - fast-glob "^3.2.12" - minimatch "^7.4.3" - mkdirp "^2.1.6" - path-browserify "^1.0.1" - -"@tsconfig/node10@^1.0.7": - version "1.0.12" - resolved "https://registry.yarnpkg.com/@tsconfig/node10/-/node10-1.0.12.tgz#be57ceac1e4692b41be9de6be8c32a106636dba4" - integrity sha512-UCYBaeFvM11aU2y3YPZ//O5Rhj+xKyzy7mvcIoAjASbigy8mHMryP5cK7dgjlz2hWxh1g5pLw084E0a/wlUSFQ== - -"@tsconfig/node12@^1.0.7": - version "1.0.11" - resolved "https://registry.yarnpkg.com/@tsconfig/node12/-/node12-1.0.11.tgz#ee3def1f27d9ed66dac6e46a295cffb0152e058d" - integrity sha512-cqefuRsh12pWyGsIoBKJA9luFu3mRxCA+ORZvA4ktLSzIuCUtWVxGIuXigEwO5/ywWFMZ2QEGKWvkZG1zDMTag== - -"@tsconfig/node14@^1.0.0": - version "1.0.3" - resolved "https://registry.yarnpkg.com/@tsconfig/node14/-/node14-1.0.3.tgz#e4386316284f00b98435bf40f72f75a09dabf6c1" - integrity sha512-ysT8mhdixWK6Hw3i1V2AeRqZ5WfXg1G43mqoYlM2nc6388Fq5jcXyr5mRsqViLx/GJYdoL0bfXD8nmF+Zn/Iow== - -"@tsconfig/node16@^1.0.2": - version "1.0.4" - resolved "https://registry.yarnpkg.com/@tsconfig/node16/-/node16-1.0.4.tgz#0b92dcc0cc1c81f6f306a381f28e31b1a56536e9" - integrity sha512-vxhUy4J8lyeyinH7Azl1pdd43GJhZH/tP2weN8TntQblOY+A0XbT8DJk1/oCPuOOyg/Ja757rG0CgHcWC8OfMA== - -"@types/babel__core@^7.1.14": - version "7.20.5" - resolved "https://registry.yarnpkg.com/@types/babel__core/-/babel__core-7.20.5.tgz#3df15f27ba85319caa07ba08d0721889bb39c017" - integrity sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA== - dependencies: - "@babel/parser" "^7.20.7" - "@babel/types" "^7.20.7" - "@types/babel__generator" "*" - "@types/babel__template" "*" - "@types/babel__traverse" "*" - -"@types/babel__generator@*": - version "7.27.0" - resolved "https://registry.yarnpkg.com/@types/babel__generator/-/babel__generator-7.27.0.tgz#b5819294c51179957afaec341442f9341e4108a9" - integrity sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg== - dependencies: - "@babel/types" "^7.0.0" - -"@types/babel__template@*": - version "7.4.4" - resolved "https://registry.yarnpkg.com/@types/babel__template/-/babel__template-7.4.4.tgz#5672513701c1b2199bc6dad636a9d7491586766f" - integrity sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A== - dependencies: - "@babel/parser" "^7.1.0" - "@babel/types" "^7.0.0" - -"@types/babel__traverse@*", "@types/babel__traverse@^7.0.6": - version "7.28.0" - resolved "https://registry.yarnpkg.com/@types/babel__traverse/-/babel__traverse-7.28.0.tgz#07d713d6cce0d265c9849db0cbe62d3f61f36f74" - integrity sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q== - dependencies: - "@babel/types" "^7.28.2" - -"@types/body-parser@*": - version "1.19.6" - resolved "https://registry.yarnpkg.com/@types/body-parser/-/body-parser-1.19.6.tgz#1859bebb8fd7dac9918a45d54c1971ab8b5af474" - integrity sha512-HLFeCYgz89uk22N5Qg3dvGvsv46B8GLvKKo1zKG4NybA8U2DiEO3w9lqGg29t/tfLRJpJ6iQxnVw4OnB7MoM9g== - dependencies: - "@types/connect" "*" - "@types/node" "*" - -"@types/connect@*": - version "3.4.38" - resolved "https://registry.yarnpkg.com/@types/connect/-/connect-3.4.38.tgz#5ba7f3bc4fbbdeaff8dded952e5ff2cc53f8d858" - integrity sha512-K6uROf1LD88uDQqJCktA4yzL1YYAK6NgfsI0v/mTgyPKWsX1CnJ0XPSDhViejru1GcRkLWb8RlzFYJRqGUbaug== - dependencies: - "@types/node" "*" - -"@types/cookie-parser@^1.4.10": - version "1.4.10" - resolved "https://registry.yarnpkg.com/@types/cookie-parser/-/cookie-parser-1.4.10.tgz#a045272a383a30597a01955d4f9c790018f214e4" - integrity sha512-B4xqkqfZ8Wek+rCOeRxsjMS9OgvzebEzzLYw7NHYuvzb7IdxOkI0ZHGgeEBX4PUM7QGVvNSK60T3OvWj3YfBRg== - -"@types/cors@^2.8.19": - version "2.8.19" - resolved "https://registry.yarnpkg.com/@types/cors/-/cors-2.8.19.tgz#d93ea2673fd8c9f697367f5eeefc2bbfa94f0342" - integrity sha512-mFNylyeyqN93lfe/9CSxOGREz8cpzAhH+E93xJ4xWQf62V8sQ/24reV2nyzUWM6H6Xji+GGHpkbLe7pVoUEskg== - dependencies: - "@types/node" "*" - -"@types/estree@^1.0.6": - version "1.0.8" - resolved "https://registry.yarnpkg.com/@types/estree/-/estree-1.0.8.tgz#958b91c991b1867ced318bedea0e215ee050726e" - integrity sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w== - -"@types/express-serve-static-core@^5.0.0": - version "5.1.1" - resolved "https://registry.yarnpkg.com/@types/express-serve-static-core/-/express-serve-static-core-5.1.1.tgz#1a77faffee9572d39124933259be2523837d7eaa" - integrity sha512-v4zIMr/cX7/d2BpAEX3KNKL/JrT1s43s96lLvvdTmza1oEvDudCqK9aF/djc/SWgy8Yh0h30TZx5VpzqFCxk5A== - dependencies: - "@types/node" "*" - "@types/qs" "*" - "@types/range-parser" "*" - "@types/send" "*" - -"@types/express@^5.0.3": - version "5.0.6" - resolved "https://registry.yarnpkg.com/@types/express/-/express-5.0.6.tgz#2d724b2c990dcb8c8444063f3580a903f6d500cc" - integrity sha512-sKYVuV7Sv9fbPIt/442koC7+IIwK5olP1KWeD88e/idgoJqDm3JV/YUiPwkoKK92ylff2MGxSz1CSjsXelx0YA== - dependencies: - "@types/body-parser" "*" - "@types/express-serve-static-core" "^5.0.0" - "@types/serve-static" "^2" - -"@types/graceful-fs@^4.1.3": - version "4.1.9" - resolved "https://registry.yarnpkg.com/@types/graceful-fs/-/graceful-fs-4.1.9.tgz#2a06bc0f68a20ab37b3e36aa238be6abdf49e8b4" - integrity sha512-olP3sd1qOEe5dXTSaFvQG+02VdRXcdytWLAZsAq1PecU8uqQAhkrnbli7DagjtXKW/Bl7YJbUsa8MPcuc8LHEQ== - dependencies: - "@types/node" "*" - -"@types/http-errors@*": - version "2.0.5" - resolved "https://registry.yarnpkg.com/@types/http-errors/-/http-errors-2.0.5.tgz#5b749ab2b16ba113423feb1a64a95dcd30398472" - integrity sha512-r8Tayk8HJnX0FztbZN7oVqGccWgw98T/0neJphO91KkmOzug1KkofZURD4UaD5uH8AqcFLfdPErnBod0u71/qg== - -"@types/istanbul-lib-coverage@*", "@types/istanbul-lib-coverage@^2.0.0", "@types/istanbul-lib-coverage@^2.0.1": - version "2.0.6" - resolved "https://registry.yarnpkg.com/@types/istanbul-lib-coverage/-/istanbul-lib-coverage-2.0.6.tgz#7739c232a1fee9b4d3ce8985f314c0c6d33549d7" - integrity sha512-2QF/t/auWm0lsy8XtKVPG19v3sSOQlJe/YHZgfjb/KBBHOGSV+J2q/S671rcq9uTBrLAXmZpqJiaQbMT+zNU1w== - -"@types/istanbul-lib-report@*": - version "3.0.3" - resolved "https://registry.yarnpkg.com/@types/istanbul-lib-report/-/istanbul-lib-report-3.0.3.tgz#53047614ae72e19fc0401d872de3ae2b4ce350bf" - integrity sha512-NQn7AHQnk/RSLOxrBbGyJM/aVQ+pjj5HCgasFxc0K/KhoATfQ/47AyUl15I2yBUpihjmas+a+VJBOqecrFH+uA== - dependencies: - "@types/istanbul-lib-coverage" "*" - -"@types/istanbul-reports@^3.0.0": - version "3.0.4" - resolved "https://registry.yarnpkg.com/@types/istanbul-reports/-/istanbul-reports-3.0.4.tgz#0f03e3d2f670fbdac586e34b433783070cc16f54" - integrity sha512-pk2B1NWalF9toCRu6gjBzR69syFjP4Od8WRAX+0mmf9lAjCRicLOWc+ZrxZHx/0XRjotgkF9t6iaMJ+aXcOdZQ== - dependencies: - "@types/istanbul-lib-report" "*" - -"@types/jest@^29.4.0": - version "29.5.14" - resolved "https://registry.yarnpkg.com/@types/jest/-/jest-29.5.14.tgz#2b910912fa1d6856cadcd0c1f95af7df1d6049e5" - integrity sha512-ZN+4sdnLUbo8EVvVc2ao0GFW6oVrQRPn4K2lglySj7APvSrgzxHiNNK99us4WDMi57xxA2yggblIAMNhXOotLQ== - dependencies: - expect "^29.0.0" - pretty-format "^29.0.0" - -"@types/json-schema@^7.0.15": - version "7.0.15" - resolved "https://registry.yarnpkg.com/@types/json-schema/-/json-schema-7.0.15.tgz#596a1747233694d50f6ad8a7869fcb6f56cf5841" - integrity sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA== - -"@types/mute-stream@^0.0.4": - version "0.0.4" - resolved "https://registry.yarnpkg.com/@types/mute-stream/-/mute-stream-0.0.4.tgz#77208e56a08767af6c5e1237be8888e2f255c478" - integrity sha512-CPM9nzrCPPJHQNA9keH9CVkVI+WR5kMa+7XEs5jcGQ0VoAGnLv242w8lIVgwAEfmE4oufJRaTc9PNLQl0ioAow== - dependencies: - "@types/node" "*" - -"@types/node@*": - version "25.0.8" - resolved "https://registry.yarnpkg.com/@types/node/-/node-25.0.8.tgz#e54e00f94fe1db2497b3e42d292b8376a2678c8d" - integrity sha512-powIePYMmC3ibL0UJ2i2s0WIbq6cg6UyVFQxSCpaPxxzAaziRfimGivjdF943sSGV6RADVbk0Nvlm5P/FB44Zg== - dependencies: - undici-types "~7.16.0" - -"@types/node@^22.5.5": - version "22.19.6" - resolved "https://registry.yarnpkg.com/@types/node/-/node-22.19.6.tgz#0e9d80ebcd2dfce03265768c17a1212d4eb07e82" - integrity sha512-qm+G8HuG6hOHQigsi7VGuLjUVu6TtBo/F05zvX04Mw2uCg9Dv0Qxy3Qw7j41SidlTcl5D/5yg0SEZqOB+EqZnQ== - dependencies: - undici-types "~6.21.0" - -"@types/qs@*", "@types/qs@^6.14.0": - version "6.14.0" - resolved "https://registry.yarnpkg.com/@types/qs/-/qs-6.14.0.tgz#d8b60cecf62f2db0fb68e5e006077b9178b85de5" - integrity sha512-eOunJqu0K1923aExK6y8p6fsihYEn/BYuQ4g0CxAAgFc4b/ZLN4CrsRZ55srTdqoiLzU2B2evC+apEIxprEzkQ== - -"@types/range-parser@*": - version "1.2.7" - resolved "https://registry.yarnpkg.com/@types/range-parser/-/range-parser-1.2.7.tgz#50ae4353eaaddc04044279812f52c8c65857dbcb" - integrity sha512-hKormJbkJqzQGhziax5PItDUTMAM9uE2XXQmM37dyd4hVM+5aVl7oVxMVUiVQn2oCQFN/LKCZdvSM0pFRqbSmQ== - -"@types/send@*": - version "1.2.1" - resolved "https://registry.yarnpkg.com/@types/send/-/send-1.2.1.tgz#6a784e45543c18c774c049bff6d3dbaf045c9c74" - integrity sha512-arsCikDvlU99zl1g69TcAB3mzZPpxgw0UQnaHeC1Nwb015xp8bknZv5rIfri9xTOcMuaVgvabfIRA7PSZVuZIQ== - dependencies: - "@types/node" "*" - -"@types/serve-static@^2": - version "2.2.0" - resolved "https://registry.yarnpkg.com/@types/serve-static/-/serve-static-2.2.0.tgz#d4a447503ead0d1671132d1ab6bd58b805d8de6a" - integrity sha512-8mam4H1NHLtu7nmtalF7eyBH14QyOASmcxHhSfEoRyr0nP/YdoesEtU+uSRvMe96TW/HPTtkoKqQLl53N7UXMQ== - dependencies: - "@types/http-errors" "*" - "@types/node" "*" - -"@types/stack-utils@^2.0.0": - version "2.0.3" - resolved "https://registry.yarnpkg.com/@types/stack-utils/-/stack-utils-2.0.3.tgz#6209321eb2c1712a7e7466422b8cb1fc0d9dd5d8" - integrity sha512-9aEbYZ3TbYMznPdcdr3SmIrLXwC/AKZXQeCf9Pgao5CKb8CyHuEX5jzWPTkvregvhRJHcpRO6BFoGW9ycaOkYw== - -"@types/wrap-ansi@^3.0.0": - version "3.0.0" - resolved "https://registry.yarnpkg.com/@types/wrap-ansi/-/wrap-ansi-3.0.0.tgz#18b97a972f94f60a679fd5c796d96421b9abb9fd" - integrity sha512-ltIpx+kM7g/MLRZfkbL7EsCEjfzCcScLpkg37eXEtx5kmrAKBkTJwd1GIAjDSL8wTpM6Hzn5YO4pSb91BEwu1g== - -"@types/yargs-parser@*": - version "21.0.3" - resolved "https://registry.yarnpkg.com/@types/yargs-parser/-/yargs-parser-21.0.3.tgz#815e30b786d2e8f0dcd85fd5bcf5e1a04d008f15" - integrity sha512-I4q9QU9MQv4oEOz4tAHJtNz1cwuLxn2F3xcc2iV5WdqLPpUnj30aUuxt1mAxYTG+oe8CZMV/+6rU4S4gRDzqtQ== - -"@types/yargs@^17.0.8": - version "17.0.35" - resolved "https://registry.yarnpkg.com/@types/yargs/-/yargs-17.0.35.tgz#07013e46aa4d7d7d50a49e15604c1c5340d4eb24" - integrity sha512-qUHkeCyQFxMXg79wQfTtfndEC+N9ZZg76HJftDJp+qH2tV7Gj4OJi7l+PiWwJ+pWtW8GwSmqsDj/oymhrTWXjg== - dependencies: - "@types/yargs-parser" "*" - -"@typescript-eslint/eslint-plugin@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.31.1.tgz#62f1befe59647524994e89de4516d8dcba7a850a" - integrity sha512-oUlH4h1ABavI4F0Xnl8/fOtML/eu8nI2A1nYd+f+55XI0BLu+RIqKoCiZKNo6DtqZBEQm5aNKA20G3Z5w3R6GQ== - dependencies: - "@eslint-community/regexpp" "^4.10.0" - "@typescript-eslint/scope-manager" "8.31.1" - "@typescript-eslint/type-utils" "8.31.1" - "@typescript-eslint/utils" "8.31.1" - "@typescript-eslint/visitor-keys" "8.31.1" - graphemer "^1.4.0" - ignore "^5.3.1" - natural-compare "^1.4.0" - ts-api-utils "^2.0.1" - -"@typescript-eslint/parser@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/parser/-/parser-8.31.1.tgz#e9b0ccf30d37dde724ee4d15f4dbc195995cce1b" - integrity sha512-oU/OtYVydhXnumd0BobL9rkJg7wFJ9bFFPmSmB/bf/XWN85hlViji59ko6bSKBXyseT9V8l+CN1nwmlbiN0G7Q== - dependencies: - "@typescript-eslint/scope-manager" "8.31.1" - "@typescript-eslint/types" "8.31.1" - "@typescript-eslint/typescript-estree" "8.31.1" - "@typescript-eslint/visitor-keys" "8.31.1" - debug "^4.3.4" - -"@typescript-eslint/scope-manager@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/scope-manager/-/scope-manager-8.31.1.tgz#1eb52e76878f545e4add142e0d8e3e97e7aa443b" - integrity sha512-BMNLOElPxrtNQMIsFHE+3P0Yf1z0dJqV9zLdDxN/xLlWMlXK/ApEsVEKzpizg9oal8bAT5Sc7+ocal7AC1HCVw== - dependencies: - "@typescript-eslint/types" "8.31.1" - "@typescript-eslint/visitor-keys" "8.31.1" - -"@typescript-eslint/type-utils@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/type-utils/-/type-utils-8.31.1.tgz#be0f438fb24b03568e282a0aed85f776409f970c" - integrity sha512-fNaT/m9n0+dpSp8G/iOQ05GoHYXbxw81x+yvr7TArTuZuCA6VVKbqWYVZrV5dVagpDTtj/O8k5HBEE/p/HM5LA== - dependencies: - "@typescript-eslint/typescript-estree" "8.31.1" - "@typescript-eslint/utils" "8.31.1" - debug "^4.3.4" - ts-api-utils "^2.0.1" - -"@typescript-eslint/types@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/types/-/types-8.31.1.tgz#478ed6f7e8aee1be7b63a60212b6bffe1423b5d4" - integrity sha512-SfepaEFUDQYRoA70DD9GtytljBePSj17qPxFHA/h3eg6lPTqGJ5mWOtbXCk1YrVU1cTJRd14nhaXWFu0l2troQ== - -"@typescript-eslint/typescript-estree@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/typescript-estree/-/typescript-estree-8.31.1.tgz#37792fe7ef4d3021c7580067c8f1ae66daabacdf" - integrity sha512-kaA0ueLe2v7KunYOyWYtlf/QhhZb7+qh4Yw6Ni5kgukMIG+iP773tjgBiLWIXYumWCwEq3nLW+TUywEp8uEeag== - dependencies: - "@typescript-eslint/types" "8.31.1" - "@typescript-eslint/visitor-keys" "8.31.1" - debug "^4.3.4" - fast-glob "^3.3.2" - is-glob "^4.0.3" - minimatch "^9.0.4" - semver "^7.6.0" - ts-api-utils "^2.0.1" - -"@typescript-eslint/utils@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/utils/-/utils-8.31.1.tgz#5628ea0393598a0b2f143d0fc6d019f0dee9dd14" - integrity sha512-2DSI4SNfF5T4oRveQ4nUrSjUqjMND0nLq9rEkz0gfGr3tg0S5KB6DhwR+WZPCjzkZl3cH+4x2ce3EsL50FubjQ== - dependencies: - "@eslint-community/eslint-utils" "^4.4.0" - "@typescript-eslint/scope-manager" "8.31.1" - "@typescript-eslint/types" "8.31.1" - "@typescript-eslint/typescript-estree" "8.31.1" - -"@typescript-eslint/visitor-keys@8.31.1": - version "8.31.1" - resolved "https://registry.yarnpkg.com/@typescript-eslint/visitor-keys/-/visitor-keys-8.31.1.tgz#6742b0e3ba1e0c1e35bdaf78c03e759eb8dd8e75" - integrity sha512-I+/rgqOVBn6f0o7NDTmAPWWC6NuqhV174lfYvAm9fUaWeiefLdux9/YI3/nLugEn9L8fcSi0XmpKi/r5u0nmpw== - dependencies: - "@typescript-eslint/types" "8.31.1" - eslint-visitor-keys "^4.2.0" - -"@valtown/deno-http-worker@^0.0.21": - version "0.0.21" - resolved "https://registry.yarnpkg.com/@valtown/deno-http-worker/-/deno-http-worker-0.0.21.tgz#9ce3b5c1d0db211fe7ea8297881fe551838474ad" - integrity sha512-16kFuUykann75lNytnXXIQlmpzreZjzdyT27ebT3yNGCS3kKaS1iZYWHc3Si9An54Cphwr4qEcviChQkEeJBlA== - -accepts@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/accepts/-/accepts-2.0.0.tgz#bbcf4ba5075467f3f2131eab3cffc73c2f5d7895" - integrity sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng== - dependencies: - mime-types "^3.0.0" - negotiator "^1.0.0" - -acorn-jsx@^5.3.2: - version "5.3.2" - resolved "https://registry.yarnpkg.com/acorn-jsx/-/acorn-jsx-5.3.2.tgz#7ed5bb55908b3b2f1bc55c6af1653bada7f07937" - integrity sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ== - -acorn-walk@^8.1.1: - version "8.3.4" - resolved "https://registry.yarnpkg.com/acorn-walk/-/acorn-walk-8.3.4.tgz#794dd169c3977edf4ba4ea47583587c5866236b7" - integrity sha512-ueEepnujpqee2o5aIYnvHU6C0A42MNdsIDeqy5BydrkuC5R1ZuUFnm27EeFJGoEHJQgn3uleRvmTXaJgfXbt4g== - dependencies: - acorn "^8.11.0" - -acorn@^8.11.0, acorn@^8.4.1: - version "8.15.0" - resolved "https://registry.yarnpkg.com/acorn/-/acorn-8.15.0.tgz#a360898bc415edaac46c8241f6383975b930b816" - integrity sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg== - -acorn@^8.15.0: - version "8.16.0" - resolved "https://registry.yarnpkg.com/acorn/-/acorn-8.16.0.tgz#4ce79c89be40afe7afe8f3adb902a1f1ce9ac08a" - integrity sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw== - -aggregate-error@^3.0.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/aggregate-error/-/aggregate-error-3.1.0.tgz#92670ff50f5359bdb7a3e0d40d0ec30c5737687a" - integrity sha512-4I7Td01quW/RpocfNayFdFVk1qSuoh0E7JrbRJ16nH01HhKFQ88INq9Sd+nd72zqRySlr9BmDA8xlEJ6vJMrYA== - dependencies: - clean-stack "^2.0.0" - indent-string "^4.0.0" - -ajv-formats@^3.0.1: - version "3.0.1" - resolved "https://registry.yarnpkg.com/ajv-formats/-/ajv-formats-3.0.1.tgz#3d5dc762bca17679c3c2ea7e90ad6b7532309578" - integrity sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ== - dependencies: - ajv "^8.0.0" - -ajv@^6.14.0: - version "6.14.0" - resolved "https://registry.yarnpkg.com/ajv/-/ajv-6.14.0.tgz#fd067713e228210636ebb08c60bd3765d6dbe73a" - integrity sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw== - dependencies: - fast-deep-equal "^3.1.1" - fast-json-stable-stringify "^2.0.0" - json-schema-traverse "^0.4.1" - uri-js "^4.2.2" - -ajv@^8.0.0, ajv@^8.17.1: - version "8.17.1" - resolved "https://registry.yarnpkg.com/ajv/-/ajv-8.17.1.tgz#37d9a5c776af6bc92d7f4f9510eba4c0a60d11a6" - integrity sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g== - dependencies: - fast-deep-equal "^3.1.3" - fast-uri "^3.0.1" - json-schema-traverse "^1.0.0" - require-from-string "^2.0.2" - -ajv@^8.18.0: - version "8.18.0" - resolved "https://registry.yarnpkg.com/ajv/-/ajv-8.18.0.tgz#8864186b6738d003eb3a933172bb3833e10cefbc" - integrity sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A== - dependencies: - fast-deep-equal "^3.1.3" - fast-uri "^3.0.1" - json-schema-traverse "^1.0.0" - require-from-string "^2.0.2" - -ansi-escapes@^4.2.1, ansi-escapes@^4.3.2: - version "4.3.2" - resolved "https://registry.yarnpkg.com/ansi-escapes/-/ansi-escapes-4.3.2.tgz#6b2291d1db7d98b6521d5f1efa42d0f3a9feb65e" - integrity sha512-gKXj5ALrKWQLsYG9jlTRmR/xKluxHV+Z9QEwNIgCfM1/uwPMCuzVVnh5mwTd+OuBZcwSIMbqssNWRm1lE51QaQ== - dependencies: - type-fest "^0.21.3" - -ansi-regex@^5.0.1: - version "5.0.1" - resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-5.0.1.tgz#082cb2c89c9fe8659a311a53bd6a4dc5301db304" - integrity sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ== - -ansi-styles@^4.0.0, ansi-styles@^4.1.0: - version "4.3.0" - resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-4.3.0.tgz#edd803628ae71c04c85ae7a0906edad34b648937" - integrity sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg== - dependencies: - color-convert "^2.0.1" - -ansi-styles@^5.0.0: - version "5.2.0" - resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-5.2.0.tgz#07449690ad45777d1924ac2abb2fc8895dba836b" - integrity sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA== - -anymatch@^3.0.3: - version "3.1.3" - resolved "https://registry.yarnpkg.com/anymatch/-/anymatch-3.1.3.tgz#790c58b19ba1720a84205b57c618d5ad8524973e" - integrity sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw== - dependencies: - normalize-path "^3.0.0" - picomatch "^2.0.4" - -arg@^4.1.0: - version "4.1.3" - resolved "https://registry.yarnpkg.com/arg/-/arg-4.1.3.tgz#269fc7ad5b8e42cb63c896d5666017261c144089" - integrity sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA== - -argparse@^1.0.7: - version "1.0.10" - resolved "https://registry.yarnpkg.com/argparse/-/argparse-1.0.10.tgz#bcd6791ea5ae09725e17e5ad988134cd40b3d911" - integrity sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg== - dependencies: - sprintf-js "~1.0.2" - -argparse@^2.0.1: - version "2.0.1" - resolved "https://registry.yarnpkg.com/argparse/-/argparse-2.0.1.tgz#246f50f3ca78a3240f6c997e8a9bd1eac49e4b38" - integrity sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q== - -atomic-sleep@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/atomic-sleep/-/atomic-sleep-1.0.0.tgz#eb85b77a601fc932cfe432c5acd364a9e2c9075b" - integrity sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ== - -babel-jest@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/babel-jest/-/babel-jest-29.7.0.tgz#f4369919225b684c56085998ac63dbd05be020d5" - integrity sha512-BrvGY3xZSwEcCzKvKsCi2GgHqDqsYkOP4/by5xCgIwGXQxIEh+8ew3gmrE1y7XRR6LHZIj6yLYnUi/mm2KXKBg== - dependencies: - "@jest/transform" "^29.7.0" - "@types/babel__core" "^7.1.14" - babel-plugin-istanbul "^6.1.1" - babel-preset-jest "^29.6.3" - chalk "^4.0.0" - graceful-fs "^4.2.9" - slash "^3.0.0" - -babel-plugin-istanbul@^6.1.1: - version "6.1.1" - resolved "https://registry.yarnpkg.com/babel-plugin-istanbul/-/babel-plugin-istanbul-6.1.1.tgz#fa88ec59232fd9b4e36dbbc540a8ec9a9b47da73" - integrity sha512-Y1IQok9821cC9onCx5otgFfRm7Lm+I+wwxOx738M/WLPZ9Q42m4IG5W0FNX8WLL2gYMZo3JkuXIH2DOpWM+qwA== - dependencies: - "@babel/helper-plugin-utils" "^7.0.0" - "@istanbuljs/load-nyc-config" "^1.0.0" - "@istanbuljs/schema" "^0.1.2" - istanbul-lib-instrument "^5.0.4" - test-exclude "^6.0.0" - -babel-plugin-jest-hoist@^29.6.3: - version "29.6.3" - resolved "https://registry.yarnpkg.com/babel-plugin-jest-hoist/-/babel-plugin-jest-hoist-29.6.3.tgz#aadbe943464182a8922c3c927c3067ff40d24626" - integrity sha512-ESAc/RJvGTFEzRwOTT4+lNDk/GNHMkKbNzsvT0qKRfDyyYTskxB5rnU2njIDYVxXCBHHEI1c0YwHob3WaYujOg== - dependencies: - "@babel/template" "^7.3.3" - "@babel/types" "^7.3.3" - "@types/babel__core" "^7.1.14" - "@types/babel__traverse" "^7.0.6" - -babel-preset-current-node-syntax@^1.0.0: - version "1.2.0" - resolved "https://registry.yarnpkg.com/babel-preset-current-node-syntax/-/babel-preset-current-node-syntax-1.2.0.tgz#20730d6cdc7dda5d89401cab10ac6a32067acde6" - integrity sha512-E/VlAEzRrsLEb2+dv8yp3bo4scof3l9nR4lrld+Iy5NyVqgVYUJnDAmunkhPMisRI32Qc4iRiz425d8vM++2fg== - dependencies: - "@babel/plugin-syntax-async-generators" "^7.8.4" - "@babel/plugin-syntax-bigint" "^7.8.3" - "@babel/plugin-syntax-class-properties" "^7.12.13" - "@babel/plugin-syntax-class-static-block" "^7.14.5" - "@babel/plugin-syntax-import-attributes" "^7.24.7" - "@babel/plugin-syntax-import-meta" "^7.10.4" - "@babel/plugin-syntax-json-strings" "^7.8.3" - "@babel/plugin-syntax-logical-assignment-operators" "^7.10.4" - "@babel/plugin-syntax-nullish-coalescing-operator" "^7.8.3" - "@babel/plugin-syntax-numeric-separator" "^7.10.4" - "@babel/plugin-syntax-object-rest-spread" "^7.8.3" - "@babel/plugin-syntax-optional-catch-binding" "^7.8.3" - "@babel/plugin-syntax-optional-chaining" "^7.8.3" - "@babel/plugin-syntax-private-property-in-object" "^7.14.5" - "@babel/plugin-syntax-top-level-await" "^7.14.5" - -babel-preset-jest@^29.6.3: - version "29.6.3" - resolved "https://registry.yarnpkg.com/babel-preset-jest/-/babel-preset-jest-29.6.3.tgz#fa05fa510e7d493896d7b0dd2033601c840f171c" - integrity sha512-0B3bhxR6snWXJZtR/RliHTDPRgn1sNHOR0yVtq/IiQFyuOVjFS+wuio/R4gSNkyYmKmJB4wGZv2NZanmKmTnNA== - dependencies: - babel-plugin-jest-hoist "^29.6.3" - babel-preset-current-node-syntax "^1.0.0" - -balanced-match@^1.0.0: - version "1.0.2" - resolved "https://registry.yarnpkg.com/balanced-match/-/balanced-match-1.0.2.tgz#e83e3a7e3f300b34cb9d87f615fa0cbf357690ee" - integrity sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw== - -baseline-browser-mapping@^2.9.0: - version "2.9.14" - resolved "https://registry.yarnpkg.com/baseline-browser-mapping/-/baseline-browser-mapping-2.9.14.tgz#3b6af0bc032445bca04de58caa9a87cfe921cbb3" - integrity sha512-B0xUquLkiGLgHhpPBqvl7GWegWBUNuujQ6kXd/r1U38ElPT6Ok8KZ8e+FpUGEc2ZoRQUzq/aUnaKFc/svWUGSg== - -body-parser@^2.2.1: - version "2.2.2" - resolved "https://registry.yarnpkg.com/body-parser/-/body-parser-2.2.2.tgz#1a32cdb966beaf68de50a9dfbe5b58f83cb8890c" - integrity sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA== - dependencies: - bytes "^3.1.2" - content-type "^1.0.5" - debug "^4.4.3" - http-errors "^2.0.0" - iconv-lite "^0.7.0" - on-finished "^2.4.1" - qs "^6.14.1" - raw-body "^3.0.1" - type-is "^2.0.1" - -brace-expansion@^1.1.7: - version "1.1.12" - resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-1.1.12.tgz#ab9b454466e5a8cc3a187beaad580412a9c5b843" - integrity sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg== - dependencies: - balanced-match "^1.0.0" - concat-map "0.0.1" - -brace-expansion@^2.0.1: - version "2.0.2" - resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.0.2.tgz#54fc53237a613d854c7bd37463aad17df87214e7" - integrity sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ== - dependencies: - balanced-match "^1.0.0" - -braces@^3.0.3: - version "3.0.3" - resolved "https://registry.yarnpkg.com/braces/-/braces-3.0.3.tgz#490332f40919452272d55a8480adc0c441358789" - integrity sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA== - dependencies: - fill-range "^7.1.1" - -browserslist@^4.24.0: - version "4.28.1" - resolved "https://registry.yarnpkg.com/browserslist/-/browserslist-4.28.1.tgz#7f534594628c53c63101079e27e40de490456a95" - integrity sha512-ZC5Bd0LgJXgwGqUknZY/vkUQ04r8NXnJZ3yYi4vDmSiZmC/pdSN0NbNRPxZpbtO4uAfDUAFffO8IZoM3Gj8IkA== - dependencies: - baseline-browser-mapping "^2.9.0" - caniuse-lite "^1.0.30001759" - electron-to-chromium "^1.5.263" - node-releases "^2.0.27" - update-browserslist-db "^1.2.0" - -bs-logger@^0.2.6: - version "0.2.6" - resolved "https://registry.yarnpkg.com/bs-logger/-/bs-logger-0.2.6.tgz#eb7d365307a72cf974cc6cda76b68354ad336bd8" - integrity sha512-pd8DCoxmbgc7hyPKOvxtqNcjYoOsABPQdcCUjGp3d42VR2CX1ORhk2A87oqqu5R1kk+76nsxZupkmyd+MVtCog== - dependencies: - fast-json-stable-stringify "2.x" - -bser@2.1.1: - version "2.1.1" - resolved "https://registry.yarnpkg.com/bser/-/bser-2.1.1.tgz#e6787da20ece9d07998533cfd9de6f5c38f4bc05" - integrity sha512-gQxTNE/GAfIIrmHLUE3oJyp5FO6HRBfhjnw4/wMmA63ZGDJnWBmgY/lyQBpnDUkGmAhbSe39tx2d/iTOAfglwQ== - dependencies: - node-int64 "^0.4.0" - -buffer-from@^1.0.0: - version "1.1.2" - resolved "https://registry.yarnpkg.com/buffer-from/-/buffer-from-1.1.2.tgz#2b146a6fd72e80b4f55d255f35ed59a3a9a41bd5" - integrity sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ== - -bytes@^3.1.2, bytes@~3.1.2: - version "3.1.2" - resolved "https://registry.yarnpkg.com/bytes/-/bytes-3.1.2.tgz#8b0beeb98605adf1b128fa4386403c009e0221a5" - integrity sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg== - -call-bind-apply-helpers@^1.0.1, call-bind-apply-helpers@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz#4b5428c222be985d79c3d82657479dbe0b59b2d6" - integrity sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ== - dependencies: - es-errors "^1.3.0" - function-bind "^1.1.2" - -call-bound@^1.0.2: - version "1.0.4" - resolved "https://registry.yarnpkg.com/call-bound/-/call-bound-1.0.4.tgz#238de935d2a2a692928c538c7ccfa91067fd062a" - integrity sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg== - dependencies: - call-bind-apply-helpers "^1.0.2" - get-intrinsic "^1.3.0" - -callsites@^3.0.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/callsites/-/callsites-3.1.0.tgz#b3630abd8943432f54b3f0519238e33cd7df2f73" - integrity sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ== - -camelcase@^5.3.1: - version "5.3.1" - resolved "https://registry.yarnpkg.com/camelcase/-/camelcase-5.3.1.tgz#e3c9b31569e106811df242f715725a1f4c494320" - integrity sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg== - -camelcase@^6.2.0: - version "6.3.0" - resolved "https://registry.yarnpkg.com/camelcase/-/camelcase-6.3.0.tgz#5685b95eb209ac9c0c177467778c9c84df58ba9a" - integrity sha512-Gmy6FhYlCY7uOElZUSbxo2UCDH8owEk996gkbrpsgGtrJLM3J7jGxl9Ic7Qwwj4ivOE5AWZWRMecDdF7hqGjFA== - -caniuse-lite@^1.0.30001759: - version "1.0.30001764" - resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001764.tgz#03206c56469f236103b90f9ae10bcb8b9e1f6005" - integrity sha512-9JGuzl2M+vPL+pz70gtMF9sHdMFbY9FJaQBi186cHKH3pSzDvzoUJUPV6fqiKIMyXbud9ZLg4F3Yza1vJ1+93g== - -chalk@^4.0.0: - version "4.1.2" - resolved "https://registry.yarnpkg.com/chalk/-/chalk-4.1.2.tgz#aac4e2b7734a740867aeb16bf02aad556a1e7a01" - integrity sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA== - dependencies: - ansi-styles "^4.1.0" - supports-color "^7.1.0" - -char-regex@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/char-regex/-/char-regex-1.0.2.tgz#d744358226217f981ed58f479b1d6bcc29545dcf" - integrity sha512-kWWXztvZ5SBQV+eRgKFeh8q5sLuZY2+8WUIzlxWVTg+oGwY14qylx1KbKzHd8P6ZYkAg0xyIDU9JMHhyJMZ1jw== - -chardet@^0.7.0: - version "0.7.0" - resolved "https://registry.yarnpkg.com/chardet/-/chardet-0.7.0.tgz#90094849f0937f2eedc2425d0d28a9e5f0cbad9e" - integrity sha512-mT8iDcrh03qDGRRmoA2hmBJnxpllMR+0/0qlzjqZES6NdiWDcZkCNAk4rPFZ9Q85r27unkiNNg8ZOiwZXBHwcA== - -ci-info@^3.2.0: - version "3.9.0" - resolved "https://registry.yarnpkg.com/ci-info/-/ci-info-3.9.0.tgz#4279a62028a7b1f262f3473fc9605f5e218c59b4" - integrity sha512-NIxF55hv4nSqQswkAeiOi1r83xy8JldOFDTWiug55KBu9Jnblncd2U6ViHmYgHf01TPZS77NJBhBMKdWj9HQMQ== - -cjs-module-lexer@^1.0.0: - version "1.4.3" - resolved "https://registry.yarnpkg.com/cjs-module-lexer/-/cjs-module-lexer-1.4.3.tgz#0f79731eb8cfe1ec72acd4066efac9d61991b00d" - integrity sha512-9z8TZaGM1pfswYeXrUpzPrkx8UnWYdhJclsiYMm6x/w5+nN+8Tf/LnAgfLGQCm59qAOxU8WwHEq2vNwF6i4j+Q== - -clean-stack@^2.0.0: - version "2.2.0" - resolved "https://registry.yarnpkg.com/clean-stack/-/clean-stack-2.2.0.tgz#ee8472dbb129e727b31e8a10a427dee9dfe4008b" - integrity sha512-4diC9HaTE+KRAMWhDhrGOECgWZxoevMc5TlkObMqNSsVU62PYzXZ/SMTjzyGAFF1YusgxGcSWTEXBhp0CPwQ1A== - -cli-width@^4.1.0: - version "4.1.0" - resolved "https://registry.yarnpkg.com/cli-width/-/cli-width-4.1.0.tgz#42daac41d3c254ef38ad8ac037672130173691c5" - integrity sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ== - -cliui@^8.0.1: - version "8.0.1" - resolved "https://registry.yarnpkg.com/cliui/-/cliui-8.0.1.tgz#0c04b075db02cbfe60dc8e6cf2f5486b1a3608aa" - integrity sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ== - dependencies: - string-width "^4.2.0" - strip-ansi "^6.0.1" - wrap-ansi "^7.0.0" - -co@^4.6.0: - version "4.6.0" - resolved "https://registry.yarnpkg.com/co/-/co-4.6.0.tgz#6ea6bdf3d853ae54ccb8e47bfa0bf3f9031fb184" - integrity sha512-QVb0dM5HvG+uaxitm8wONl7jltx8dqhfU33DcqtOZcLSVIKSDDLDi7+0LbAKiyI8hD9u42m2YxXSkMGWThaecQ== - -code-block-writer@^12.0.0: - version "12.0.0" - resolved "https://registry.yarnpkg.com/code-block-writer/-/code-block-writer-12.0.0.tgz#4dd58946eb4234105aff7f0035977b2afdc2a770" - integrity sha512-q4dMFMlXtKR3XNBHyMHt/3pwYNA69EDk00lloMOaaUMKPUXBw6lpXtbu3MMVG6/uOihGnRDOlkyqsONEUj60+w== - -collect-v8-coverage@^1.0.0: - version "1.0.3" - resolved "https://registry.yarnpkg.com/collect-v8-coverage/-/collect-v8-coverage-1.0.3.tgz#cc1f01eb8d02298cbc9a437c74c70ab4e5210b80" - integrity sha512-1L5aqIkwPfiodaMgQunkF1zRhNqifHBmtbbbxcr6yVxxBnliw4TDOW6NxpO8DJLgJ16OT+Y4ztZqP6p/FtXnAw== - -color-convert@^2.0.1: - version "2.0.1" - resolved "https://registry.yarnpkg.com/color-convert/-/color-convert-2.0.1.tgz#72d3a68d598c9bdb3af2ad1e84f21d896abd4de3" - integrity sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ== - dependencies: - color-name "~1.1.4" - -color-name@~1.1.4: - version "1.1.4" - resolved "https://registry.yarnpkg.com/color-name/-/color-name-1.1.4.tgz#c2a09a87acbde69543de6f63fa3995c826c536a2" - integrity sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA== - -colorette@^2.0.7: - version "2.0.20" - resolved "https://registry.yarnpkg.com/colorette/-/colorette-2.0.20.tgz#9eb793e6833067f7235902fcd3b09917a000a95a" - integrity sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w== - -commander@^13.1.0: - version "13.1.0" - resolved "https://registry.yarnpkg.com/commander/-/commander-13.1.0.tgz#776167db68c78f38dcce1f9b8d7b8b9a488abf46" - integrity sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw== - -concat-map@0.0.1: - version "0.0.1" - resolved "https://registry.yarnpkg.com/concat-map/-/concat-map-0.0.1.tgz#d8a96bd77fd68df7793a73036a3ba0d5405d477b" - integrity sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg== - -content-disposition@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/content-disposition/-/content-disposition-1.0.1.tgz#a8b7bbeb2904befdfb6787e5c0c086959f605f9b" - integrity sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q== - -content-type@^1.0.5: - version "1.0.5" - resolved "https://registry.yarnpkg.com/content-type/-/content-type-1.0.5.tgz#8b773162656d1d1086784c8f23a54ce6d73d7918" - integrity sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA== - -convert-source-map@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/convert-source-map/-/convert-source-map-2.0.0.tgz#4b560f649fc4e918dd0ab75cf4961e8bc882d82a" - integrity sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg== - -cookie-parser@^1.4.6: - version "1.4.7" - resolved "https://registry.yarnpkg.com/cookie-parser/-/cookie-parser-1.4.7.tgz#e2125635dfd766888ffe90d60c286404fa0e7b26" - integrity sha512-nGUvgXnotP3BsjiLX2ypbQnWoGUPIIfHQNZkkC668ntrzGWEZVW70HDEB1qnNGMicPje6EttlIgzo51YSwNQGw== - dependencies: - cookie "0.7.2" - cookie-signature "1.0.6" - -cookie-signature@1.0.6: - version "1.0.6" - resolved "https://registry.yarnpkg.com/cookie-signature/-/cookie-signature-1.0.6.tgz#e303a882b342cc3ee8ca513a79999734dab3ae2c" - integrity sha512-QADzlaHc8icV8I7vbaJXJwod9HWYp8uCqf1xa4OfNu1T7JVxQIrUgOWtHdNDtPiywmFbiS12VjotIXLrKM3orQ== - -cookie-signature@^1.2.1: - version "1.2.2" - resolved "https://registry.yarnpkg.com/cookie-signature/-/cookie-signature-1.2.2.tgz#57c7fc3cc293acab9fec54d73e15690ebe4a1793" - integrity sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg== - -cookie@0.7.2, cookie@^0.7.1: - version "0.7.2" - resolved "https://registry.yarnpkg.com/cookie/-/cookie-0.7.2.tgz#556369c472a2ba910f2979891b526b3436237ed7" - integrity sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w== - -cors@^2.8.5: - version "2.8.5" - resolved "https://registry.yarnpkg.com/cors/-/cors-2.8.5.tgz#eac11da51592dd86b9f06f6e7ac293b3df875d29" - integrity sha512-KIHbLJqu73RGr/hnbrO9uBeixNGuvSQjul/jdFvS/KFSIH1hWVd1ng7zOHx+YrEfInLG7q4n6GHQ9cDtxv/P6g== - dependencies: - object-assign "^4" - vary "^1" - -create-jest@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/create-jest/-/create-jest-29.7.0.tgz#a355c5b3cb1e1af02ba177fe7afd7feee49a5320" - integrity sha512-Adz2bdH0Vq3F53KEMJOoftQFutWCukm6J24wbPWRO4k1kMY7gS7ds/uoJkNuV8wDCtWWnuwGcJwpWcih+zEW1Q== - dependencies: - "@jest/types" "^29.6.3" - chalk "^4.0.0" - exit "^0.1.2" - graceful-fs "^4.2.9" - jest-config "^29.7.0" - jest-util "^29.7.0" - prompts "^2.0.1" - -create-require@^1.1.0: - version "1.1.1" - resolved "https://registry.yarnpkg.com/create-require/-/create-require-1.1.1.tgz#c1d7e8f1e5f6cfc9ff65f9cd352d37348756c333" - integrity sha512-dcKFX3jn0MpIaXjisoRvexIJVEKzaq7z2rZKxf+MSr9TkdmHmsU4m2lcLojrj/FHl8mk5VxMmYA+ftRkP/3oKQ== - -cross-spawn@^7.0.3, cross-spawn@^7.0.5, cross-spawn@^7.0.6: - version "7.0.6" - resolved "https://registry.yarnpkg.com/cross-spawn/-/cross-spawn-7.0.6.tgz#8a58fe78f00dcd70c370451759dfbfaf03e8ee9f" - integrity sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA== - dependencies: - path-key "^3.1.0" - shebang-command "^2.0.0" - which "^2.0.1" - -dateformat@^4.6.3: - version "4.6.3" - resolved "https://registry.yarnpkg.com/dateformat/-/dateformat-4.6.3.tgz#556fa6497e5217fedb78821424f8a1c22fa3f4b5" - integrity sha512-2P0p0pFGzHS5EMnhdxQi7aJN+iMheud0UhG4dlE1DLAlvL8JHjJJTX/CSm4JXwV0Ka5nGk3zC5mcb5bUQUxxMA== - -debug@^4.1.0, debug@^4.1.1, debug@^4.3.1, debug@^4.3.2, debug@^4.3.4, debug@^4.3.7, debug@^4.4.0, debug@^4.4.3: - version "4.4.3" - resolved "https://registry.yarnpkg.com/debug/-/debug-4.4.3.tgz#c6ae432d9bd9662582fce08709b038c58e9e3d6a" - integrity sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA== - dependencies: - ms "^2.1.3" - -dedent@^1.0.0: - version "1.7.1" - resolved "https://registry.yarnpkg.com/dedent/-/dedent-1.7.1.tgz#364661eea3d73f3faba7089214420ec2f8f13e15" - integrity sha512-9JmrhGZpOlEgOLdQgSm0zxFaYoQon408V1v49aqTWuXENVlnCuY9JBZcXZiCsZQWDjTm5Qf/nIvAy77mXDAjEg== - -deep-is@^0.1.3: - version "0.1.4" - resolved "https://registry.yarnpkg.com/deep-is/-/deep-is-0.1.4.tgz#a6f2dce612fadd2ef1f519b73551f17e85199831" - integrity sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ== - -deepmerge@^4.2.2: - version "4.3.1" - resolved "https://registry.yarnpkg.com/deepmerge/-/deepmerge-4.3.1.tgz#44b5f2147cd3b00d4b56137685966f26fd25dd4a" - integrity sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A== - -depd@^2.0.0, depd@~2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/depd/-/depd-2.0.0.tgz#b696163cc757560d09cf22cc8fad1571b79e76df" - integrity sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw== - -detect-newline@^3.0.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/detect-newline/-/detect-newline-3.1.0.tgz#576f5dfc63ae1a192ff192d8ad3af6308991b651" - integrity sha512-TLz+x/vEXm/Y7P7wn1EJFNLxYpUD4TgMosxY6fAVJUnJMbupHBOncxyWUG9OpTaH9EBD7uFI5LfEgmMOc54DsA== - -diff-sequences@^29.6.3: - version "29.6.3" - resolved "https://registry.yarnpkg.com/diff-sequences/-/diff-sequences-29.6.3.tgz#4deaf894d11407c51efc8418012f9e70b84ea921" - integrity sha512-EjePK1srD3P08o2j4f0ExnylqRs5B9tJjcp9t1krH2qRi8CCdsYfwe9JgSLurFBWwq4uOlipzfk5fHNvwFKr8Q== - -diff@^4.0.1: - version "4.0.2" - resolved "https://registry.yarnpkg.com/diff/-/diff-4.0.2.tgz#60f3aecb89d5fae520c11aa19efc2bb982aade7d" - integrity sha512-58lmxKSA4BNyLz+HHMUzlOEpg09FV+ev6ZMe3vJihgdxzgcwZ8VoEEPmALCZG9LmqfVoNMMKpttIYTVG6uDY7A== - -dunder-proto@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/dunder-proto/-/dunder-proto-1.0.1.tgz#d7ae667e1dc83482f8b70fd0f6eefc50da30f58a" - integrity sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A== - dependencies: - call-bind-apply-helpers "^1.0.1" - es-errors "^1.3.0" - gopd "^1.2.0" - -ee-first@1.1.1: - version "1.1.1" - resolved "https://registry.yarnpkg.com/ee-first/-/ee-first-1.1.1.tgz#590c61156b0ae2f4f0255732a158b266bc56b21d" - integrity sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow== - -electron-to-chromium@^1.5.263: - version "1.5.267" - resolved "https://registry.yarnpkg.com/electron-to-chromium/-/electron-to-chromium-1.5.267.tgz#5d84f2df8cdb6bfe7e873706bb21bd4bfb574dc7" - integrity sha512-0Drusm6MVRXSOJpGbaSVgcQsuB4hEkMpHXaVstcPmhu5LIedxs1xNK/nIxmQIU/RPC0+1/o0AVZfBTkTNJOdUw== - -emittery@^0.13.1: - version "0.13.1" - resolved "https://registry.yarnpkg.com/emittery/-/emittery-0.13.1.tgz#c04b8c3457490e0847ae51fced3af52d338e3dad" - integrity sha512-DeWwawk6r5yR9jFgnDKYt4sLS0LmHJJi3ZOnb5/JdbYwj3nW+FxQnHIjhBKz8YLC7oRNPVM9NQ47I3CVx34eqQ== - -emoji-regex@^8.0.0: - version "8.0.0" - resolved "https://registry.yarnpkg.com/emoji-regex/-/emoji-regex-8.0.0.tgz#e818fd69ce5ccfcb404594f842963bf53164cc37" - integrity sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A== - -encodeurl@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/encodeurl/-/encodeurl-2.0.0.tgz#7b8ea898077d7e409d3ac45474ea38eaf0857a58" - integrity sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg== - -end-of-stream@^1.1.0: - version "1.4.5" - resolved "https://registry.yarnpkg.com/end-of-stream/-/end-of-stream-1.4.5.tgz#7344d711dea40e0b74abc2ed49778743ccedb08c" - integrity sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg== - dependencies: - once "^1.4.0" - -error-ex@^1.3.1: - version "1.3.4" - resolved "https://registry.yarnpkg.com/error-ex/-/error-ex-1.3.4.tgz#b3a8d8bb6f92eecc1629e3e27d3c8607a8a32414" - integrity sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ== - dependencies: - is-arrayish "^0.2.1" - -es-define-property@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/es-define-property/-/es-define-property-1.0.1.tgz#983eb2f9a6724e9303f61addf011c72e09e0b0fa" - integrity sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g== - -es-errors@^1.3.0: - version "1.3.0" - resolved "https://registry.yarnpkg.com/es-errors/-/es-errors-1.3.0.tgz#05f75a25dab98e4fb1dcd5e1472c0546d5057c8f" - integrity sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw== - -es-object-atoms@^1.0.0, es-object-atoms@^1.1.1: - version "1.1.1" - resolved "https://registry.yarnpkg.com/es-object-atoms/-/es-object-atoms-1.1.1.tgz#1c4f2c4837327597ce69d2ca190a7fdd172338c1" - integrity sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA== - dependencies: - es-errors "^1.3.0" - -escalade@^3.1.1, escalade@^3.2.0: - version "3.2.0" - resolved "https://registry.yarnpkg.com/escalade/-/escalade-3.2.0.tgz#011a3f69856ba189dffa7dc8fcce99d2a87903e5" - integrity sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA== - -escape-html@^1.0.3: - version "1.0.3" - resolved "https://registry.yarnpkg.com/escape-html/-/escape-html-1.0.3.tgz#0258eae4d3d0c0974de1c169188ef0051d1d1988" - integrity sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow== - -escape-string-regexp@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz#a30304e99daa32e23b2fd20f51babd07cffca344" - integrity sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w== - -escape-string-regexp@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz#14ba83a5d373e3d311e5afca29cf5bfad965bf34" - integrity sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA== - -eslint-plugin-prettier@^5.4.1: - version "5.5.5" - resolved "https://registry.yarnpkg.com/eslint-plugin-prettier/-/eslint-plugin-prettier-5.5.5.tgz#9eae11593faa108859c26f9a9c367d619a0769c0" - integrity sha512-hscXkbqUZ2sPithAuLm5MXL+Wph+U7wHngPBv9OMWwlP8iaflyxpjTYZkmdgB4/vPIhemRlBEoLrH7UC1n7aUw== - dependencies: - prettier-linter-helpers "^1.0.1" - synckit "^0.11.12" - -eslint-plugin-unused-imports@^4.1.4: - version "4.4.1" - resolved "https://registry.yarnpkg.com/eslint-plugin-unused-imports/-/eslint-plugin-unused-imports-4.4.1.tgz#a831f0a2937d7631eba30cb87091ab7d3a5da0e1" - integrity sha512-oZGYUz1X3sRMGUB+0cZyK2VcvRX5lm/vB56PgNNcU+7ficUCKm66oZWKUubXWnOuPjQ8PvmXtCViXBMONPe7tQ== - -eslint-scope@^8.4.0: - version "8.4.0" - resolved "https://registry.yarnpkg.com/eslint-scope/-/eslint-scope-8.4.0.tgz#88e646a207fad61436ffa39eb505147200655c82" - integrity sha512-sNXOfKCn74rt8RICKMvJS7XKV/Xk9kA7DyJr8mJik3S7Cwgy3qlkkmyS2uQB3jiJg6VNdZd/pDBJu0nvG2NlTg== - dependencies: - esrecurse "^4.3.0" - estraverse "^5.2.0" - -eslint-visitor-keys@^3.4.3: - version "3.4.3" - resolved "https://registry.yarnpkg.com/eslint-visitor-keys/-/eslint-visitor-keys-3.4.3.tgz#0cd72fe8550e3c2eae156a96a4dddcd1c8ac5800" - integrity sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag== - -eslint-visitor-keys@^4.2.0, eslint-visitor-keys@^4.2.1: - version "4.2.1" - resolved "https://registry.yarnpkg.com/eslint-visitor-keys/-/eslint-visitor-keys-4.2.1.tgz#4cfea60fe7dd0ad8e816e1ed026c1d5251b512c1" - integrity sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ== - -eslint@^9.39.1: - version "9.39.4" - resolved "https://registry.yarnpkg.com/eslint/-/eslint-9.39.4.tgz#855da1b2e2ad66dc5991195f35e262bcec8117b5" - integrity sha512-XoMjdBOwe/esVgEvLmNsD3IRHkm7fbKIUGvrleloJXUZgDHig2IPWNniv+GwjyJXzuNqVjlr5+4yVUZjycJwfQ== - dependencies: - "@eslint-community/eslint-utils" "^4.8.0" - "@eslint-community/regexpp" "^4.12.1" - "@eslint/config-array" "^0.21.2" - "@eslint/config-helpers" "^0.4.2" - "@eslint/core" "^0.17.0" - "@eslint/eslintrc" "^3.3.5" - "@eslint/js" "9.39.4" - "@eslint/plugin-kit" "^0.4.1" - "@humanfs/node" "^0.16.6" - "@humanwhocodes/module-importer" "^1.0.1" - "@humanwhocodes/retry" "^0.4.2" - "@types/estree" "^1.0.6" - ajv "^6.14.0" - chalk "^4.0.0" - cross-spawn "^7.0.6" - debug "^4.3.2" - escape-string-regexp "^4.0.0" - eslint-scope "^8.4.0" - eslint-visitor-keys "^4.2.1" - espree "^10.4.0" - esquery "^1.5.0" - esutils "^2.0.2" - fast-deep-equal "^3.1.3" - file-entry-cache "^8.0.0" - find-up "^5.0.0" - glob-parent "^6.0.2" - ignore "^5.2.0" - imurmurhash "^0.1.4" - is-glob "^4.0.0" - json-stable-stringify-without-jsonify "^1.0.1" - lodash.merge "^4.6.2" - minimatch "^3.1.5" - natural-compare "^1.4.0" - optionator "^0.9.3" - -espree@^10.0.1, espree@^10.4.0: - version "10.4.0" - resolved "https://registry.yarnpkg.com/espree/-/espree-10.4.0.tgz#d54f4949d4629005a1fa168d937c3ff1f7e2a837" - integrity sha512-j6PAQ2uUr79PZhBjP5C5fhl8e39FmRnOjsD5lGnWrFU8i2G776tBK7+nP8KuQUTTyAZUwfQqXAgrVH5MbH9CYQ== - dependencies: - acorn "^8.15.0" - acorn-jsx "^5.3.2" - eslint-visitor-keys "^4.2.1" - -esprima@^4.0.0: - version "4.0.1" - resolved "https://registry.yarnpkg.com/esprima/-/esprima-4.0.1.tgz#13b04cdb3e6c5d19df91ab6987a8695619b0aa71" - integrity sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A== - -esquery@^1.5.0: - version "1.7.0" - resolved "https://registry.yarnpkg.com/esquery/-/esquery-1.7.0.tgz#08d048f261f0ddedb5bae95f46809463d9c9496d" - integrity sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g== - dependencies: - estraverse "^5.1.0" - -esrecurse@^4.3.0: - version "4.3.0" - resolved "https://registry.yarnpkg.com/esrecurse/-/esrecurse-4.3.0.tgz#7ad7964d679abb28bee72cec63758b1c5d2c9921" - integrity sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag== - dependencies: - estraverse "^5.2.0" - -estraverse@^5.1.0, estraverse@^5.2.0: - version "5.3.0" - resolved "https://registry.yarnpkg.com/estraverse/-/estraverse-5.3.0.tgz#2eea5290702f26ab8fe5370370ff86c965d21123" - integrity sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA== - -esutils@^2.0.2: - version "2.0.3" - resolved "https://registry.yarnpkg.com/esutils/-/esutils-2.0.3.tgz#74d2eb4de0b8da1293711910d50775b9b710ef64" - integrity sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g== - -etag@^1.8.1: - version "1.8.1" - resolved "https://registry.yarnpkg.com/etag/-/etag-1.8.1.tgz#41ae2eeb65efa62268aebfea83ac7d79299b0887" - integrity sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg== - -eventsource-parser@^3.0.0, eventsource-parser@^3.0.1: - version "3.0.6" - resolved "https://registry.yarnpkg.com/eventsource-parser/-/eventsource-parser-3.0.6.tgz#292e165e34cacbc936c3c92719ef326d4aeb4e90" - integrity sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg== - -eventsource@^3.0.2: - version "3.0.7" - resolved "https://registry.yarnpkg.com/eventsource/-/eventsource-3.0.7.tgz#1157622e2f5377bb6aef2114372728ba0c156989" - integrity sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA== - dependencies: - eventsource-parser "^3.0.1" - -execa@^5.0.0: - version "5.1.1" - resolved "https://registry.yarnpkg.com/execa/-/execa-5.1.1.tgz#f80ad9cbf4298f7bd1d4c9555c21e93741c411dd" - integrity sha512-8uSpZZocAZRBAPIEINJj3Lo9HyGitllczc27Eh5YYojjMFMn8yHMDMaUHE2Jqfq05D/wucwI4JGURyXt1vchyg== - dependencies: - cross-spawn "^7.0.3" - get-stream "^6.0.0" - human-signals "^2.1.0" - is-stream "^2.0.0" - merge-stream "^2.0.0" - npm-run-path "^4.0.1" - onetime "^5.1.2" - signal-exit "^3.0.3" - strip-final-newline "^2.0.0" - -exit@^0.1.2: - version "0.1.2" - resolved "https://registry.yarnpkg.com/exit/-/exit-0.1.2.tgz#0632638f8d877cc82107d30a0fff1a17cba1cd0c" - integrity sha512-Zk/eNKV2zbjpKzrsQ+n1G6poVbErQxJ0LBOJXaKZ1EViLzH+hrLu9cdXI4zw9dBQJslwBEpbQ2P1oS7nDxs6jQ== - -expect@^29.0.0, expect@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/expect/-/expect-29.7.0.tgz#578874590dcb3214514084c08115d8aee61e11bc" - integrity sha512-2Zks0hf1VLFYI1kbh0I5jP3KHHyCHpkfyHBzsSXRFgl/Bg9mWYfMW8oD+PdMPlEwy5HNsR9JutYy6pMeOh61nw== - dependencies: - "@jest/expect-utils" "^29.7.0" - jest-get-type "^29.6.3" - jest-matcher-utils "^29.7.0" - jest-message-util "^29.7.0" - jest-util "^29.7.0" - -express-rate-limit@^8.2.1: - version "8.3.1" - resolved "https://registry.yarnpkg.com/express-rate-limit/-/express-rate-limit-8.3.1.tgz#0aaba098eadd40f6737f30a98e6b16fa1a29edfb" - integrity sha512-D1dKN+cmyPWuvB+G2SREQDzPY1agpBIcTa9sJxOPMCNeH3gwzhqJRDWCXW3gg0y//+LQ/8j52JbMROWyrKdMdw== - dependencies: - ip-address "10.1.0" - -express@^5.1.0, express@^5.2.1: - version "5.2.1" - resolved "https://registry.yarnpkg.com/express/-/express-5.2.1.tgz#8f21d15b6d327f92b4794ecf8cb08a72f956ac04" - integrity sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw== - dependencies: - accepts "^2.0.0" - body-parser "^2.2.1" - content-disposition "^1.0.0" - content-type "^1.0.5" - cookie "^0.7.1" - cookie-signature "^1.2.1" - debug "^4.4.0" - depd "^2.0.0" - encodeurl "^2.0.0" - escape-html "^1.0.3" - etag "^1.8.1" - finalhandler "^2.1.0" - fresh "^2.0.0" - http-errors "^2.0.0" - merge-descriptors "^2.0.0" - mime-types "^3.0.0" - on-finished "^2.4.1" - once "^1.4.0" - parseurl "^1.3.3" - proxy-addr "^2.0.7" - qs "^6.14.0" - range-parser "^1.2.1" - router "^2.2.0" - send "^1.1.0" - serve-static "^2.2.0" - statuses "^2.0.1" - type-is "^2.0.1" - vary "^1.1.2" - -external-editor@^3.1.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/external-editor/-/external-editor-3.1.0.tgz#cb03f740befae03ea4d283caed2741a83f335495" - integrity sha512-hMQ4CX1p1izmuLYyZqLMO/qGNw10wSv9QDCPfzXfyFrOaCSSoRfqE1Kf1s5an66J5JZC62NewG+mK49jOCtQew== - dependencies: - chardet "^0.7.0" - iconv-lite "^0.4.24" - tmp "^0.0.33" - -fast-copy@^4.0.0: - version "4.0.2" - resolved "https://registry.yarnpkg.com/fast-copy/-/fast-copy-4.0.2.tgz#57f14115e1edbec274f69090072a480aa29cbedd" - integrity sha512-ybA6PDXIXOXivLJK/z9e+Otk7ve13I4ckBvGO5I2RRmBU1gMHLVDJYEuJYhGwez7YNlYji2M2DvVU+a9mSFDlw== - -fast-deep-equal@^3.1.1, fast-deep-equal@^3.1.3: - version "3.1.3" - resolved "https://registry.yarnpkg.com/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz#3a7d56b559d6cbc3eb512325244e619a65c6c525" - integrity sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q== - -fast-diff@^1.1.2: - version "1.3.0" - resolved "https://registry.yarnpkg.com/fast-diff/-/fast-diff-1.3.0.tgz#ece407fa550a64d638536cd727e129c61616e0f0" - integrity sha512-VxPP4NqbUjj6MaAOafWeUn2cXWLcCtljklUtZf0Ind4XQ+QPtmA0b18zZy0jIQx+ExRVCR/ZQpBmik5lXshNsw== - -fast-glob@^3.2.12, fast-glob@^3.3.2: - version "3.3.3" - resolved "https://registry.yarnpkg.com/fast-glob/-/fast-glob-3.3.3.tgz#d06d585ce8dba90a16b0505c543c3ccfb3aeb818" - integrity sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg== - dependencies: - "@nodelib/fs.stat" "^2.0.2" - "@nodelib/fs.walk" "^1.2.3" - glob-parent "^5.1.2" - merge2 "^1.3.0" - micromatch "^4.0.8" - -fast-json-stable-stringify@2.x, fast-json-stable-stringify@^2.0.0, fast-json-stable-stringify@^2.1.0: - version "2.1.0" - resolved "https://registry.yarnpkg.com/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz#874bf69c6f404c2b5d99c481341399fd55892633" - integrity sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw== - -fast-levenshtein@^2.0.6: - version "2.0.6" - resolved "https://registry.yarnpkg.com/fast-levenshtein/-/fast-levenshtein-2.0.6.tgz#3d8a5c66883a16a30ca8643e851f19baa7797917" - integrity sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw== - -fast-safe-stringify@^2.1.1: - version "2.1.1" - resolved "https://registry.yarnpkg.com/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz#c406a83b6e70d9e35ce3b30a81141df30aeba884" - integrity sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA== - -fast-uri@^3.0.1: - version "3.1.0" - resolved "https://registry.yarnpkg.com/fast-uri/-/fast-uri-3.1.0.tgz#66eecff6c764c0df9b762e62ca7edcfb53b4edfa" - integrity sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA== - -fastq@^1.6.0: - version "1.20.1" - resolved "https://registry.yarnpkg.com/fastq/-/fastq-1.20.1.tgz#ca750a10dc925bc8b18839fd203e3ef4b3ced675" - integrity sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw== - dependencies: - reusify "^1.0.4" - -fb-watchman@^2.0.0: - version "2.0.2" - resolved "https://registry.yarnpkg.com/fb-watchman/-/fb-watchman-2.0.2.tgz#e9524ee6b5c77e9e5001af0f85f3adbb8623255c" - integrity sha512-p5161BqbuCaSnB8jIbzQHOlpgsPmK5rJVDfDKO91Axs5NC1uu3HRQm6wt9cd9/+GtQQIO53JdGXXoyDpTAsgYA== - dependencies: - bser "2.1.1" - -fflate@^0.8.2: - version "0.8.2" - resolved "https://registry.yarnpkg.com/fflate/-/fflate-0.8.2.tgz#fc8631f5347812ad6028bbe4a2308b2792aa1dea" - integrity sha512-cPJU47OaAoCbg0pBvzsgpTPhmhqI5eJjh/JIu8tPj5q+T7iLvW/JAYUqmE7KOB4R1ZyEhzBaIQpQpardBF5z8A== - -file-entry-cache@^8.0.0: - version "8.0.0" - resolved "https://registry.yarnpkg.com/file-entry-cache/-/file-entry-cache-8.0.0.tgz#7787bddcf1131bffb92636c69457bbc0edd6d81f" - integrity sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ== - dependencies: - flat-cache "^4.0.0" - -fill-range@^7.1.1: - version "7.1.1" - resolved "https://registry.yarnpkg.com/fill-range/-/fill-range-7.1.1.tgz#44265d3cac07e3ea7dc247516380643754a05292" - integrity sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg== - dependencies: - to-regex-range "^5.0.1" - -finalhandler@^2.1.0: - version "2.1.1" - resolved "https://registry.yarnpkg.com/finalhandler/-/finalhandler-2.1.1.tgz#a2c517a6559852bcdb06d1f8bd7f51b68fad8099" - integrity sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA== - dependencies: - debug "^4.4.0" - encodeurl "^2.0.0" - escape-html "^1.0.3" - on-finished "^2.4.1" - parseurl "^1.3.3" - statuses "^2.0.1" - -find-up@^4.0.0, find-up@^4.1.0: - version "4.1.0" - resolved "https://registry.yarnpkg.com/find-up/-/find-up-4.1.0.tgz#97afe7d6cdc0bc5928584b7c8d7b16e8a9aa5d19" - integrity sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw== - dependencies: - locate-path "^5.0.0" - path-exists "^4.0.0" - -find-up@^5.0.0: - version "5.0.0" - resolved "https://registry.yarnpkg.com/find-up/-/find-up-5.0.0.tgz#4c92819ecb7083561e4f4a240a86be5198f536fc" - integrity sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng== - dependencies: - locate-path "^6.0.0" - path-exists "^4.0.0" - -flat-cache@^4.0.0: - version "4.0.1" - resolved "https://registry.yarnpkg.com/flat-cache/-/flat-cache-4.0.1.tgz#0ece39fcb14ee012f4b0410bd33dd9c1f011127c" - integrity sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw== - dependencies: - flatted "^3.2.9" - keyv "^4.5.4" - -flatted@^3.2.9: - version "3.3.3" - resolved "https://registry.yarnpkg.com/flatted/-/flatted-3.3.3.tgz#67c8fad95454a7c7abebf74bb78ee74a44023358" - integrity sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg== - -flora-colossus@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/flora-colossus/-/flora-colossus-2.0.0.tgz#af1e85db0a8256ef05f3fb531c1235236c97220a" - integrity sha512-dz4HxH6pOvbUzZpZ/yXhafjbR2I8cenK5xL0KtBFb7U2ADsR+OwXifnxZjij/pZWF775uSCMzWVd+jDik2H2IA== - dependencies: - debug "^4.3.4" - fs-extra "^10.1.0" - -forwarded@0.2.0: - version "0.2.0" - resolved "https://registry.yarnpkg.com/forwarded/-/forwarded-0.2.0.tgz#2269936428aad4c15c7ebe9779a84bf0b2a81811" - integrity sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow== - -fresh@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/fresh/-/fresh-2.0.0.tgz#8dd7df6a1b3a1b3a5cf186c05a5dd267622635a4" - integrity sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A== - -fs-extra@^10.1.0: - version "10.1.0" - resolved "https://registry.yarnpkg.com/fs-extra/-/fs-extra-10.1.0.tgz#02873cfbc4084dde127eaa5f9905eef2325d1abf" - integrity sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ== - dependencies: - graceful-fs "^4.2.0" - jsonfile "^6.0.1" - universalify "^2.0.0" - -fs.realpath@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/fs.realpath/-/fs.realpath-1.0.0.tgz#1504ad2523158caa40db4a2787cb01411994ea4f" - integrity sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw== - -fsevents@^2.3.2: - version "2.3.3" - resolved "https://registry.yarnpkg.com/fsevents/-/fsevents-2.3.3.tgz#cac6407785d03675a2a5e1a5305c697b347d90d6" - integrity sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw== - -function-bind@^1.1.2: - version "1.1.2" - resolved "https://registry.yarnpkg.com/function-bind/-/function-bind-1.1.2.tgz#2c02d864d97f3ea6c8830c464cbd11ab6eab7a1c" - integrity sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA== - -fuse.js@^7.1.0: - version "7.1.0" - resolved "https://registry.yarnpkg.com/fuse.js/-/fuse.js-7.1.0.tgz#306228b4befeee11e05b027087c2744158527d09" - integrity sha512-trLf4SzuuUxfusZADLINj+dE8clK1frKdmqiJNb1Es75fmI5oY6X2mxLVUciLLjxqw/xr72Dhy+lER6dGd02FQ== - -galactus@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/galactus/-/galactus-1.0.0.tgz#c2615182afa0c6d0859b92e56ae36d052827db7e" - integrity sha512-R1fam6D4CyKQGNlvJne4dkNF+PvUUl7TAJInvTGa9fti9qAv95quQz29GXapA4d8Ec266mJJxFVh82M4GIIGDQ== - dependencies: - debug "^4.3.4" - flora-colossus "^2.0.0" - fs-extra "^10.1.0" - -gensync@^1.0.0-beta.2: - version "1.0.0-beta.2" - resolved "https://registry.yarnpkg.com/gensync/-/gensync-1.0.0-beta.2.tgz#32a6ee76c3d7f52d46b2b1ae5d93fea8580a25e0" - integrity sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg== - -get-caller-file@^2.0.5: - version "2.0.5" - resolved "https://registry.yarnpkg.com/get-caller-file/-/get-caller-file-2.0.5.tgz#4f94412a82db32f36e3b0b9741f8a97feb031f7e" - integrity sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg== - -get-intrinsic@^1.2.5, get-intrinsic@^1.3.0: - version "1.3.0" - resolved "https://registry.yarnpkg.com/get-intrinsic/-/get-intrinsic-1.3.0.tgz#743f0e3b6964a93a5491ed1bffaae054d7f98d01" - integrity sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ== - dependencies: - call-bind-apply-helpers "^1.0.2" - es-define-property "^1.0.1" - es-errors "^1.3.0" - es-object-atoms "^1.1.1" - function-bind "^1.1.2" - get-proto "^1.0.1" - gopd "^1.2.0" - has-symbols "^1.1.0" - hasown "^2.0.2" - math-intrinsics "^1.1.0" - -get-package-type@^0.1.0: - version "0.1.0" - resolved "https://registry.yarnpkg.com/get-package-type/-/get-package-type-0.1.0.tgz#8de2d803cff44df3bc6c456e6668b36c3926e11a" - integrity sha512-pjzuKtY64GYfWizNAJ0fr9VqttZkNiK2iS430LtIHzjBEr6bX8Am2zm4sW4Ro5wjWW5cAlRL1qAMTcXbjNAO2Q== - -get-proto@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/get-proto/-/get-proto-1.0.1.tgz#150b3f2743869ef3e851ec0c49d15b1d14d00ee1" - integrity sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g== - dependencies: - dunder-proto "^1.0.1" - es-object-atoms "^1.0.0" - -get-stdin@^8.0.0: - version "8.0.0" - resolved "https://registry.yarnpkg.com/get-stdin/-/get-stdin-8.0.0.tgz#cbad6a73feb75f6eeb22ba9e01f89aa28aa97a53" - integrity sha512-sY22aA6xchAzprjyqmSEQv4UbAAzRN0L2dQB0NlN5acTTK9Don6nhoc3eAbUnpZiCANAMfd/+40kVdKfFygohg== - -get-stream@^6.0.0: - version "6.0.1" - resolved "https://registry.yarnpkg.com/get-stream/-/get-stream-6.0.1.tgz#a262d8eef67aced57c2852ad6167526a43cbf7b7" - integrity sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg== - -glob-parent@^5.1.2: - version "5.1.2" - resolved "https://registry.yarnpkg.com/glob-parent/-/glob-parent-5.1.2.tgz#869832c58034fe68a4093c17dc15e8340d8401c4" - integrity sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow== - dependencies: - is-glob "^4.0.1" - -glob-parent@^6.0.2: - version "6.0.2" - resolved "https://registry.yarnpkg.com/glob-parent/-/glob-parent-6.0.2.tgz#6d237d99083950c79290f24c7642a3de9a28f9e3" - integrity sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A== - dependencies: - is-glob "^4.0.3" - -glob@^7.1.3, glob@^7.1.4: - version "7.2.3" - resolved "https://registry.yarnpkg.com/glob/-/glob-7.2.3.tgz#b8df0fb802bbfa8e89bd1d938b4e16578ed44f2b" - integrity sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q== - dependencies: - fs.realpath "^1.0.0" - inflight "^1.0.4" - inherits "2" - minimatch "^3.1.1" - once "^1.3.0" - path-is-absolute "^1.0.0" - -globals@^14.0.0: - version "14.0.0" - resolved "https://registry.yarnpkg.com/globals/-/globals-14.0.0.tgz#898d7413c29babcf6bafe56fcadded858ada724e" - integrity sha512-oahGvuMGQlPw/ivIYBjVSrWAfWLBeku5tpPE2fOPLi+WHffIWbuh2tCjhyQhTBPMf5E9jDEH4FOmTYgYwbKwtQ== - -gopd@^1.2.0: - version "1.2.0" - resolved "https://registry.yarnpkg.com/gopd/-/gopd-1.2.0.tgz#89f56b8217bdbc8802bd299df6d7f1081d7e51a1" - integrity sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg== - -graceful-fs@^4.1.6, graceful-fs@^4.2.0, graceful-fs@^4.2.9: - version "4.2.11" - resolved "https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-4.2.11.tgz#4183e4e8bf08bb6e05bbb2f7d2e0c8f712ca40e3" - integrity sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ== - -graphemer@^1.4.0: - version "1.4.0" - resolved "https://registry.yarnpkg.com/graphemer/-/graphemer-1.4.0.tgz#fb2f1d55e0e3a1849aeffc90c4fa0dd53a0e66c6" - integrity sha512-EtKwoO6kxCL9WO5xipiHTZlSzBm7WLT627TqC/uVRd0HKmq8NXyebnNYxDoBi7wt8eTWrUrKXCOVaFq9x1kgag== - -handlebars@^4.7.8: - version "4.7.8" - resolved "https://registry.yarnpkg.com/handlebars/-/handlebars-4.7.8.tgz#41c42c18b1be2365439188c77c6afae71c0cd9e9" - integrity sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ== - dependencies: - minimist "^1.2.5" - neo-async "^2.6.2" - source-map "^0.6.1" - wordwrap "^1.0.0" - optionalDependencies: - uglify-js "^3.1.4" - -has-flag@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/has-flag/-/has-flag-4.0.0.tgz#944771fd9c81c81265c4d6941860da06bb59479b" - integrity sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ== - -has-symbols@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/has-symbols/-/has-symbols-1.1.0.tgz#fc9c6a783a084951d0b971fe1018de813707a338" - integrity sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ== - -hasown@^2.0.2: - version "2.0.2" - resolved "https://registry.yarnpkg.com/hasown/-/hasown-2.0.2.tgz#003eaf91be7adc372e84ec59dc37252cedb80003" - integrity sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ== - dependencies: - function-bind "^1.1.2" - -help-me@^5.0.0: - version "5.0.0" - resolved "https://registry.yarnpkg.com/help-me/-/help-me-5.0.0.tgz#b1ebe63b967b74060027c2ac61f9be12d354a6f6" - integrity sha512-7xgomUX6ADmcYzFik0HzAxh/73YlKR9bmFzf51CZwR+b6YtzU2m0u49hQCqV6SvlqIqsaxovfwdvbnsw3b/zpg== - -hono@^4.11.4, hono@^4.12.4: - version "4.12.7" - resolved "https://registry.yarnpkg.com/hono/-/hono-4.12.7.tgz#ca000956e965c2b3d791e43540498e616d6c6442" - integrity sha512-jq9l1DM0zVIvsm3lv9Nw9nlJnMNPOcAtsbsgiUhWcFzPE99Gvo6yRTlszSLLYacMeQ6quHD6hMfId8crVHvexw== - -html-escaper@^2.0.0: - version "2.0.2" - resolved "https://registry.yarnpkg.com/html-escaper/-/html-escaper-2.0.2.tgz#dfd60027da36a36dfcbe236262c00a5822681453" - integrity sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg== - -http-errors@^2.0.0, http-errors@^2.0.1, http-errors@~2.0.1: - version "2.0.1" - resolved "https://registry.yarnpkg.com/http-errors/-/http-errors-2.0.1.tgz#36d2f65bc909c8790018dd36fb4d93da6caae06b" - integrity sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ== - dependencies: - depd "~2.0.0" - inherits "~2.0.4" - setprototypeof "~1.2.0" - statuses "~2.0.2" - toidentifier "~1.0.1" - -human-signals@^2.1.0: - version "2.1.0" - resolved "https://registry.yarnpkg.com/human-signals/-/human-signals-2.1.0.tgz#dc91fcba42e4d06e4abaed33b3e7a3c02f514ea0" - integrity sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw== - -iconv-lite@^0.4.24: - version "0.4.24" - resolved "https://registry.yarnpkg.com/iconv-lite/-/iconv-lite-0.4.24.tgz#2022b4b25fbddc21d2f524974a474aafe733908b" - integrity sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA== - dependencies: - safer-buffer ">= 2.1.2 < 3" - -iconv-lite@^0.7.0, iconv-lite@~0.7.0: - version "0.7.2" - resolved "https://registry.yarnpkg.com/iconv-lite/-/iconv-lite-0.7.2.tgz#d0bdeac3f12b4835b7359c2ad89c422a4d1cc72e" - integrity sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw== - dependencies: - safer-buffer ">= 2.1.2 < 3.0.0" - -ignore@^5.2.0, ignore@^5.3.1: - version "5.3.2" - resolved "https://registry.yarnpkg.com/ignore/-/ignore-5.3.2.tgz#3cd40e729f3643fd87cb04e50bf0eb722bc596f5" - integrity sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g== - -ignore@^7.0.5: - version "7.0.5" - resolved "https://registry.yarnpkg.com/ignore/-/ignore-7.0.5.tgz#4cb5f6cd7d4c7ab0365738c7aea888baa6d7efd9" - integrity sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg== - -import-fresh@^3.2.1: - version "3.3.1" - resolved "https://registry.yarnpkg.com/import-fresh/-/import-fresh-3.3.1.tgz#9cecb56503c0ada1f2741dbbd6546e4b13b57ccf" - integrity sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ== - dependencies: - parent-module "^1.0.0" - resolve-from "^4.0.0" - -import-local@^3.0.2: - version "3.2.0" - resolved "https://registry.yarnpkg.com/import-local/-/import-local-3.2.0.tgz#c3d5c745798c02a6f8b897726aba5100186ee260" - integrity sha512-2SPlun1JUPWoM6t3F0dw0FkCF/jWY8kttcY4f599GLTSjh2OCuuhdTkJQsEcZzBqbXZGKMK2OqW1oZsjtf/gQA== - dependencies: - pkg-dir "^4.2.0" - resolve-cwd "^3.0.0" - -imurmurhash@^0.1.4: - version "0.1.4" - resolved "https://registry.yarnpkg.com/imurmurhash/-/imurmurhash-0.1.4.tgz#9218b9b2b928a238b13dc4fb6b6d576f231453ea" - integrity sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA== - -indent-string@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/indent-string/-/indent-string-4.0.0.tgz#624f8f4497d619b2d9768531d58f4122854d7251" - integrity sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg== - -inflight@^1.0.4: - version "1.0.6" - resolved "https://registry.yarnpkg.com/inflight/-/inflight-1.0.6.tgz#49bd6331d7d02d0c09bc910a1075ba8165b56df9" - integrity sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA== - dependencies: - once "^1.3.0" - wrappy "1" - -inherits@2, inherits@^2.0.3, inherits@~2.0.4: - version "2.0.4" - resolved "https://registry.yarnpkg.com/inherits/-/inherits-2.0.4.tgz#0fa2c64f932917c3433a0ded55363aae37416b7c" - integrity sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ== - -ip-address@10.1.0: - version "10.1.0" - resolved "https://registry.yarnpkg.com/ip-address/-/ip-address-10.1.0.tgz#d8dcffb34d0e02eb241427444a6e23f5b0595aa4" - integrity sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q== - -ipaddr.js@1.9.1: - version "1.9.1" - resolved "https://registry.yarnpkg.com/ipaddr.js/-/ipaddr.js-1.9.1.tgz#bff38543eeb8984825079ff3a2a8e6cbd46781b3" - integrity sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g== - -is-arrayish@^0.2.1: - version "0.2.1" - resolved "https://registry.yarnpkg.com/is-arrayish/-/is-arrayish-0.2.1.tgz#77c99840527aa8ecb1a8ba697b80645a7a926a9d" - integrity sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg== - -is-core-module@^2.16.1: - version "2.16.1" - resolved "https://registry.yarnpkg.com/is-core-module/-/is-core-module-2.16.1.tgz#2a98801a849f43e2add644fbb6bc6229b19a4ef4" - integrity sha512-UfoeMA6fIJ8wTYFEUjelnaGI67v6+N7qXJEvQuIGa99l4xsCruSYOVSQ0uPANn4dAzm8lkYPaKLrrijLq7x23w== - dependencies: - hasown "^2.0.2" - -is-extglob@^2.1.1: - version "2.1.1" - resolved "https://registry.yarnpkg.com/is-extglob/-/is-extglob-2.1.1.tgz#a88c02535791f02ed37c76a1b9ea9773c833f8c2" - integrity sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ== - -is-fullwidth-code-point@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz#f116f8064fe90b3f7844a38997c0b75051269f1d" - integrity sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg== - -is-generator-fn@^2.0.0: - version "2.1.0" - resolved "https://registry.yarnpkg.com/is-generator-fn/-/is-generator-fn-2.1.0.tgz#7d140adc389aaf3011a8f2a2a4cfa6faadffb118" - integrity sha512-cTIB4yPYL/Grw0EaSzASzg6bBy9gqCofvWN8okThAYIxKJZC+udlRAmGbM0XLeniEJSs8uEgHPGuHSe1XsOLSQ== - -is-glob@^4.0.0, is-glob@^4.0.1, is-glob@^4.0.3: - version "4.0.3" - resolved "https://registry.yarnpkg.com/is-glob/-/is-glob-4.0.3.tgz#64f61e42cbbb2eec2071a9dac0b28ba1e65d5084" - integrity sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg== - dependencies: - is-extglob "^2.1.1" - -is-number@^7.0.0: - version "7.0.0" - resolved "https://registry.yarnpkg.com/is-number/-/is-number-7.0.0.tgz#7535345b896734d5f80c4d06c50955527a14f12b" - integrity sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng== - -is-promise@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/is-promise/-/is-promise-4.0.0.tgz#42ff9f84206c1991d26debf520dd5c01042dd2f3" - integrity sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ== - -is-stream@^2.0.0: - version "2.0.1" - resolved "https://registry.yarnpkg.com/is-stream/-/is-stream-2.0.1.tgz#fac1e3d53b97ad5a9d0ae9cef2389f5810a5c077" - integrity sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg== - -isexe@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/isexe/-/isexe-2.0.0.tgz#e8fbf374dc556ff8947a10dcb0572d633f2cfa10" - integrity sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw== - -istanbul-lib-coverage@^3.0.0, istanbul-lib-coverage@^3.2.0: - version "3.2.2" - resolved "https://registry.yarnpkg.com/istanbul-lib-coverage/-/istanbul-lib-coverage-3.2.2.tgz#2d166c4b0644d43a39f04bf6c2edd1e585f31756" - integrity sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg== - -istanbul-lib-instrument@^5.0.4: - version "5.2.1" - resolved "https://registry.yarnpkg.com/istanbul-lib-instrument/-/istanbul-lib-instrument-5.2.1.tgz#d10c8885c2125574e1c231cacadf955675e1ce3d" - integrity sha512-pzqtp31nLv/XFOzXGuvhCb8qhjmTVo5vjVk19XE4CRlSWz0KoeJ3bw9XsA7nOp9YBf4qHjwBxkDzKcME/J29Yg== - dependencies: - "@babel/core" "^7.12.3" - "@babel/parser" "^7.14.7" - "@istanbuljs/schema" "^0.1.2" - istanbul-lib-coverage "^3.2.0" - semver "^6.3.0" - -istanbul-lib-instrument@^6.0.0: - version "6.0.3" - resolved "https://registry.yarnpkg.com/istanbul-lib-instrument/-/istanbul-lib-instrument-6.0.3.tgz#fa15401df6c15874bcb2105f773325d78c666765" - integrity sha512-Vtgk7L/R2JHyyGW07spoFlB8/lpjiOLTjMdms6AFMraYt3BaJauod/NGrfnVG/y4Ix1JEuMRPDPEj2ua+zz1/Q== - dependencies: - "@babel/core" "^7.23.9" - "@babel/parser" "^7.23.9" - "@istanbuljs/schema" "^0.1.3" - istanbul-lib-coverage "^3.2.0" - semver "^7.5.4" - -istanbul-lib-report@^3.0.0: - version "3.0.1" - resolved "https://registry.yarnpkg.com/istanbul-lib-report/-/istanbul-lib-report-3.0.1.tgz#908305bac9a5bd175ac6a74489eafd0fc2445a7d" - integrity sha512-GCfE1mtsHGOELCU8e/Z7YWzpmybrx/+dSTfLrvY8qRmaY6zXTKWn6WQIjaAFw069icm6GVMNkgu0NzI4iPZUNw== - dependencies: - istanbul-lib-coverage "^3.0.0" - make-dir "^4.0.0" - supports-color "^7.1.0" - -istanbul-lib-source-maps@^4.0.0: - version "4.0.1" - resolved "https://registry.yarnpkg.com/istanbul-lib-source-maps/-/istanbul-lib-source-maps-4.0.1.tgz#895f3a709fcfba34c6de5a42939022f3e4358551" - integrity sha512-n3s8EwkdFIJCG3BPKBYvskgXGoy88ARzvegkitk60NxRdwltLOTaH7CUiMRXvwYorl0Q712iEjcWB+fK/MrWVw== - dependencies: - debug "^4.1.1" - istanbul-lib-coverage "^3.0.0" - source-map "^0.6.1" - -istanbul-reports@^3.1.3: - version "3.2.0" - resolved "https://registry.yarnpkg.com/istanbul-reports/-/istanbul-reports-3.2.0.tgz#cb4535162b5784aa623cee21a7252cf2c807ac93" - integrity sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA== - dependencies: - html-escaper "^2.0.0" - istanbul-lib-report "^3.0.0" - -jest-changed-files@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-changed-files/-/jest-changed-files-29.7.0.tgz#1c06d07e77c78e1585d020424dedc10d6e17ac3a" - integrity sha512-fEArFiwf1BpQ+4bXSprcDc3/x4HSzL4al2tozwVpDFpsxALjLYdyiIK4e5Vz66GQJIbXJ82+35PtysofptNX2w== - dependencies: - execa "^5.0.0" - jest-util "^29.7.0" - p-limit "^3.1.0" - -jest-circus@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-circus/-/jest-circus-29.7.0.tgz#b6817a45fcc835d8b16d5962d0c026473ee3668a" - integrity sha512-3E1nCMgipcTkCocFwM90XXQab9bS+GMsjdpmPrlelaxwD93Ad8iVEjX/vvHPdLPnFf+L40u+5+iutRdA1N9myw== - dependencies: - "@jest/environment" "^29.7.0" - "@jest/expect" "^29.7.0" - "@jest/test-result" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/node" "*" - chalk "^4.0.0" - co "^4.6.0" - dedent "^1.0.0" - is-generator-fn "^2.0.0" - jest-each "^29.7.0" - jest-matcher-utils "^29.7.0" - jest-message-util "^29.7.0" - jest-runtime "^29.7.0" - jest-snapshot "^29.7.0" - jest-util "^29.7.0" - p-limit "^3.1.0" - pretty-format "^29.7.0" - pure-rand "^6.0.0" - slash "^3.0.0" - stack-utils "^2.0.3" - -jest-cli@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-cli/-/jest-cli-29.7.0.tgz#5592c940798e0cae677eec169264f2d839a37995" - integrity sha512-OVVobw2IubN/GSYsxETi+gOe7Ka59EFMR/twOU3Jb2GnKKeMGJB5SGUUrEz3SFVmJASUdZUzy83sLNNQ2gZslg== - dependencies: - "@jest/core" "^29.7.0" - "@jest/test-result" "^29.7.0" - "@jest/types" "^29.6.3" - chalk "^4.0.0" - create-jest "^29.7.0" - exit "^0.1.2" - import-local "^3.0.2" - jest-config "^29.7.0" - jest-util "^29.7.0" - jest-validate "^29.7.0" - yargs "^17.3.1" - -jest-config@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-config/-/jest-config-29.7.0.tgz#bcbda8806dbcc01b1e316a46bb74085a84b0245f" - integrity sha512-uXbpfeQ7R6TZBqI3/TxCU4q4ttk3u0PJeC+E0zbfSoSjq6bJ7buBPxzQPL0ifrkY4DNu4JUdk0ImlBUYi840eQ== - dependencies: - "@babel/core" "^7.11.6" - "@jest/test-sequencer" "^29.7.0" - "@jest/types" "^29.6.3" - babel-jest "^29.7.0" - chalk "^4.0.0" - ci-info "^3.2.0" - deepmerge "^4.2.2" - glob "^7.1.3" - graceful-fs "^4.2.9" - jest-circus "^29.7.0" - jest-environment-node "^29.7.0" - jest-get-type "^29.6.3" - jest-regex-util "^29.6.3" - jest-resolve "^29.7.0" - jest-runner "^29.7.0" - jest-util "^29.7.0" - jest-validate "^29.7.0" - micromatch "^4.0.4" - parse-json "^5.2.0" - pretty-format "^29.7.0" - slash "^3.0.0" - strip-json-comments "^3.1.1" - -jest-diff@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-diff/-/jest-diff-29.7.0.tgz#017934a66ebb7ecf6f205e84699be10afd70458a" - integrity sha512-LMIgiIrhigmPrs03JHpxUh2yISK3vLFPkAodPeo0+BuF7wA2FoQbkEg1u8gBYBThncu7e1oEDUfIXVuTqLRUjw== - dependencies: - chalk "^4.0.0" - diff-sequences "^29.6.3" - jest-get-type "^29.6.3" - pretty-format "^29.7.0" - -jest-docblock@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-docblock/-/jest-docblock-29.7.0.tgz#8fddb6adc3cdc955c93e2a87f61cfd350d5d119a" - integrity sha512-q617Auw3A612guyaFgsbFeYpNP5t2aoUNLwBUbc/0kD1R4t9ixDbyFTHd1nok4epoVFpr7PmeWHrhvuV3XaJ4g== - dependencies: - detect-newline "^3.0.0" - -jest-each@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-each/-/jest-each-29.7.0.tgz#162a9b3f2328bdd991beaabffbb74745e56577d1" - integrity sha512-gns+Er14+ZrEoC5fhOfYCY1LOHHr0TI+rQUHZS8Ttw2l7gl+80eHc/gFf2Ktkw0+SIACDTeWvpFcv3B04VembQ== - dependencies: - "@jest/types" "^29.6.3" - chalk "^4.0.0" - jest-get-type "^29.6.3" - jest-util "^29.7.0" - pretty-format "^29.7.0" - -jest-environment-node@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-environment-node/-/jest-environment-node-29.7.0.tgz#0b93e111dda8ec120bc8300e6d1fb9576e164376" - integrity sha512-DOSwCRqXirTOyheM+4d5YZOrWcdu0LNZ87ewUoywbcb2XR4wKgqiG8vNeYwhjFMbEkfju7wx2GYH0P2gevGvFw== - dependencies: - "@jest/environment" "^29.7.0" - "@jest/fake-timers" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/node" "*" - jest-mock "^29.7.0" - jest-util "^29.7.0" - -jest-get-type@^29.6.3: - version "29.6.3" - resolved "https://registry.yarnpkg.com/jest-get-type/-/jest-get-type-29.6.3.tgz#36f499fdcea197c1045a127319c0481723908fd1" - integrity sha512-zrteXnqYxfQh7l5FHyL38jL39di8H8rHoecLH3JNxH3BwOrBsNeabdap5e0I23lD4HHI8W5VFBZqG4Eaq5LNcw== - -jest-haste-map@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-haste-map/-/jest-haste-map-29.7.0.tgz#3c2396524482f5a0506376e6c858c3bbcc17b104" - integrity sha512-fP8u2pyfqx0K1rGn1R9pyE0/KTn+G7PxktWidOBTqFPLYX0b9ksaMFkhK5vrS3DVun09pckLdlx90QthlW7AmA== - dependencies: - "@jest/types" "^29.6.3" - "@types/graceful-fs" "^4.1.3" - "@types/node" "*" - anymatch "^3.0.3" - fb-watchman "^2.0.0" - graceful-fs "^4.2.9" - jest-regex-util "^29.6.3" - jest-util "^29.7.0" - jest-worker "^29.7.0" - micromatch "^4.0.4" - walker "^1.0.8" - optionalDependencies: - fsevents "^2.3.2" - -jest-leak-detector@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-leak-detector/-/jest-leak-detector-29.7.0.tgz#5b7ec0dadfdfec0ca383dc9aa016d36b5ea4c728" - integrity sha512-kYA8IJcSYtST2BY9I+SMC32nDpBT3J2NvWJx8+JCuCdl/CR1I4EKUJROiP8XtCcxqgTTBGJNdbB1A8XRKbTetw== - dependencies: - jest-get-type "^29.6.3" - pretty-format "^29.7.0" - -jest-matcher-utils@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-matcher-utils/-/jest-matcher-utils-29.7.0.tgz#ae8fec79ff249fd592ce80e3ee474e83a6c44f12" - integrity sha512-sBkD+Xi9DtcChsI3L3u0+N0opgPYnCRPtGcQYrgXmR+hmt/fYfWAL0xRXYU8eWOdfuLgBe0YCW3AFtnRLagq/g== - dependencies: - chalk "^4.0.0" - jest-diff "^29.7.0" - jest-get-type "^29.6.3" - pretty-format "^29.7.0" - -jest-message-util@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-message-util/-/jest-message-util-29.7.0.tgz#8bc392e204e95dfe7564abbe72a404e28e51f7f3" - integrity sha512-GBEV4GRADeP+qtB2+6u61stea8mGcOT4mCtrYISZwfu9/ISHFJ/5zOMXYbpBE9RsS5+Gb63DW4FgmnKJ79Kf6w== - dependencies: - "@babel/code-frame" "^7.12.13" - "@jest/types" "^29.6.3" - "@types/stack-utils" "^2.0.0" - chalk "^4.0.0" - graceful-fs "^4.2.9" - micromatch "^4.0.4" - pretty-format "^29.7.0" - slash "^3.0.0" - stack-utils "^2.0.3" - -jest-mock@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-mock/-/jest-mock-29.7.0.tgz#4e836cf60e99c6fcfabe9f99d017f3fdd50a6347" - integrity sha512-ITOMZn+UkYS4ZFh83xYAOzWStloNzJFO2s8DWrE4lhtGD+AorgnbkiKERe4wQVBydIGPx059g6riW5Btp6Llnw== - dependencies: - "@jest/types" "^29.6.3" - "@types/node" "*" - jest-util "^29.7.0" - -jest-pnp-resolver@^1.2.2: - version "1.2.3" - resolved "https://registry.yarnpkg.com/jest-pnp-resolver/-/jest-pnp-resolver-1.2.3.tgz#930b1546164d4ad5937d5540e711d4d38d4cad2e" - integrity sha512-+3NpwQEnRoIBtx4fyhblQDPgJI0H1IEIkX7ShLUjPGA7TtUTvI1oiKi3SR4oBR0hQhQR80l4WAe5RrXBwWMA8w== - -jest-regex-util@^29.6.3: - version "29.6.3" - resolved "https://registry.yarnpkg.com/jest-regex-util/-/jest-regex-util-29.6.3.tgz#4a556d9c776af68e1c5f48194f4d0327d24e8a52" - integrity sha512-KJJBsRCyyLNWCNBOvZyRDnAIfUiRJ8v+hOBQYGn8gDyF3UegwiP4gwRR3/SDa42g1YbVycTidUF3rKjyLFDWbg== - -jest-resolve-dependencies@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-resolve-dependencies/-/jest-resolve-dependencies-29.7.0.tgz#1b04f2c095f37fc776ff40803dc92921b1e88428" - integrity sha512-un0zD/6qxJ+S0et7WxeI3H5XSe9lTBBR7bOHCHXkKR6luG5mwDDlIzVQ0V5cZCuoTgEdcdwzTghYkTWfubi+nA== - dependencies: - jest-regex-util "^29.6.3" - jest-snapshot "^29.7.0" - -jest-resolve@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-resolve/-/jest-resolve-29.7.0.tgz#64d6a8992dd26f635ab0c01e5eef4399c6bcbc30" - integrity sha512-IOVhZSrg+UvVAshDSDtHyFCCBUl/Q3AAJv8iZ6ZjnZ74xzvwuzLXid9IIIPgTnY62SJjfuupMKZsZQRsCvxEgA== - dependencies: - chalk "^4.0.0" - graceful-fs "^4.2.9" - jest-haste-map "^29.7.0" - jest-pnp-resolver "^1.2.2" - jest-util "^29.7.0" - jest-validate "^29.7.0" - resolve "^1.20.0" - resolve.exports "^2.0.0" - slash "^3.0.0" - -jest-runner@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-runner/-/jest-runner-29.7.0.tgz#809af072d408a53dcfd2e849a4c976d3132f718e" - integrity sha512-fsc4N6cPCAahybGBfTRcq5wFR6fpLznMg47sY5aDpsoejOcVYFb07AHuSnR0liMcPTgBsA3ZJL6kFOjPdoNipQ== - dependencies: - "@jest/console" "^29.7.0" - "@jest/environment" "^29.7.0" - "@jest/test-result" "^29.7.0" - "@jest/transform" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/node" "*" - chalk "^4.0.0" - emittery "^0.13.1" - graceful-fs "^4.2.9" - jest-docblock "^29.7.0" - jest-environment-node "^29.7.0" - jest-haste-map "^29.7.0" - jest-leak-detector "^29.7.0" - jest-message-util "^29.7.0" - jest-resolve "^29.7.0" - jest-runtime "^29.7.0" - jest-util "^29.7.0" - jest-watcher "^29.7.0" - jest-worker "^29.7.0" - p-limit "^3.1.0" - source-map-support "0.5.13" - -jest-runtime@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-runtime/-/jest-runtime-29.7.0.tgz#efecb3141cf7d3767a3a0cc8f7c9990587d3d817" - integrity sha512-gUnLjgwdGqW7B4LvOIkbKs9WGbn+QLqRQQ9juC6HndeDiezIwhDP+mhMwHWCEcfQ5RUXa6OPnFF8BJh5xegwwQ== - dependencies: - "@jest/environment" "^29.7.0" - "@jest/fake-timers" "^29.7.0" - "@jest/globals" "^29.7.0" - "@jest/source-map" "^29.6.3" - "@jest/test-result" "^29.7.0" - "@jest/transform" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/node" "*" - chalk "^4.0.0" - cjs-module-lexer "^1.0.0" - collect-v8-coverage "^1.0.0" - glob "^7.1.3" - graceful-fs "^4.2.9" - jest-haste-map "^29.7.0" - jest-message-util "^29.7.0" - jest-mock "^29.7.0" - jest-regex-util "^29.6.3" - jest-resolve "^29.7.0" - jest-snapshot "^29.7.0" - jest-util "^29.7.0" - slash "^3.0.0" - strip-bom "^4.0.0" - -jest-snapshot@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-snapshot/-/jest-snapshot-29.7.0.tgz#c2c574c3f51865da1bb329036778a69bf88a6be5" - integrity sha512-Rm0BMWtxBcioHr1/OX5YCP8Uov4riHvKPknOGs804Zg9JGZgmIBkbtlxJC/7Z4msKYVbIJtfU+tKb8xlYNfdkw== - dependencies: - "@babel/core" "^7.11.6" - "@babel/generator" "^7.7.2" - "@babel/plugin-syntax-jsx" "^7.7.2" - "@babel/plugin-syntax-typescript" "^7.7.2" - "@babel/types" "^7.3.3" - "@jest/expect-utils" "^29.7.0" - "@jest/transform" "^29.7.0" - "@jest/types" "^29.6.3" - babel-preset-current-node-syntax "^1.0.0" - chalk "^4.0.0" - expect "^29.7.0" - graceful-fs "^4.2.9" - jest-diff "^29.7.0" - jest-get-type "^29.6.3" - jest-matcher-utils "^29.7.0" - jest-message-util "^29.7.0" - jest-util "^29.7.0" - natural-compare "^1.4.0" - pretty-format "^29.7.0" - semver "^7.5.3" - -jest-util@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-util/-/jest-util-29.7.0.tgz#23c2b62bfb22be82b44de98055802ff3710fc0bc" - integrity sha512-z6EbKajIpqGKU56y5KBUgy1dt1ihhQJgWzUlZHArA/+X2ad7Cb5iF+AK1EWVL/Bo7Rz9uurpqw6SiBCefUbCGA== - dependencies: - "@jest/types" "^29.6.3" - "@types/node" "*" - chalk "^4.0.0" - ci-info "^3.2.0" - graceful-fs "^4.2.9" - picomatch "^2.2.3" - -jest-validate@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-validate/-/jest-validate-29.7.0.tgz#7bf705511c64da591d46b15fce41400d52147d9c" - integrity sha512-ZB7wHqaRGVw/9hST/OuFUReG7M8vKeq0/J2egIGLdvjHCmYqGARhzXmtgi+gVeZ5uXFF219aOc3Ls2yLg27tkw== - dependencies: - "@jest/types" "^29.6.3" - camelcase "^6.2.0" - chalk "^4.0.0" - jest-get-type "^29.6.3" - leven "^3.1.0" - pretty-format "^29.7.0" - -jest-watcher@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-watcher/-/jest-watcher-29.7.0.tgz#7810d30d619c3a62093223ce6bb359ca1b28a2f2" - integrity sha512-49Fg7WXkU3Vl2h6LbLtMQ/HyB6rXSIX7SqvBLQmssRBGN9I0PNvPmAmCWSOY6SOvrjhI/F7/bGAv9RtnsPA03g== - dependencies: - "@jest/test-result" "^29.7.0" - "@jest/types" "^29.6.3" - "@types/node" "*" - ansi-escapes "^4.2.1" - chalk "^4.0.0" - emittery "^0.13.1" - jest-util "^29.7.0" - string-length "^4.0.1" - -jest-worker@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest-worker/-/jest-worker-29.7.0.tgz#acad073acbbaeb7262bd5389e1bcf43e10058d4a" - integrity sha512-eIz2msL/EzL9UFTFFx7jBTkeZfku0yUAyZZZmJ93H2TYEiroIx2PQjEXcwYtYl8zXCxb+PAmA2hLIt/6ZEkPHw== - dependencies: - "@types/node" "*" - jest-util "^29.7.0" - merge-stream "^2.0.0" - supports-color "^8.0.0" - -jest@^29.4.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/jest/-/jest-29.7.0.tgz#994676fc24177f088f1c5e3737f5697204ff2613" - integrity sha512-NIy3oAFp9shda19hy4HK0HRTWKtPJmGdnvywu01nOqNC2vZg+Z+fvJDxpMQA88eb2I9EcafcdjYgsDthnYTvGw== - dependencies: - "@jest/core" "^29.7.0" - "@jest/types" "^29.6.3" - import-local "^3.0.2" - jest-cli "^29.7.0" - -jose@^6.1.3: - version "6.2.1" - resolved "https://registry.yarnpkg.com/jose/-/jose-6.2.1.tgz#7a6b1de83816deaee9055a558e1278a7b2b9ea1b" - integrity sha512-jUaKr1yrbfaImV7R2TN/b3IcZzsw38/chqMpo2XJ7i2F8AfM/lA4G1goC3JVEwg0H7UldTmSt3P68nt31W7/mw== - -joycon@^3.1.1: - version "3.1.1" - resolved "https://registry.yarnpkg.com/joycon/-/joycon-3.1.1.tgz#bce8596d6ae808f8b68168f5fc69280996894f03" - integrity sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw== - -"jq-web@https://github.com/stainless-api/jq-web/releases/download/v0.8.8/jq-web.tar.gz": - version "0.8.8" - resolved "https://github.com/stainless-api/jq-web/releases/download/v0.8.8/jq-web.tar.gz#7849ef64bdfc28f70cbfc9888f886860e96da10d" - -js-tokens@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/js-tokens/-/js-tokens-4.0.0.tgz#19203fb59991df98e3a287050d4647cdeaf32499" - integrity sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ== - -js-yaml@^3.13.1: - version "3.14.2" - resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-3.14.2.tgz#77485ce1dd7f33c061fd1b16ecea23b55fcb04b0" - integrity sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg== - dependencies: - argparse "^1.0.7" - esprima "^4.0.0" - -js-yaml@^4.1.1: - version "4.1.1" - resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-4.1.1.tgz#854c292467705b699476e1a2decc0c8a3458806b" - integrity sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA== - dependencies: - argparse "^2.0.1" - -jsesc@^3.0.2: - version "3.1.0" - resolved "https://registry.yarnpkg.com/jsesc/-/jsesc-3.1.0.tgz#74d335a234f67ed19907fdadfac7ccf9d409825d" - integrity sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA== - -json-buffer@3.0.1: - version "3.0.1" - resolved "https://registry.yarnpkg.com/json-buffer/-/json-buffer-3.0.1.tgz#9338802a30d3b6605fbe0613e094008ca8c05a13" - integrity sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ== - -json-parse-even-better-errors@^2.3.0: - version "2.3.1" - resolved "https://registry.yarnpkg.com/json-parse-even-better-errors/-/json-parse-even-better-errors-2.3.1.tgz#7c47805a94319928e05777405dc12e1f7a4ee02d" - integrity sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w== - -json-schema-traverse@^0.4.1: - version "0.4.1" - resolved "https://registry.yarnpkg.com/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz#69f6a87d9513ab8bb8fe63bdb0979c448e684660" - integrity sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg== - -json-schema-traverse@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz#ae7bcb3656ab77a73ba5c49bf654f38e6b6860e2" - integrity sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug== - -json-schema-typed@^8.0.2: - version "8.0.2" - resolved "https://registry.yarnpkg.com/json-schema-typed/-/json-schema-typed-8.0.2.tgz#e98ee7b1899ff4a184534d1f167c288c66bbeff4" - integrity sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA== - -json-stable-stringify-without-jsonify@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/json-stable-stringify-without-jsonify/-/json-stable-stringify-without-jsonify-1.0.1.tgz#9db7b59496ad3f3cfef30a75142d2d930ad72651" - integrity sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw== - -json5@^2.2.2, json5@^2.2.3: - version "2.2.3" - resolved "https://registry.yarnpkg.com/json5/-/json5-2.2.3.tgz#78cd6f1a19bdc12b73db5ad0c61efd66c1e29283" - integrity sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg== - -jsonfile@^6.0.1: - version "6.2.0" - resolved "https://registry.yarnpkg.com/jsonfile/-/jsonfile-6.2.0.tgz#7c265bd1b65de6977478300087c99f1c84383f62" - integrity sha512-FGuPw30AdOIUTRMC2OMRtQV+jkVj2cfPqSeWXv1NEAJ1qZ5zb1X6z1mFhbfOB/iy3ssJCD+3KuZ8r8C3uVFlAg== - dependencies: - universalify "^2.0.0" - optionalDependencies: - graceful-fs "^4.1.6" - -keyv@^4.5.4: - version "4.5.4" - resolved "https://registry.yarnpkg.com/keyv/-/keyv-4.5.4.tgz#a879a99e29452f942439f2a405e3af8b31d4de93" - integrity sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw== - dependencies: - json-buffer "3.0.1" - -kleur@^3.0.3: - version "3.0.3" - resolved "https://registry.yarnpkg.com/kleur/-/kleur-3.0.3.tgz#a79c9ecc86ee1ce3fa6206d1216c501f147fc07e" - integrity sha512-eTIzlVOSUR+JxdDFepEYcBMtZ9Qqdef+rnzWdRZuMbOywu5tO2w2N7rqjoANZ5k9vywhL6Br1VRjUIgTQx4E8w== - -leven@^3.1.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/leven/-/leven-3.1.0.tgz#77891de834064cccba82ae7842bb6b14a13ed7f2" - integrity sha512-qsda+H8jTaUaN/x5vzW2rzc+8Rw4TAQ/4KjB46IwK5VH+IlVeeeje/EoZRpiXvIqjFgK84QffqPztGI3VBLG1A== - -levn@^0.4.1: - version "0.4.1" - resolved "https://registry.yarnpkg.com/levn/-/levn-0.4.1.tgz#ae4562c007473b932a6200d403268dd2fffc6ade" - integrity sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ== - dependencies: - prelude-ls "^1.2.1" - type-check "~0.4.0" - -lines-and-columns@^1.1.6: - version "1.2.4" - resolved "https://registry.yarnpkg.com/lines-and-columns/-/lines-and-columns-1.2.4.tgz#eca284f75d2965079309dc0ad9255abb2ebc1632" - integrity sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg== - -locate-path@^5.0.0: - version "5.0.0" - resolved "https://registry.yarnpkg.com/locate-path/-/locate-path-5.0.0.tgz#1afba396afd676a6d42504d0a67a3a7eb9f62aa0" - integrity sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g== - dependencies: - p-locate "^4.1.0" - -locate-path@^6.0.0: - version "6.0.0" - resolved "https://registry.yarnpkg.com/locate-path/-/locate-path-6.0.0.tgz#55321eb309febbc59c4801d931a72452a681d286" - integrity sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw== - dependencies: - p-locate "^5.0.0" - -lodash.memoize@^4.1.2: - version "4.1.2" - resolved "https://registry.yarnpkg.com/lodash.memoize/-/lodash.memoize-4.1.2.tgz#bcc6c49a42a2840ed997f323eada5ecd182e0bfe" - integrity sha512-t7j+NzmgnQzTAYXcsHYLgimltOV1MXHtlOWf6GjL9Kj8GK5FInw5JotxvbOs+IvV1/Dzo04/fCGfLVs7aXb4Ag== - -lodash.merge@^4.6.2: - version "4.6.2" - resolved "https://registry.yarnpkg.com/lodash.merge/-/lodash.merge-4.6.2.tgz#558aa53b43b661e1925a0afdfa36a9a1085fe57a" - integrity sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ== - -lru-cache@^5.1.1: - version "5.1.1" - resolved "https://registry.yarnpkg.com/lru-cache/-/lru-cache-5.1.1.tgz#1da27e6710271947695daf6848e847f01d84b920" - integrity sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w== - dependencies: - yallist "^3.0.2" - -make-dir@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/make-dir/-/make-dir-4.0.0.tgz#c3c2307a771277cd9638305f915c29ae741b614e" - integrity sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw== - dependencies: - semver "^7.5.3" - -make-error@^1.1.1, make-error@^1.3.6: - version "1.3.6" - resolved "https://registry.yarnpkg.com/make-error/-/make-error-1.3.6.tgz#2eb2e37ea9b67c4891f684a1394799af484cf7a2" - integrity sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw== - -makeerror@1.0.12: - version "1.0.12" - resolved "https://registry.yarnpkg.com/makeerror/-/makeerror-1.0.12.tgz#3e5dd2079a82e812e983cc6610c4a2cb0eaa801a" - integrity sha512-JmqCvUhmt43madlpFzG4BQzG2Z3m6tvQDNKdClZnO3VbIudJYmxsT0FNJMeiB2+JTSlTQTSbU8QdesVmwJcmLg== - dependencies: - tmpl "1.0.5" - -math-intrinsics@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/math-intrinsics/-/math-intrinsics-1.1.0.tgz#a0dd74be81e2aa5c2f27e65ce283605ee4e2b7f9" - integrity sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g== - -media-typer@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/media-typer/-/media-typer-1.1.0.tgz#6ab74b8f2d3320f2064b2a87a38e7931ff3a5561" - integrity sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw== - -merge-descriptors@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/merge-descriptors/-/merge-descriptors-2.0.0.tgz#ea922f660635a2249ee565e0449f951e6b603808" - integrity sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g== - -merge-stream@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/merge-stream/-/merge-stream-2.0.0.tgz#52823629a14dd00c9770fb6ad47dc6310f2c1f60" - integrity sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w== - -merge2@^1.3.0: - version "1.4.1" - resolved "https://registry.yarnpkg.com/merge2/-/merge2-1.4.1.tgz#4368892f885e907455a6fd7dc55c0c9d404990ae" - integrity sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg== - -micromatch@^4.0.4, micromatch@^4.0.8: - version "4.0.8" - resolved "https://registry.yarnpkg.com/micromatch/-/micromatch-4.0.8.tgz#d66fa18f3a47076789320b9b1af32bd86d9fa202" - integrity sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA== - dependencies: - braces "^3.0.3" - picomatch "^2.3.1" - -mime-db@^1.54.0: - version "1.54.0" - resolved "https://registry.yarnpkg.com/mime-db/-/mime-db-1.54.0.tgz#cddb3ee4f9c64530dff640236661d42cb6a314f5" - integrity sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ== - -mime-types@^3.0.0, mime-types@^3.0.2: - version "3.0.2" - resolved "https://registry.yarnpkg.com/mime-types/-/mime-types-3.0.2.tgz#39002d4182575d5af036ffa118100f2524b2e2ab" - integrity sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A== - dependencies: - mime-db "^1.54.0" - -mimic-fn@^2.1.0: - version "2.1.0" - resolved "https://registry.yarnpkg.com/mimic-fn/-/mimic-fn-2.1.0.tgz#7ed2c2ccccaf84d3ffcb7a69b57711fc2083401b" - integrity sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg== - -minimatch@^3.0.4, minimatch@^3.1.1, minimatch@^3.1.5: - version "3.1.5" - resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-3.1.5.tgz#580c88f8d5445f2bd6aa8f3cadefa0de79fbd69e" - integrity sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w== - dependencies: - brace-expansion "^1.1.7" - -minimatch@^7.4.3: - version "7.4.6" - resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-7.4.6.tgz#845d6f254d8f4a5e4fd6baf44d5f10c8448365fb" - integrity sha512-sBz8G/YjVniEz6lKPNpKxXwazJe4c19fEfV2GDMX6AjFz+MX9uDWIZW8XreVhkFW3fkIdTv/gxWr/Kks5FFAVw== - dependencies: - brace-expansion "^2.0.1" - -minimatch@^9.0.4: - version "9.0.5" - resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-9.0.5.tgz#d74f9dd6b57d83d8e98cfb82133b03978bc929e5" - integrity sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow== - dependencies: - brace-expansion "^2.0.1" - -minimist@^1.2.5, minimist@^1.2.6: - version "1.2.8" - resolved "https://registry.yarnpkg.com/minimist/-/minimist-1.2.8.tgz#c1a464e7693302e082a075cee0c057741ac4772c" - integrity sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA== - -mkdirp@^2.1.6: - version "2.1.6" - resolved "https://registry.yarnpkg.com/mkdirp/-/mkdirp-2.1.6.tgz#964fbcb12b2d8c5d6fbc62a963ac95a273e2cc19" - integrity sha512-+hEnITedc8LAtIP9u3HJDFIdcLV2vXP33sqLLIzkv1Db1zO/1OxbvYf0Y1OC/S/Qo5dxHXepofhmxL02PsKe+A== - -ms@^2.1.3: - version "2.1.3" - resolved "https://registry.yarnpkg.com/ms/-/ms-2.1.3.tgz#574c8138ce1d2b5861f0b44579dbadd60c6615b2" - integrity sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA== - -mute-stream@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/mute-stream/-/mute-stream-1.0.0.tgz#e31bd9fe62f0aed23520aa4324ea6671531e013e" - integrity sha512-avsJQhyd+680gKXyG/sQc0nXaC6rBkPOfyHYcFb9+hdkqQkR9bdnkJ0AMZhke0oesPqIO+mFFJ+IdBc7mst4IA== - -natural-compare@^1.4.0: - version "1.4.0" - resolved "https://registry.yarnpkg.com/natural-compare/-/natural-compare-1.4.0.tgz#4abebfeed7541f2c27acfb29bdbbd15c8d5ba4f7" - integrity sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw== - -negotiator@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/negotiator/-/negotiator-1.0.0.tgz#b6c91bb47172d69f93cfd7c357bbb529019b5f6a" - integrity sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg== - -neo-async@^2.6.2: - version "2.6.2" - resolved "https://registry.yarnpkg.com/neo-async/-/neo-async-2.6.2.tgz#b4aafb93e3aeb2d8174ca53cf163ab7d7308305f" - integrity sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw== - -node-forge@^1.3.2: - version "1.3.3" - resolved "https://registry.yarnpkg.com/node-forge/-/node-forge-1.3.3.tgz#0ad80f6333b3a0045e827ac20b7f735f93716751" - integrity sha512-rLvcdSyRCyouf6jcOIPe/BgwG/d7hKjzMKOas33/pHEr6gbq18IK9zV7DiPvzsz0oBJPme6qr6H6kGZuI9/DZg== - -node-int64@^0.4.0: - version "0.4.0" - resolved "https://registry.yarnpkg.com/node-int64/-/node-int64-0.4.0.tgz#87a9065cdb355d3182d8f94ce11188b825c68a3b" - integrity sha512-O5lz91xSOeoXP6DulyHfllpq+Eg00MWitZIbtPfoSEvqIHdl5gfcY6hYzDWnj0qD5tz52PI08u9qUvSVeUBeHw== - -node-releases@^2.0.27: - version "2.0.27" - resolved "https://registry.yarnpkg.com/node-releases/-/node-releases-2.0.27.tgz#eedca519205cf20f650f61d56b070db111231e4e" - integrity sha512-nmh3lCkYZ3grZvqcCH+fjmQ7X+H0OeZgP40OierEaAptX4XofMh5kwNbWh7lBduUzCcV/8kZ+NDLCwm2iorIlA== - -normalize-path@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/normalize-path/-/normalize-path-3.0.0.tgz#0dcd69ff23a1c9b11fd0978316644a0388216a65" - integrity sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA== - -npm-run-path@^4.0.1: - version "4.0.1" - resolved "https://registry.yarnpkg.com/npm-run-path/-/npm-run-path-4.0.1.tgz#b7ecd1e5ed53da8e37a55e1c2269e0b97ed748ea" - integrity sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw== - dependencies: - path-key "^3.0.0" - -object-assign@^4: - version "4.1.1" - resolved "https://registry.yarnpkg.com/object-assign/-/object-assign-4.1.1.tgz#2109adc7965887cfc05cbbd442cac8bfbb360863" - integrity sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg== - -object-inspect@^1.13.3: - version "1.13.4" - resolved "https://registry.yarnpkg.com/object-inspect/-/object-inspect-1.13.4.tgz#8375265e21bc20d0fa582c22e1b13485d6e00213" - integrity sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew== - -on-exit-leak-free@^2.1.0: - version "2.1.2" - resolved "https://registry.yarnpkg.com/on-exit-leak-free/-/on-exit-leak-free-2.1.2.tgz#fed195c9ebddb7d9e4c3842f93f281ac8dadd3b8" - integrity sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA== - -on-finished@^2.4.1: - version "2.4.1" - resolved "https://registry.yarnpkg.com/on-finished/-/on-finished-2.4.1.tgz#58c8c44116e54845ad57f14ab10b03533184ac3f" - integrity sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg== - dependencies: - ee-first "1.1.1" - -once@^1.3.0, once@^1.3.1, once@^1.4.0: - version "1.4.0" - resolved "https://registry.yarnpkg.com/once/-/once-1.4.0.tgz#583b1aa775961d4b113ac17d9c50baef9dd76bd1" - integrity sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w== - dependencies: - wrappy "1" - -onetime@^5.1.2: - version "5.1.2" - resolved "https://registry.yarnpkg.com/onetime/-/onetime-5.1.2.tgz#d0e96ebb56b07476df1dd9c4806e5237985ca45e" - integrity sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg== - dependencies: - mimic-fn "^2.1.0" - -optionator@^0.9.3: - version "0.9.4" - resolved "https://registry.yarnpkg.com/optionator/-/optionator-0.9.4.tgz#7ea1c1a5d91d764fb282139c88fe11e182a3a734" - integrity sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g== - dependencies: - deep-is "^0.1.3" - fast-levenshtein "^2.0.6" - levn "^0.4.1" - prelude-ls "^1.2.1" - type-check "^0.4.0" - word-wrap "^1.2.5" - -os-tmpdir@~1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/os-tmpdir/-/os-tmpdir-1.0.2.tgz#bbe67406c79aa85c5cfec766fe5734555dfa1274" - integrity sha512-D2FR03Vir7FIu45XBY20mTb+/ZSWB00sjU9jdQXt83gDrI4Ztz5Fs7/yy74g2N5SVQY4xY1qDr4rNddwYRVX0g== - -p-all@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/p-all/-/p-all-3.0.0.tgz#077c023c37e75e760193badab2bad3ccd5782bfb" - integrity sha512-qUZbvbBFVXm6uJ7U/WDiO0fv6waBMbjlCm4E66oZdRR+egswICarIdHyVSZZHudH8T5SF8x/JG0q0duFzPnlBw== - dependencies: - p-map "^4.0.0" - -p-limit@^2.2.0: - version "2.3.0" - resolved "https://registry.yarnpkg.com/p-limit/-/p-limit-2.3.0.tgz#3dd33c647a214fdfffd835933eb086da0dc21db1" - integrity sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w== - dependencies: - p-try "^2.0.0" - -p-limit@^3.0.2, p-limit@^3.1.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/p-limit/-/p-limit-3.1.0.tgz#e1daccbe78d0d1388ca18c64fea38e3e57e3706b" - integrity sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ== - dependencies: - yocto-queue "^0.1.0" - -p-locate@^4.1.0: - version "4.1.0" - resolved "https://registry.yarnpkg.com/p-locate/-/p-locate-4.1.0.tgz#a3428bb7088b3a60292f66919278b7c297ad4f07" - integrity sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A== - dependencies: - p-limit "^2.2.0" - -p-locate@^5.0.0: - version "5.0.0" - resolved "https://registry.yarnpkg.com/p-locate/-/p-locate-5.0.0.tgz#83c8315c6785005e3bd021839411c9e110e6d834" - integrity sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw== - dependencies: - p-limit "^3.0.2" - -p-map@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/p-map/-/p-map-4.0.0.tgz#bb2f95a5eda2ec168ec9274e06a747c3e2904d2b" - integrity sha512-/bjOqmgETBYB5BoEeGVea8dmvHb2m9GLy1E9W43yeyfP6QQCZGFNa+XRceJEuDB6zqr+gKpIAmlLebMpykw/MQ== - dependencies: - aggregate-error "^3.0.0" - -p-try@^2.0.0: - version "2.2.0" - resolved "https://registry.yarnpkg.com/p-try/-/p-try-2.2.0.tgz#cb2868540e313d61de58fafbe35ce9004d5540e6" - integrity sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ== - -parent-module@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/parent-module/-/parent-module-1.0.1.tgz#691d2709e78c79fae3a156622452d00762caaaa2" - integrity sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g== - dependencies: - callsites "^3.0.0" - -parse-json@^5.2.0: - version "5.2.0" - resolved "https://registry.yarnpkg.com/parse-json/-/parse-json-5.2.0.tgz#c76fc66dee54231c962b22bcc8a72cf2f99753cd" - integrity sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg== - dependencies: - "@babel/code-frame" "^7.0.0" - error-ex "^1.3.1" - json-parse-even-better-errors "^2.3.0" - lines-and-columns "^1.1.6" - -parseurl@^1.3.3: - version "1.3.3" - resolved "https://registry.yarnpkg.com/parseurl/-/parseurl-1.3.3.tgz#9da19e7bee8d12dff0513ed5b76957793bc2e8d4" - integrity sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ== - -path-browserify@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/path-browserify/-/path-browserify-1.0.1.tgz#d98454a9c3753d5790860f16f68867b9e46be1fd" - integrity sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g== - -path-exists@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/path-exists/-/path-exists-4.0.0.tgz#513bdbe2d3b95d7762e8c1137efa195c6c61b5b3" - integrity sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w== - -path-is-absolute@^1.0.0: - version "1.0.1" - resolved "https://registry.yarnpkg.com/path-is-absolute/-/path-is-absolute-1.0.1.tgz#174b9268735534ffbc7ace6bf53a5a9e1b5c5f5f" - integrity sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg== - -path-key@^3.0.0, path-key@^3.1.0: - version "3.1.1" - resolved "https://registry.yarnpkg.com/path-key/-/path-key-3.1.1.tgz#581f6ade658cbba65a0d3380de7753295054f375" - integrity sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q== - -path-parse@^1.0.7: - version "1.0.7" - resolved "https://registry.yarnpkg.com/path-parse/-/path-parse-1.0.7.tgz#fbc114b60ca42b30d9daf5858e4bd68bbedb6735" - integrity sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw== - -path-to-regexp@^8.0.0: - version "8.3.0" - resolved "https://registry.yarnpkg.com/path-to-regexp/-/path-to-regexp-8.3.0.tgz#aa818a6981f99321003a08987d3cec9c3474cd1f" - integrity sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA== - -picocolors@^1.1.1: - version "1.1.1" - resolved "https://registry.yarnpkg.com/picocolors/-/picocolors-1.1.1.tgz#3d321af3eab939b083c8f929a1d12cda81c26b6b" - integrity sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA== - -picomatch@^2.0.4, picomatch@^2.2.3, picomatch@^2.3.1: - version "2.3.1" - resolved "https://registry.yarnpkg.com/picomatch/-/picomatch-2.3.1.tgz#3ba3833733646d9d3e4995946c1365a67fb07a42" - integrity sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA== - -pino-abstract-transport@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/pino-abstract-transport/-/pino-abstract-transport-3.0.0.tgz#b21e5f33a297e8c4c915c62b3ce5dd4a87a52c23" - integrity sha512-wlfUczU+n7Hy/Ha5j9a/gZNy7We5+cXp8YL+X+PG8S0KXxw7n/JXA3c46Y0zQznIJ83URJiwy7Lh56WLokNuxg== - dependencies: - split2 "^4.0.0" - -pino-http@^11.0.0: - version "11.0.0" - resolved "https://registry.yarnpkg.com/pino-http/-/pino-http-11.0.0.tgz#ebadef4694fc59aadab9be7e5939aea625b4615f" - integrity sha512-wqg5XIAGRRIWtTk8qPGxkbrfiwEWz1lgedVLvhLALudKXvg1/L2lTFgTGPJ4Z2e3qcRmxoFxDuSdMdMGNM6I1g== - dependencies: - get-caller-file "^2.0.5" - pino "^10.0.0" - pino-std-serializers "^7.0.0" - process-warning "^5.0.0" - -pino-pretty@^13.1.3: - version "13.1.3" - resolved "https://registry.yarnpkg.com/pino-pretty/-/pino-pretty-13.1.3.tgz#2274cccda925dd355c104079a5029f6598d0381b" - integrity sha512-ttXRkkOz6WWC95KeY9+xxWL6AtImwbyMHrL1mSwqwW9u+vLp/WIElvHvCSDg0xO/Dzrggz1zv3rN5ovTRVowKg== - dependencies: - colorette "^2.0.7" - dateformat "^4.6.3" - fast-copy "^4.0.0" - fast-safe-stringify "^2.1.1" - help-me "^5.0.0" - joycon "^3.1.1" - minimist "^1.2.6" - on-exit-leak-free "^2.1.0" - pino-abstract-transport "^3.0.0" - pump "^3.0.0" - secure-json-parse "^4.0.0" - sonic-boom "^4.0.1" - strip-json-comments "^5.0.2" - -pino-std-serializers@^7.0.0: - version "7.1.0" - resolved "https://registry.yarnpkg.com/pino-std-serializers/-/pino-std-serializers-7.1.0.tgz#a7b0cd65225f29e92540e7853bd73b07479893fc" - integrity sha512-BndPH67/JxGExRgiX1dX0w1FvZck5Wa4aal9198SrRhZjH3GxKQUKIBnYJTdj2HDN3UQAS06HlfcSbQj2OHmaw== - -pino@^10.0.0, pino@^10.3.1: - version "10.3.1" - resolved "https://registry.yarnpkg.com/pino/-/pino-10.3.1.tgz#6552c8f8d8481844c9e452e7bf0be90bff1939ce" - integrity sha512-r34yH/GlQpKZbU1BvFFqOjhISRo1MNx1tWYsYvmj6KIRHSPMT2+yHOEb1SG6NMvRoHRF0a07kCOox/9yakl1vg== - dependencies: - "@pinojs/redact" "^0.4.0" - atomic-sleep "^1.0.0" - on-exit-leak-free "^2.1.0" - pino-abstract-transport "^3.0.0" - pino-std-serializers "^7.0.0" - process-warning "^5.0.0" - quick-format-unescaped "^4.0.3" - real-require "^0.2.0" - safe-stable-stringify "^2.3.1" - sonic-boom "^4.0.1" - thread-stream "^4.0.0" - -pirates@^4.0.4: - version "4.0.7" - resolved "https://registry.yarnpkg.com/pirates/-/pirates-4.0.7.tgz#643b4a18c4257c8a65104b73f3049ce9a0a15e22" - integrity sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA== - -pkce-challenge@^5.0.0: - version "5.0.1" - resolved "https://registry.yarnpkg.com/pkce-challenge/-/pkce-challenge-5.0.1.tgz#3b4446865b17b1745e9ace2016a31f48ddf6230d" - integrity sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ== - -pkg-dir@^4.2.0: - version "4.2.0" - resolved "https://registry.yarnpkg.com/pkg-dir/-/pkg-dir-4.2.0.tgz#f099133df7ede422e81d1d8448270eeb3e4261f3" - integrity sha512-HRDzbaKjC+AOWVXxAU/x54COGeIv9eb+6CkDSQoNTt4XyWoIJvuPsXizxu/Fr23EiekbtZwmh1IcIG/l/a10GQ== - dependencies: - find-up "^4.0.0" - -prelude-ls@^1.2.1: - version "1.2.1" - resolved "https://registry.yarnpkg.com/prelude-ls/-/prelude-ls-1.2.1.tgz#debc6489d7a6e6b0e7611888cec880337d316396" - integrity sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g== - -prettier-linter-helpers@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/prettier-linter-helpers/-/prettier-linter-helpers-1.0.1.tgz#6a31f88a4bad6c7adda253de12ba4edaea80ebcd" - integrity sha512-SxToR7P8Y2lWmv/kTzVLC1t/GDI2WGjMwNhLLE9qtH8Q13C+aEmuRlzDst4Up4s0Wc8sF2M+J57iB3cMLqftfg== - dependencies: - fast-diff "^1.1.2" - -prettier@^3.0.0: - version "3.7.4" - resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.7.4.tgz#d2f8335d4b1cec47e1c8098645411b0c9dff9c0f" - integrity sha512-v6UNi1+3hSlVvv8fSaoUbggEM5VErKmmpGA7Pl3HF8V6uKY7rvClBOJlH6yNwQtfTueNkGVpOv/mtWL9L4bgRA== - -pretty-bytes@^5.6.0: - version "5.6.0" - resolved "https://registry.yarnpkg.com/pretty-bytes/-/pretty-bytes-5.6.0.tgz#356256f643804773c82f64723fe78c92c62beaeb" - integrity sha512-FFw039TmrBqFK8ma/7OL3sDz/VytdtJr044/QUJtH0wK9lb9jLq9tJyIxUwtQJHwar2BqtiA4iCWSwo9JLkzFg== - -pretty-format@^29.0.0, pretty-format@^29.7.0: - version "29.7.0" - resolved "https://registry.yarnpkg.com/pretty-format/-/pretty-format-29.7.0.tgz#ca42c758310f365bfa71a0bda0a807160b776812" - integrity sha512-Pdlw/oPxN+aXdmM9R00JVC9WVFoCLTKJvDVLgmJ+qAffBMxsV85l/Lu7sNx4zSzPyoL2euImuEwHhOXdEgNFZQ== - dependencies: - "@jest/schemas" "^29.6.3" - ansi-styles "^5.0.0" - react-is "^18.0.0" - -process-warning@^5.0.0: - version "5.0.0" - resolved "https://registry.yarnpkg.com/process-warning/-/process-warning-5.0.0.tgz#566e0bf79d1dff30a72d8bbbe9e8ecefe8d378d7" - integrity sha512-a39t9ApHNx2L4+HBnQKqxxHNs1r7KF+Intd8Q/g1bUh6q0WIp9voPXJ/x0j+ZL45KF1pJd9+q2jLIRMfvEshkA== - -prompts@^2.0.1: - version "2.4.2" - resolved "https://registry.yarnpkg.com/prompts/-/prompts-2.4.2.tgz#7b57e73b3a48029ad10ebd44f74b01722a4cb069" - integrity sha512-NxNv/kLguCA7p3jE8oL2aEBsrJWgAakBpgmgK6lpPWV+WuOmY6r2/zbAVnP+T8bQlA0nzHXSJSJW0Hq7ylaD2Q== - dependencies: - kleur "^3.0.3" - sisteransi "^1.0.5" - -proxy-addr@^2.0.7: - version "2.0.7" - resolved "https://registry.yarnpkg.com/proxy-addr/-/proxy-addr-2.0.7.tgz#f19fe69ceab311eeb94b42e70e8c2070f9ba1025" - integrity sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg== - dependencies: - forwarded "0.2.0" - ipaddr.js "1.9.1" - -pump@^3.0.0: - version "3.0.4" - resolved "https://registry.yarnpkg.com/pump/-/pump-3.0.4.tgz#1f313430527fa8b905622ebd22fe1444e757ab3c" - integrity sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA== - dependencies: - end-of-stream "^1.1.0" - once "^1.3.1" - -punycode@^2.1.0: - version "2.3.1" - resolved "https://registry.yarnpkg.com/punycode/-/punycode-2.3.1.tgz#027422e2faec0b25e1549c3e1bd8309b9133b6e5" - integrity sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg== - -pure-rand@^6.0.0: - version "6.1.0" - resolved "https://registry.yarnpkg.com/pure-rand/-/pure-rand-6.1.0.tgz#d173cf23258231976ccbdb05247c9787957604f2" - integrity sha512-bVWawvoZoBYpp6yIoQtQXHZjmz35RSVHnUOTefl8Vcjr8snTPY1wnpSPMWekcFwbxI6gtmT7rSYPFvz71ldiOA== - -qs@^6.14.0, qs@^6.14.1: - version "6.14.1" - resolved "https://registry.yarnpkg.com/qs/-/qs-6.14.1.tgz#a41d85b9d3902f31d27861790506294881871159" - integrity sha512-4EK3+xJl8Ts67nLYNwqw/dsFVnCf+qR7RgXSK9jEEm9unao3njwMDdmsdvoKBKHzxd7tCYz5e5M+SnMjdtXGQQ== - dependencies: - side-channel "^1.1.0" - -queue-microtask@^1.2.2: - version "1.2.3" - resolved "https://registry.yarnpkg.com/queue-microtask/-/queue-microtask-1.2.3.tgz#4929228bbc724dfac43e0efb058caf7b6cfb6243" - integrity sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A== - -quick-format-unescaped@^4.0.3: - version "4.0.4" - resolved "https://registry.yarnpkg.com/quick-format-unescaped/-/quick-format-unescaped-4.0.4.tgz#93ef6dd8d3453cbc7970dd614fad4c5954d6b5a7" - integrity sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg== - -range-parser@^1.2.1: - version "1.2.1" - resolved "https://registry.yarnpkg.com/range-parser/-/range-parser-1.2.1.tgz#3cf37023d199e1c24d1a55b84800c2f3e6468031" - integrity sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg== - -raw-body@^3.0.0, raw-body@^3.0.1: - version "3.0.2" - resolved "https://registry.yarnpkg.com/raw-body/-/raw-body-3.0.2.tgz#3e3ada5ae5568f9095d84376fd3a49b8fb000a51" - integrity sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA== - dependencies: - bytes "~3.1.2" - http-errors "~2.0.1" - iconv-lite "~0.7.0" - unpipe "~1.0.0" - -react-is@^18.0.0: - version "18.3.1" - resolved "https://registry.yarnpkg.com/react-is/-/react-is-18.3.1.tgz#e83557dc12eae63a99e003a46388b1dcbb44db7e" - integrity sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg== - -readable-stream@^3.4.0: - version "3.6.2" - resolved "https://registry.yarnpkg.com/readable-stream/-/readable-stream-3.6.2.tgz#56a9b36ea965c00c5a93ef31eb111a0f11056967" - integrity sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA== - dependencies: - inherits "^2.0.3" - string_decoder "^1.1.1" - util-deprecate "^1.0.1" - -real-require@^0.2.0: - version "0.2.0" - resolved "https://registry.yarnpkg.com/real-require/-/real-require-0.2.0.tgz#209632dea1810be2ae063a6ac084fee7e33fba78" - integrity sha512-57frrGM/OCTLqLOAh0mhVA9VBMHd+9U7Zb2THMGdBUoZVOtGbJzjxsYGDJ3A9AYYCP4hn6y1TVbaOfzWtm5GFg== - -require-directory@^2.1.1: - version "2.1.1" - resolved "https://registry.yarnpkg.com/require-directory/-/require-directory-2.1.1.tgz#8c64ad5fd30dab1c976e2344ffe7f792a6a6df42" - integrity sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q== - -require-from-string@^2.0.2: - version "2.0.2" - resolved "https://registry.yarnpkg.com/require-from-string/-/require-from-string-2.0.2.tgz#89a7fdd938261267318eafe14f9c32e598c36909" - integrity sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw== - -resolve-cwd@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/resolve-cwd/-/resolve-cwd-3.0.0.tgz#0f0075f1bb2544766cf73ba6a6e2adfebcb13f2d" - integrity sha512-OrZaX2Mb+rJCpH/6CpSqt9xFVpN++x01XnN2ie9g6P5/3xelLAkXWVADpdz1IHD/KFfEXyE6V0U01OQ3UO2rEg== - dependencies: - resolve-from "^5.0.0" - -resolve-from@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/resolve-from/-/resolve-from-4.0.0.tgz#4abcd852ad32dd7baabfe9b40e00a36db5f392e6" - integrity sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g== - -resolve-from@^5.0.0: - version "5.0.0" - resolved "https://registry.yarnpkg.com/resolve-from/-/resolve-from-5.0.0.tgz#c35225843df8f776df21c57557bc087e9dfdfc69" - integrity sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw== - -resolve.exports@^2.0.0: - version "2.0.3" - resolved "https://registry.yarnpkg.com/resolve.exports/-/resolve.exports-2.0.3.tgz#41955e6f1b4013b7586f873749a635dea07ebe3f" - integrity sha512-OcXjMsGdhL4XnbShKpAcSqPMzQoYkYyhbEaeSko47MjRP9NfEQMhZkXL1DoFlt9LWQn4YttrdnV6X2OiyzBi+A== - -resolve@^1.20.0: - version "1.22.11" - resolved "https://registry.yarnpkg.com/resolve/-/resolve-1.22.11.tgz#aad857ce1ffb8bfa9b0b1ac29f1156383f68c262" - integrity sha512-RfqAvLnMl313r7c9oclB1HhUEAezcpLjz95wFH4LVuhk9JF/r22qmVP9AMmOU4vMX7Q8pN8jwNg/CSpdFnMjTQ== - dependencies: - is-core-module "^2.16.1" - path-parse "^1.0.7" - supports-preserve-symlinks-flag "^1.0.0" - -reusify@^1.0.4: - version "1.1.0" - resolved "https://registry.yarnpkg.com/reusify/-/reusify-1.1.0.tgz#0fe13b9522e1473f51b558ee796e08f11f9b489f" - integrity sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw== - -router@^2.2.0: - version "2.2.0" - resolved "https://registry.yarnpkg.com/router/-/router-2.2.0.tgz#019be620b711c87641167cc79b99090f00b146ef" - integrity sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ== - dependencies: - debug "^4.4.0" - depd "^2.0.0" - is-promise "^4.0.0" - parseurl "^1.3.3" - path-to-regexp "^8.0.0" - -run-parallel@^1.1.9: - version "1.2.0" - resolved "https://registry.yarnpkg.com/run-parallel/-/run-parallel-1.2.0.tgz#66d1368da7bdf921eb9d95bd1a9229e7f21a43ee" - integrity sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA== - dependencies: - queue-microtask "^1.2.2" - -safe-buffer@~5.2.0: - version "5.2.1" - resolved "https://registry.yarnpkg.com/safe-buffer/-/safe-buffer-5.2.1.tgz#1eaf9fa9bdb1fdd4ec75f58f9cdb4e6b7827eec6" - integrity sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ== - -safe-stable-stringify@^2.3.1: - version "2.5.0" - resolved "https://registry.yarnpkg.com/safe-stable-stringify/-/safe-stable-stringify-2.5.0.tgz#4ca2f8e385f2831c432a719b108a3bf7af42a1dd" - integrity sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA== - -"safer-buffer@>= 2.1.2 < 3", "safer-buffer@>= 2.1.2 < 3.0.0": - version "2.1.2" - resolved "https://registry.yarnpkg.com/safer-buffer/-/safer-buffer-2.1.2.tgz#44fa161b0187b9549dd84bb91802f9bd8385cd6a" - integrity sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg== - -secure-json-parse@^4.0.0: - version "4.1.0" - resolved "https://registry.yarnpkg.com/secure-json-parse/-/secure-json-parse-4.1.0.tgz#4f1ab41c67a13497ea1b9131bb4183a22865477c" - integrity sha512-l4KnYfEyqYJxDwlNVyRfO2E4NTHfMKAWdUuA8J0yve2Dz/E/PdBepY03RvyJpssIpRFwJoCD55wA+mEDs6ByWA== - -semver@^6.3.0, semver@^6.3.1: - version "6.3.1" - resolved "https://registry.yarnpkg.com/semver/-/semver-6.3.1.tgz#556d2ef8689146e46dcea4bfdd095f3434dffcb4" - integrity sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA== - -semver@^7.5.3, semver@^7.5.4, semver@^7.6.0, semver@^7.7.3: - version "7.7.3" - resolved "https://registry.yarnpkg.com/semver/-/semver-7.7.3.tgz#4b5f4143d007633a8dc671cd0a6ef9147b8bb946" - integrity sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q== - -send@^1.1.0, send@^1.2.0: - version "1.2.1" - resolved "https://registry.yarnpkg.com/send/-/send-1.2.1.tgz#9eab743b874f3550f40a26867bf286ad60d3f3ed" - integrity sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ== - dependencies: - debug "^4.4.3" - encodeurl "^2.0.0" - escape-html "^1.0.3" - etag "^1.8.1" - fresh "^2.0.0" - http-errors "^2.0.1" - mime-types "^3.0.2" - ms "^2.1.3" - on-finished "^2.4.1" - range-parser "^1.2.1" - statuses "^2.0.2" - -serve-static@^2.2.0: - version "2.2.1" - resolved "https://registry.yarnpkg.com/serve-static/-/serve-static-2.2.1.tgz#7f186a4a4e5f5b663ad7a4294ff1bf37cf0e98a9" - integrity sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw== - dependencies: - encodeurl "^2.0.0" - escape-html "^1.0.3" - parseurl "^1.3.3" - send "^1.2.0" - -setprototypeof@~1.2.0: - version "1.2.0" - resolved "https://registry.yarnpkg.com/setprototypeof/-/setprototypeof-1.2.0.tgz#66c9a24a73f9fc28cbe66b09fed3d33dcaf1b424" - integrity sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw== - -shebang-command@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/shebang-command/-/shebang-command-2.0.0.tgz#ccd0af4f8835fbdc265b82461aaf0c36663f34ea" - integrity sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA== - dependencies: - shebang-regex "^3.0.0" - -shebang-regex@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/shebang-regex/-/shebang-regex-3.0.0.tgz#ae16f1644d873ecad843b0307b143362d4c42172" - integrity sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A== - -side-channel-list@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/side-channel-list/-/side-channel-list-1.0.0.tgz#10cb5984263115d3b7a0e336591e290a830af8ad" - integrity sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA== - dependencies: - es-errors "^1.3.0" - object-inspect "^1.13.3" - -side-channel-map@^1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/side-channel-map/-/side-channel-map-1.0.1.tgz#d6bb6b37902c6fef5174e5f533fab4c732a26f42" - integrity sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA== - dependencies: - call-bound "^1.0.2" - es-errors "^1.3.0" - get-intrinsic "^1.2.5" - object-inspect "^1.13.3" - -side-channel-weakmap@^1.0.2: - version "1.0.2" - resolved "https://registry.yarnpkg.com/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz#11dda19d5368e40ce9ec2bdc1fb0ecbc0790ecea" - integrity sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A== - dependencies: - call-bound "^1.0.2" - es-errors "^1.3.0" - get-intrinsic "^1.2.5" - object-inspect "^1.13.3" - side-channel-map "^1.0.1" - -side-channel@^1.1.0: - version "1.1.0" - resolved "https://registry.yarnpkg.com/side-channel/-/side-channel-1.1.0.tgz#c3fcff9c4da932784873335ec9765fa94ff66bc9" - integrity sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw== - dependencies: - es-errors "^1.3.0" - object-inspect "^1.13.3" - side-channel-list "^1.0.0" - side-channel-map "^1.0.1" - side-channel-weakmap "^1.0.2" - -signal-exit@^3.0.3, signal-exit@^3.0.7: - version "3.0.7" - resolved "https://registry.yarnpkg.com/signal-exit/-/signal-exit-3.0.7.tgz#a9a1767f8af84155114eaabd73f99273c8f59ad9" - integrity sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ== - -signal-exit@^4.1.0: - version "4.1.0" - resolved "https://registry.yarnpkg.com/signal-exit/-/signal-exit-4.1.0.tgz#952188c1cbd546070e2dd20d0f41c0ae0530cb04" - integrity sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw== - -sisteransi@^1.0.5: - version "1.0.5" - resolved "https://registry.yarnpkg.com/sisteransi/-/sisteransi-1.0.5.tgz#134d681297756437cc05ca01370d3a7a571075ed" - integrity sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg== - -slash@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/slash/-/slash-3.0.0.tgz#6539be870c165adbd5240220dbe361f1bc4d4634" - integrity sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q== - -sonic-boom@^4.0.1: - version "4.2.1" - resolved "https://registry.yarnpkg.com/sonic-boom/-/sonic-boom-4.2.1.tgz#28598250df4899c0ac572d7e2f0460690ba6a030" - integrity sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q== - dependencies: - atomic-sleep "^1.0.0" - -source-map-support@0.5.13: - version "0.5.13" - resolved "https://registry.yarnpkg.com/source-map-support/-/source-map-support-0.5.13.tgz#31b24a9c2e73c2de85066c0feb7d44767ed52932" - integrity sha512-SHSKFHadjVA5oR4PPqhtAVdcBWwRYVd6g6cAXnIbRiIwc2EhPrTuKUBdSLvlEKyIP3GCf89fltvcZiP9MMFA1w== - dependencies: - buffer-from "^1.0.0" - source-map "^0.6.0" - -source-map@^0.6.0, source-map@^0.6.1: - version "0.6.1" - resolved "https://registry.yarnpkg.com/source-map/-/source-map-0.6.1.tgz#74722af32e9614e9c287a8d0bbde48b5e2f1a263" - integrity sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g== - -split2@^4.0.0: - version "4.2.0" - resolved "https://registry.yarnpkg.com/split2/-/split2-4.2.0.tgz#c9c5920904d148bab0b9f67145f245a86aadbfa4" - integrity sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg== - -sprintf-js@~1.0.2: - version "1.0.3" - resolved "https://registry.yarnpkg.com/sprintf-js/-/sprintf-js-1.0.3.tgz#04e6926f662895354f3dd015203633b857297e2c" - integrity sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g== - -stack-utils@^2.0.3: - version "2.0.6" - resolved "https://registry.yarnpkg.com/stack-utils/-/stack-utils-2.0.6.tgz#aaf0748169c02fc33c8232abccf933f54a1cc34f" - integrity sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ== - dependencies: - escape-string-regexp "^2.0.0" - -statuses@^2.0.1, statuses@^2.0.2, statuses@~2.0.2: - version "2.0.2" - resolved "https://registry.yarnpkg.com/statuses/-/statuses-2.0.2.tgz#8f75eecef765b5e1cfcdc080da59409ed424e382" - integrity sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw== - -string-length@^4.0.1: - version "4.0.2" - resolved "https://registry.yarnpkg.com/string-length/-/string-length-4.0.2.tgz#a8a8dc7bd5c1a82b9b3c8b87e125f66871b6e57a" - integrity sha512-+l6rNN5fYHNhZZy41RXsYptCjA2Igmq4EG7kZAYFQI1E1VTXarr6ZPXBg6eq7Y6eK4FEhY6AJlyuFIb/v/S0VQ== - dependencies: - char-regex "^1.0.2" - strip-ansi "^6.0.0" - -string-to-stream@^3.0.1: - version "3.0.1" - resolved "https://registry.yarnpkg.com/string-to-stream/-/string-to-stream-3.0.1.tgz#480e6fb4d5476d31cb2221f75307a5dcb6638a42" - integrity sha512-Hl092MV3USJuUCC6mfl9sPzGloA3K5VwdIeJjYIkXY/8K+mUvaeEabWJgArp+xXrsWxCajeT2pc4axbVhIZJyg== - dependencies: - readable-stream "^3.4.0" - -string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.3: - version "4.2.3" - resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010" - integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g== - dependencies: - emoji-regex "^8.0.0" - is-fullwidth-code-point "^3.0.0" - strip-ansi "^6.0.1" - -string_decoder@^1.1.1: - version "1.3.0" - resolved "https://registry.yarnpkg.com/string_decoder/-/string_decoder-1.3.0.tgz#42f114594a46cf1a8e30b0a84f56c78c3edac21e" - integrity sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA== - dependencies: - safe-buffer "~5.2.0" - -strip-ansi@^6.0.0, strip-ansi@^6.0.1: - version "6.0.1" - resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.1.tgz#9e26c63d30f53443e9489495b2105d37b67a85d9" - integrity sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A== - dependencies: - ansi-regex "^5.0.1" - -strip-bom@^3.0.0: - version "3.0.0" - resolved "https://registry.yarnpkg.com/strip-bom/-/strip-bom-3.0.0.tgz#2334c18e9c759f7bdd56fdef7e9ae3d588e68ed3" - integrity sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA== - -strip-bom@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/strip-bom/-/strip-bom-4.0.0.tgz#9c3505c1db45bcedca3d9cf7a16f5c5aa3901878" - integrity sha512-3xurFv5tEgii33Zi8Jtp55wEIILR9eh34FAW00PZf+JnSsTmV/ioewSgQl97JHvgjoRGwPShsWm+IdrxB35d0w== - -strip-final-newline@^2.0.0: - version "2.0.0" - resolved "https://registry.yarnpkg.com/strip-final-newline/-/strip-final-newline-2.0.0.tgz#89b852fb2fcbe936f6f4b3187afb0a12c1ab58ad" - integrity sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA== - -strip-json-comments@^3.1.1: - version "3.1.1" - resolved "https://registry.yarnpkg.com/strip-json-comments/-/strip-json-comments-3.1.1.tgz#31f1281b3832630434831c310c01cccda8cbe006" - integrity sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig== - -strip-json-comments@^5.0.2: - version "5.0.3" - resolved "https://registry.yarnpkg.com/strip-json-comments/-/strip-json-comments-5.0.3.tgz#b7304249dd402ee67fd518ada993ab3593458bcf" - integrity sha512-1tB5mhVo7U+ETBKNf92xT4hrQa3pm0MZ0PQvuDnWgAAGHDsfp4lPSpiS6psrSiet87wyGPh9ft6wmhOMQ0hDiw== - -superstruct@^1.0.4: - version "1.0.4" - resolved "https://registry.yarnpkg.com/superstruct/-/superstruct-1.0.4.tgz#0adb99a7578bd2f1c526220da6571b2d485d91ca" - integrity sha512-7JpaAoX2NGyoFlI9NBh66BQXGONc+uE+MRS5i2iOBKuS4e+ccgMDjATgZldkah+33DakBxDHiss9kvUcGAO8UQ== - -supports-color@^7.1.0: - version "7.2.0" - resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-7.2.0.tgz#1b7dcdcb32b8138801b3e478ba6a51caa89648da" - integrity sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw== - dependencies: - has-flag "^4.0.0" - -supports-color@^8.0.0: - version "8.1.1" - resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-8.1.1.tgz#cd6fc17e28500cff56c1b86c0a7fd4a54a73005c" - integrity sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q== - dependencies: - has-flag "^4.0.0" - -supports-preserve-symlinks-flag@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz#6eda4bd344a3c94aea376d4cc31bc77311039e09" - integrity sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w== - -synckit@^0.11.12: - version "0.11.12" - resolved "https://registry.yarnpkg.com/synckit/-/synckit-0.11.12.tgz#abe74124264fbc00a48011b0d98bdc1cffb64a7b" - integrity sha512-Bh7QjT8/SuKUIfObSXNHNSK6WHo6J1tHCqJsuaFDP7gP0fkzSfTxI8y85JrppZ0h8l0maIgc2tfuZQ6/t3GtnQ== - dependencies: - "@pkgr/core" "^0.2.9" - -test-exclude@^6.0.0: - version "6.0.0" - resolved "https://registry.yarnpkg.com/test-exclude/-/test-exclude-6.0.0.tgz#04a8698661d805ea6fa293b6cb9e63ac044ef15e" - integrity sha512-cAGWPIyOHU6zlmg88jwm7VRyXnMN7iV68OGAbYDk/Mh/xC/pzVPlQtY6ngoIH/5/tciuhGfvESU8GrHrcxD56w== - dependencies: - "@istanbuljs/schema" "^0.1.2" - glob "^7.1.4" - minimatch "^3.0.4" - -thread-stream@^4.0.0: - version "4.0.0" - resolved "https://registry.yarnpkg.com/thread-stream/-/thread-stream-4.0.0.tgz#732f007c24da7084f729d6e3a7e3f5934a7380b7" - integrity sha512-4iMVL6HAINXWf1ZKZjIPcz5wYaOdPhtO8ATvZ+Xqp3BTdaqtAwQkNmKORqcIo5YkQqGXq5cwfswDwMqqQNrpJA== - dependencies: - real-require "^0.2.0" - -tmp@^0.0.33: - version "0.0.33" - resolved "https://registry.yarnpkg.com/tmp/-/tmp-0.0.33.tgz#6d34335889768d21b2bcda0aa277ced3b1bfadf9" - integrity sha512-jRCJlojKnZ3addtTOjdIqoRuPEKBvNXcGYqzO6zWZX8KfKEpnGY5jfggJQ3EjKuu8D4bJRr0y+cYJFmYbImXGw== - dependencies: - os-tmpdir "~1.0.2" - -tmpl@1.0.5: - version "1.0.5" - resolved "https://registry.yarnpkg.com/tmpl/-/tmpl-1.0.5.tgz#8683e0b902bb9c20c4f726e3c0b69f36518c07cc" - integrity sha512-3f0uOEAQwIqGuWW2MVzYg8fV/QNnc/IpuJNG837rLuczAaLVHslWHZQj4IGiEl5Hs3kkbhwL9Ab7Hrsmuj+Smw== - -to-regex-range@^5.0.1: - version "5.0.1" - resolved "https://registry.yarnpkg.com/to-regex-range/-/to-regex-range-5.0.1.tgz#1648c44aae7c8d988a326018ed72f5b4dd0392e4" - integrity sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ== - dependencies: - is-number "^7.0.0" - -toidentifier@~1.0.1: - version "1.0.1" - resolved "https://registry.yarnpkg.com/toidentifier/-/toidentifier-1.0.1.tgz#3be34321a88a820ed1bd80dfaa33e479fbb8dd35" - integrity sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA== - -ts-api-utils@^2.0.1: - version "2.4.0" - resolved "https://registry.yarnpkg.com/ts-api-utils/-/ts-api-utils-2.4.0.tgz#2690579f96d2790253bdcf1ca35d569ad78f9ad8" - integrity sha512-3TaVTaAv2gTiMB35i3FiGJaRfwb3Pyn/j3m/bfAvGe8FB7CF6u+LMYqYlDh7reQf7UNvoTvdfAqHGmPGOSsPmA== - -ts-jest@^29.1.0: - version "29.4.6" - resolved "https://registry.yarnpkg.com/ts-jest/-/ts-jest-29.4.6.tgz#51cb7c133f227396818b71297ad7409bb77106e9" - integrity sha512-fSpWtOO/1AjSNQguk43hb/JCo16oJDnMJf3CdEGNkqsEX3t0KX96xvyX1D7PfLCpVoKu4MfVrqUkFyblYoY4lA== - dependencies: - bs-logger "^0.2.6" - fast-json-stable-stringify "^2.1.0" - handlebars "^4.7.8" - json5 "^2.2.3" - lodash.memoize "^4.1.2" - make-error "^1.3.6" - semver "^7.7.3" - type-fest "^4.41.0" - yargs-parser "^21.1.1" - -ts-morph@^19.0.0: - version "19.0.0" - resolved "https://registry.yarnpkg.com/ts-morph/-/ts-morph-19.0.0.tgz#43e95fb0156c3fe3c77c814ac26b7d0be2f93169" - integrity sha512-D6qcpiJdn46tUqV45vr5UGM2dnIEuTGNxVhg0sk5NX11orcouwj6i1bMqZIz2mZTZB1Hcgy7C3oEVhAT+f6mbQ== - dependencies: - "@ts-morph/common" "~0.20.0" - code-block-writer "^12.0.0" - -ts-node@^10.5.0: - version "10.9.2" - resolved "https://registry.yarnpkg.com/ts-node/-/ts-node-10.9.2.tgz#70f021c9e185bccdca820e26dc413805c101c71f" - integrity sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ== - dependencies: - "@cspotcode/source-map-support" "^0.8.0" - "@tsconfig/node10" "^1.0.7" - "@tsconfig/node12" "^1.0.7" - "@tsconfig/node14" "^1.0.0" - "@tsconfig/node16" "^1.0.2" - acorn "^8.4.1" - acorn-walk "^8.1.1" - arg "^4.1.0" - create-require "^1.1.0" - diff "^4.0.1" - make-error "^1.1.1" - v8-compile-cache-lib "^3.0.1" - yn "3.1.1" - -"tsc-multi@https://github.com/stainless-api/tsc-multi/releases/download/v1.1.11/tsc-multi.tgz": - version "1.1.11" - resolved "https://github.com/stainless-api/tsc-multi/releases/download/v1.1.11/tsc-multi.tgz#010247051be13b55abdc98f787c017285149f4f2" - dependencies: - debug "^4.3.7" - fast-glob "^3.3.2" - get-stdin "^8.0.0" - p-all "^3.0.0" - picocolors "^1.1.1" - signal-exit "^3.0.7" - string-to-stream "^3.0.1" - superstruct "^1.0.4" - tslib "^2.8.1" - yargs "^17.7.2" - -tsconfig-paths@^4.0.0: - version "4.2.0" - resolved "https://registry.yarnpkg.com/tsconfig-paths/-/tsconfig-paths-4.2.0.tgz#ef78e19039133446d244beac0fd6a1632e2d107c" - integrity sha512-NoZ4roiN7LnbKn9QqE1amc9DJfzvZXxF4xDavcOWt1BPkdx+m+0gJuPM+S0vCe7zTJMYUP0R8pO2XMr+Y8oLIg== - dependencies: - json5 "^2.2.2" - minimist "^1.2.6" - strip-bom "^3.0.0" - -tslib@^2.8.1: - version "2.8.1" - resolved "https://registry.yarnpkg.com/tslib/-/tslib-2.8.1.tgz#612efe4ed235d567e8aba5f2a5fab70280ade83f" - integrity sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w== - -type-check@^0.4.0, type-check@~0.4.0: - version "0.4.0" - resolved "https://registry.yarnpkg.com/type-check/-/type-check-0.4.0.tgz#07b8203bfa7056c0657050e3ccd2c37730bab8f1" - integrity sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew== - dependencies: - prelude-ls "^1.2.1" - -type-detect@4.0.8: - version "4.0.8" - resolved "https://registry.yarnpkg.com/type-detect/-/type-detect-4.0.8.tgz#7646fb5f18871cfbb7749e69bd39a6388eb7450c" - integrity sha512-0fr/mIH1dlO+x7TlcMy+bIDqKPsw/70tVyeHW787goQjhmqaZe10uwLujubK9q9Lg6Fiho1KUKDYz0Z7k7g5/g== - -type-fest@^0.21.3: - version "0.21.3" - resolved "https://registry.yarnpkg.com/type-fest/-/type-fest-0.21.3.tgz#d260a24b0198436e133fa26a524a6d65fa3b2e37" - integrity sha512-t0rzBq87m3fVcduHDUFhKmyyX+9eo6WQjZvf51Ea/M0Q7+T374Jp1aUiyUl0GKxp8M/OETVHSDvmkyPgvX+X2w== - -type-fest@^4.41.0: - version "4.41.0" - resolved "https://registry.yarnpkg.com/type-fest/-/type-fest-4.41.0.tgz#6ae1c8e5731273c2bf1f58ad39cbae2c91a46c58" - integrity sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA== - -type-is@^2.0.1: - version "2.0.1" - resolved "https://registry.yarnpkg.com/type-is/-/type-is-2.0.1.tgz#64f6cf03f92fce4015c2b224793f6bdd4b068c97" - integrity sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw== - dependencies: - content-type "^1.0.5" - media-typer "^1.1.0" - mime-types "^3.0.0" - -typescript@5.8.3: - version "5.8.3" - resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.8.3.tgz#92f8a3e5e3cf497356f4178c34cd65a7f5e8440e" - integrity sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ== - -uglify-js@^3.1.4: - version "3.19.3" - resolved "https://registry.yarnpkg.com/uglify-js/-/uglify-js-3.19.3.tgz#82315e9bbc6f2b25888858acd1fff8441035b77f" - integrity sha512-v3Xu+yuwBXisp6QYTcH4UbH+xYJXqnq2m/LtQVWKWzYc1iehYnLixoQDN9FH6/j9/oybfd6W9Ghwkl8+UMKTKQ== - -undici-types@~6.21.0: - version "6.21.0" - resolved "https://registry.yarnpkg.com/undici-types/-/undici-types-6.21.0.tgz#691d00af3909be93a7faa13be61b3a5b50ef12cb" - integrity sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ== - -undici-types@~7.16.0: - version "7.16.0" - resolved "https://registry.yarnpkg.com/undici-types/-/undici-types-7.16.0.tgz#ffccdff36aea4884cbfce9a750a0580224f58a46" - integrity sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw== - -universalify@^2.0.0: - version "2.0.1" - resolved "https://registry.yarnpkg.com/universalify/-/universalify-2.0.1.tgz#168efc2180964e6386d061e094df61afe239b18d" - integrity sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw== - -unpipe@~1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/unpipe/-/unpipe-1.0.0.tgz#b2bf4ee8514aae6165b4817829d21b2ef49904ec" - integrity sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ== - -update-browserslist-db@^1.2.0: - version "1.2.3" - resolved "https://registry.yarnpkg.com/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz#64d76db58713136acbeb4c49114366cc6cc2e80d" - integrity sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w== - dependencies: - escalade "^3.2.0" - picocolors "^1.1.1" - -uri-js@^4.2.2: - version "4.4.1" - resolved "https://registry.yarnpkg.com/uri-js/-/uri-js-4.4.1.tgz#9b1a52595225859e55f669d928f88c6c57f2a77e" - integrity sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg== - dependencies: - punycode "^2.1.0" - -util-deprecate@^1.0.1: - version "1.0.2" - resolved "https://registry.yarnpkg.com/util-deprecate/-/util-deprecate-1.0.2.tgz#450d4dc9fa70de732762fbd2d4a28981419a0ccf" - integrity sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw== - -v8-compile-cache-lib@^3.0.1: - version "3.0.1" - resolved "https://registry.yarnpkg.com/v8-compile-cache-lib/-/v8-compile-cache-lib-3.0.1.tgz#6336e8d71965cb3d35a1bbb7868445a7c05264bf" - integrity sha512-wa7YjyUGfNZngI/vtK0UHAN+lgDCxBPCylVXGp0zu59Fz5aiGtNXaq3DhIov063MorB+VfufLh3JlF2KdTK3xg== - -v8-to-istanbul@^9.0.1: - version "9.3.0" - resolved "https://registry.yarnpkg.com/v8-to-istanbul/-/v8-to-istanbul-9.3.0.tgz#b9572abfa62bd556c16d75fdebc1a411d5ff3175" - integrity sha512-kiGUalWN+rgBJ/1OHZsBtU4rXZOfj/7rKQxULKlIzwzQSvMJUUNgPwJEEh7gU6xEVxC0ahoOBvN2YI8GH6FNgA== - dependencies: - "@jridgewell/trace-mapping" "^0.3.12" - "@types/istanbul-lib-coverage" "^2.0.1" - convert-source-map "^2.0.0" - -vary@^1, vary@^1.1.2: - version "1.1.2" - resolved "https://registry.yarnpkg.com/vary/-/vary-1.1.2.tgz#2299f02c6ded30d4a5961b0b9f74524a18f634fc" - integrity sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg== - -walker@^1.0.8: - version "1.0.8" - resolved "https://registry.yarnpkg.com/walker/-/walker-1.0.8.tgz#bd498db477afe573dc04185f011d3ab8a8d7653f" - integrity sha512-ts/8E8l5b7kY0vlWLewOkDXMmPdLcVV4GmOQLyxuSswIJsweeFZtAsMF7k1Nszz+TYBQrlYRmzOnr398y1JemQ== - dependencies: - makeerror "1.0.12" - -which@^2.0.1: - version "2.0.2" - resolved "https://registry.yarnpkg.com/which/-/which-2.0.2.tgz#7c6a8dd0a636a0327e10b59c9286eee93f3f51b1" - integrity sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA== - dependencies: - isexe "^2.0.0" - -word-wrap@^1.2.5: - version "1.2.5" - resolved "https://registry.yarnpkg.com/word-wrap/-/word-wrap-1.2.5.tgz#d2c45c6dd4fbce621a66f136cbe328afd0410b34" - integrity sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA== - -wordwrap@^1.0.0: - version "1.0.0" - resolved "https://registry.yarnpkg.com/wordwrap/-/wordwrap-1.0.0.tgz#27584810891456a4171c8d0226441ade90cbcaeb" - integrity sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q== - -wrap-ansi@^6.2.0: - version "6.2.0" - resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-6.2.0.tgz#e9393ba07102e6c91a3b221478f0257cd2856e53" - integrity sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA== - dependencies: - ansi-styles "^4.0.0" - string-width "^4.1.0" - strip-ansi "^6.0.0" - -wrap-ansi@^7.0.0: - version "7.0.0" - resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-7.0.0.tgz#67e145cff510a6a6984bdf1152911d69d2eb9e43" - integrity sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q== - dependencies: - ansi-styles "^4.0.0" - string-width "^4.1.0" - strip-ansi "^6.0.0" - -wrappy@1: - version "1.0.2" - resolved "https://registry.yarnpkg.com/wrappy/-/wrappy-1.0.2.tgz#b5243d8f3ec1aa35f1364605bc0d1036e30ab69f" - integrity sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ== - -write-file-atomic@^4.0.2: - version "4.0.2" - resolved "https://registry.yarnpkg.com/write-file-atomic/-/write-file-atomic-4.0.2.tgz#a9df01ae5b77858a027fd2e80768ee433555fcfd" - integrity sha512-7KxauUdBmSdWnmpaGFg+ppNjKF8uNLry8LyzjauQDOVONfFLNKrKvQOxZ/VuTIcS/gge/YNahf5RIIQWTSarlg== - dependencies: - imurmurhash "^0.1.4" - signal-exit "^3.0.7" - -y18n@^5.0.5: - version "5.0.8" - resolved "https://registry.yarnpkg.com/y18n/-/y18n-5.0.8.tgz#7f4934d0f7ca8c56f95314939ddcd2dd91ce1d55" - integrity sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA== - -yallist@^3.0.2: - version "3.1.1" - resolved "https://registry.yarnpkg.com/yallist/-/yallist-3.1.1.tgz#dbb7daf9bfd8bac9ab45ebf602b8cbad0d5d08fd" - integrity sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g== - -yargs-parser@^21.1.1: - version "21.1.1" - resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-21.1.1.tgz#9096bceebf990d21bb31fa9516e0ede294a77d35" - integrity sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw== - -yargs@^17.3.1, yargs@^17.7.2: - version "17.7.2" - resolved "https://registry.yarnpkg.com/yargs/-/yargs-17.7.2.tgz#991df39aca675a192b816e1e0363f9d75d2aa269" - integrity sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w== - dependencies: - cliui "^8.0.1" - escalade "^3.1.1" - get-caller-file "^2.0.5" - require-directory "^2.1.1" - string-width "^4.2.3" - y18n "^5.0.5" - yargs-parser "^21.1.1" - -yn@3.1.1: - version "3.1.1" - resolved "https://registry.yarnpkg.com/yn/-/yn-3.1.1.tgz#1e87401a09d767c1d5eab26a6e4c185182d2eb50" - integrity sha512-Ux4ygGWsu2c7isFWe8Yu1YluJmqVhxqK2cLXNQA5AcC3QfbGNpM7fu0Y8b/z16pXLnFxZYvWhd3fhBY9DLmC6Q== - -yocto-queue@^0.1.0: - version "0.1.0" - resolved "https://registry.yarnpkg.com/yocto-queue/-/yocto-queue-0.1.0.tgz#0294eb3dee05028d31ee1a5fa2c556a6aaf10a1b" - integrity sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q== - -yoctocolors-cjs@^2.1.2: - version "2.1.3" - resolved "https://registry.yarnpkg.com/yoctocolors-cjs/-/yoctocolors-cjs-2.1.3.tgz#7e4964ea8ec422b7a40ac917d3a344cfd2304baa" - integrity sha512-U/PBtDf35ff0D8X8D0jfdzHYEPFxAI7jJlxZXwCSez5M3190m+QobIfh+sWDWSHMCWWJN2AWamkegn6vr6YBTw== - -zod-to-json-schema@^3.24.5, zod-to-json-schema@^3.24.6, zod-to-json-schema@^3.25.1: - version "3.25.1" - resolved "https://registry.yarnpkg.com/zod-to-json-schema/-/zod-to-json-schema-3.25.1.tgz#7f24962101a439ddade2bf1aeab3c3bfec7d84ba" - integrity sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA== - -zod-validation-error@^4.0.1: - version "4.0.2" - resolved "https://registry.yarnpkg.com/zod-validation-error/-/zod-validation-error-4.0.2.tgz#bc605eba49ce0fcd598c127fee1c236be3f22918" - integrity sha512-Q6/nZLe6jxuU80qb/4uJ4t5v2VEZ44lzQjPDhYJNztRQ4wyWc6VF3D3Kb/fAuPetZQnhS3hnajCf9CsWesghLQ== - -"zod@^3.25 || ^4.0": - version "4.3.5" - resolved "https://registry.yarnpkg.com/zod/-/zod-4.3.5.tgz#aeb269a6f9fc259b1212c348c7c5432aaa474d2a" - integrity sha512-k7Nwx6vuWx1IJ9Bjuf4Zt1PEllcwe7cls3VNzm4CQ1/hgtFUK2bRNG3rvnpPUhFjmqJKAKtjV576KnUkHocg/g== - -zod@^3.25.20, zod@^3.25.67: - version "3.25.76" - resolved "https://registry.yarnpkg.com/zod/-/zod-3.25.76.tgz#26841c3f6fd22a6a2760e7ccb719179768471e34" - integrity sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ== diff --git a/scripts/build b/scripts/build index 4716248d..7c739e87 100755 --- a/scripts/build +++ b/scripts/build @@ -49,9 +49,3 @@ if [ -e ./scripts/build-deno ] then ./scripts/build-deno fi -# build all sub-packages -for dir in packages/*; do - if [ -d "$dir" ]; then - (cd "$dir" && yarn install --pure-lockfile && yarn build) - fi -done diff --git a/scripts/build-all b/scripts/build-all deleted file mode 100755 index 4e5ac01f..00000000 --- a/scripts/build-all +++ /dev/null @@ -1,5 +0,0 @@ -#!/usr/bin/env bash - -# build-all is deprecated, use build instead - -bash ./scripts/build diff --git a/scripts/publish-packages.ts b/scripts/publish-packages.ts deleted file mode 100644 index 50e93fef..00000000 --- a/scripts/publish-packages.ts +++ /dev/null @@ -1,102 +0,0 @@ -/** - * Called from the `create-releases.yml` workflow with the output - * of the release please action as the first argument. - * - * Example JSON input: - * - * ```json - { - "releases_created": "true", - "release_created": "true", - "id": "137967744", - "name": "sdk: v0.14.5", - "tag_name": "sdk-v0.14.5", - "sha": "7cc2ba5c694e76a117f731d4cf0b06f8b8361f2e", - "body": "## 0.14.5 (2024-01-22)\n\n...", - "html_url": "https://github.com/$org/$repo/releases/tag/sdk-v0.14.5", - "draft": "false", - "upload_url": "https://uploads.github.com/repos/$org/$repo/releases/137967744/assets{?name,label}", - "path": ".", - "version": "0.14.5", - "major": "0", - "minor": "14", - "patch": "5", - "packages/additional-sdk--release_created": "true", - "packages/additional-sdk--id": "137967756", - "packages/additional-sdk--name": "additional-sdk: v0.5.2", - "packages/additional-sdk--tag_name": "additional-sdk-v0.5.2", - "packages/additional-sdk--sha": "7cc2ba5c694e76a117f731d4cf0b06f8b8361f2e", - "packages/additional-sdk--body": "## 0.5.2 (2024-01-22)\n\n...", - "packages/additional-sdk--html_url": "https://github.com/$org/$repo/releases/tag/additional-sdk-v0.5.2", - "packages/additional-sdk--draft": "false", - "packages/additional-sdk--upload_url": "https://uploads.github.com/repos/$org/$repo/releases/137967756/assets{?name,label}", - "packages/additional-sdk--path": "packages/additional-sdk", - "packages/additional-sdk--version": "0.5.2", - "packages/additional-sdk--major": "0", - "packages/additional-sdk--minor": "5", - "packages/additional-sdk--patch": "2", - "paths_released": "[\".\",\"packages/additional-sdk\"]" - } - ``` - */ - -import { execSync } from 'child_process'; -import path from 'path'; - -function main() { - const data = process.argv[2] ?? process.env['DATA']; - if (!data) { - throw new Error(`Usage: publish-packages.ts '{"json": "obj"}'`); - } - - const rootDir = path.join(__dirname, '..'); - console.log('root dir', rootDir); - console.log(`publish-packages called with ${data}`); - - const outputs = JSON.parse(data); - - const rawPaths = outputs.paths_released; - - if (!rawPaths) { - console.error(JSON.stringify(outputs, null, 2)); - throw new Error('Expected outputs to contain a truthy `paths_released` property'); - } - if (typeof rawPaths !== 'string') { - console.error(JSON.stringify(outputs, null, 2)); - throw new Error('Expected outputs `paths_released` property to be a JSON string'); - } - - const paths = JSON.parse(rawPaths); - if (!Array.isArray(paths)) { - console.error(JSON.stringify(outputs, null, 2)); - throw new Error('Expected outputs `paths_released` property to be an array'); - } - if (!paths.length) { - console.error(JSON.stringify(outputs, null, 2)); - throw new Error('Expected outputs `paths_released` property to contain at least one entry'); - } - - const publishScriptPath = path.join(rootDir, 'bin', 'publish-npm'); - console.log('Using publish script at', publishScriptPath); - - console.log('Ensuring root package is built'); - console.log(`$ yarn build`); - execSync(`yarn build`, { cwd: rootDir, encoding: 'utf8', stdio: 'inherit' }); - - for (const relPackagePath of paths) { - console.log('\n'); - - const packagePath = path.join(rootDir, relPackagePath); - console.log(`Publishing in directory: ${packagePath}`); - - console.log(`$ yarn install`); - execSync(`yarn install`, { cwd: packagePath, encoding: 'utf8', stdio: 'inherit' }); - - console.log(`$ bash ${publishScriptPath}`); - execSync(`bash ${publishScriptPath}`, { cwd: packagePath, encoding: 'utf8', stdio: 'inherit' }); - } - - console.log('Finished publishing packages'); -} - -main(); diff --git a/scripts/utils/make-dist-package-json.cjs b/scripts/utils/make-dist-package-json.cjs index 4d6634ea..7c24f56e 100644 --- a/scripts/utils/make-dist-package-json.cjs +++ b/scripts/utils/make-dist-package-json.cjs @@ -12,14 +12,6 @@ processExportMap(pkgJson.exports); for (const key of ['types', 'main', 'module']) { if (typeof pkgJson[key] === 'string') pkgJson[key] = pkgJson[key].replace(/^(\.\/)?dist\//, './'); } -// Fix bin paths if present -if (pkgJson.bin) { - for (const key in pkgJson.bin) { - if (typeof pkgJson.bin[key] === 'string') { - pkgJson.bin[key] = pkgJson.bin[key].replace(/^(\.\/)?dist\//, './'); - } - } -} delete pkgJson.devDependencies; delete pkgJson.scripts.prepack; From dcd655aa389a76d728842ca17437222cb67ed4b2 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 3 Sep 2026 08:27:47 +0000 Subject: [PATCH 004/232] feat(sitemap): add subdomain discovery Stainless-Generated-From: 2b1d7c110c19294a0e2b2075a44b6a019055dcd8 --- src/resources/web.ts | 17 ++++++++++++----- tests/api-resources/web.test.ts | 1 + 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 1950467b..8f4d97d5 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -200,11 +200,12 @@ export class Web extends APIResource { } /** - * Crawl an entire website's sitemap and return all discovered page URLs. Pass - * `search` to have the crawled sitemap filtered down to the pages about a phrase - * (for example `pricing and plans` or `api authentication docs`), most relevant - * first — a searched crawl scans the whole sitemap and costs 2 credits instead - * of 1. + * Crawl an entire website's sitemap and return all discovered page URLs. Set + * `includeSubdomains=true` to also discover public pages and sitemaps on child + * hosts such as `docs.example.com` or `brand.example.com`. Pass `search` to have + * the discovered URLs filtered down to the pages about a phrase (for example + * `pricing and plans` or `api authentication docs`), most relevant first — a + * searched crawl scans the whole sitemap and costs 2 credits instead of 1. * * @example * ```ts @@ -4669,6 +4670,12 @@ export interface WebWebScrapeSitemapParams { */ headers?: { [key: string]: string }; + /** + * When true, discover and include public pages and sitemaps on subdomains of the + * requested domain. Defaults to false. + */ + includeSubdomains?: boolean; + /** * Maximum number of links to return from the sitemap crawl. Defaults to 10,000. * Minimum is 1, maximum is 100,000. diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index ab05d344..a513bb93 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -395,6 +395,7 @@ describe('resource web', () => { const response = await client.web.webScrapeSitemap({ domain: 'xxx', headers: { foo: 'J!' }, + includeSubdomains: true, maxLinks: 1, search: 'help center and troubleshooting articles', sitemapUrl: 'https://example.com', From 2b1d7c110c19294a0e2b2075a44b6a019055dcd8 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 3 Sep 2026 08:27:47 +0000 Subject: [PATCH 005/232] seal --- src/resources/web.ts | 17 ++++++++++++----- tests/api-resources/web.test.ts | 1 + 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 1950467b..8f4d97d5 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -200,11 +200,12 @@ export class Web extends APIResource { } /** - * Crawl an entire website's sitemap and return all discovered page URLs. Pass - * `search` to have the crawled sitemap filtered down to the pages about a phrase - * (for example `pricing and plans` or `api authentication docs`), most relevant - * first — a searched crawl scans the whole sitemap and costs 2 credits instead - * of 1. + * Crawl an entire website's sitemap and return all discovered page URLs. Set + * `includeSubdomains=true` to also discover public pages and sitemaps on child + * hosts such as `docs.example.com` or `brand.example.com`. Pass `search` to have + * the discovered URLs filtered down to the pages about a phrase (for example + * `pricing and plans` or `api authentication docs`), most relevant first — a + * searched crawl scans the whole sitemap and costs 2 credits instead of 1. * * @example * ```ts @@ -4669,6 +4670,12 @@ export interface WebWebScrapeSitemapParams { */ headers?: { [key: string]: string }; + /** + * When true, discover and include public pages and sitemaps on subdomains of the + * requested domain. Defaults to false. + */ + includeSubdomains?: boolean; + /** * Maximum number of links to return from the sitemap crawl. Defaults to 10,000. * Minimum is 1, maximum is 100,000. diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index ab05d344..a513bb93 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -395,6 +395,7 @@ describe('resource web', () => { const response = await client.web.webScrapeSitemap({ domain: 'xxx', headers: { foo: 'J!' }, + includeSubdomains: true, maxLinks: 1, search: 'help center and troubleshooting articles', sitemapUrl: 'https://example.com', From 22d15e373d9b5a0b6774584ed283114e8ad22704 Mon Sep 17 00:00:00 2001 From: contextualbeer Date: Thu, 3 Sep 2026 10:29:39 +0200 Subject: [PATCH 006/232] release: 2.15.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 12 ++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 15 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index b9c017b3..96a8c91d 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.14.0" + ".": "2.15.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 9509077f..69878f88 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## [2.15.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.14.0...v2.15.0) (2026-09-03) + + +### Features + +* **sitemap:** add subdomain discovery ([dcd655a](https://github.com/context-dot-dev/context-typescript-sdk/commit/dcd655aa389a76d728842ca17437222cb67ed4b2)) + + +### Bug Fixes + +* **openapi:** strip empty-object defaults from the generated spec ([01a5153](https://github.com/context-dot-dev/context-typescript-sdk/commit/01a515383a6d31d619cb1217911d659c9a52ff21)) + ## [2.14.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.13.0...v2.14.0) (2026-08-27) diff --git a/package.json b/package.json index ee79d4ce..5fa53c5f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.14.0", + "version": "2.15.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 22e51840..ba989f03 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.14.0'; // x-release-please-version +export const VERSION = '2.15.0'; // x-release-please-version From a6346c5e8cb792e02a23766e7b204913cbf88650 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 3 Sep 2026 12:30:07 +0000 Subject: [PATCH 007/232] seal --- .release-please-manifest.json | 2 +- CHANGELOG.md | 12 ++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 15 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index b9c017b3..96a8c91d 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.14.0" + ".": "2.15.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 9509077f..69878f88 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## [2.15.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.14.0...v2.15.0) (2026-09-03) + + +### Features + +* **sitemap:** add subdomain discovery ([dcd655a](https://github.com/context-dot-dev/context-typescript-sdk/commit/dcd655aa389a76d728842ca17437222cb67ed4b2)) + + +### Bug Fixes + +* **openapi:** strip empty-object defaults from the generated spec ([01a5153](https://github.com/context-dot-dev/context-typescript-sdk/commit/01a515383a6d31d619cb1217911d659c9a52ff21)) + ## [2.14.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.13.0...v2.14.0) (2026-08-27) diff --git a/package.json b/package.json index ee79d4ce..5fa53c5f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.14.0", + "version": "2.15.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 22e51840..ba989f03 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.14.0'; // x-release-please-version +export const VERSION = '2.15.0'; // x-release-please-version From da20ddbcc80c966aaed048ddb3bef70e5c2d8e8e Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 7 Sep 2026 22:01:00 +0000 Subject: [PATCH 008/232] feat(webhooks): add configurable retries and manual replay Stainless-Generated-From: 6a11381d39a85c9f4d81957bce061678fd1794c3 --- .stats.yml | 2 +- api.md | 24 ++ src/client.ts | 5 + src/resources/batch.ts | 31 +- src/resources/index.ts | 1 + src/resources/monitors.ts | 65 +++ src/resources/webhooks.ts | 3 + src/resources/webhooks/deliveries.ts | 406 ++++++++++++++++++ src/resources/webhooks/index.ts | 16 + src/resources/webhooks/webhooks.ts | 56 +++ tests/api-resources/batch.test.ts | 4 + tests/api-resources/monitors.test.ts | 6 +- .../api-resources/webhooks/deliveries.test.ts | 121 ++++++ 13 files changed, 737 insertions(+), 3 deletions(-) create mode 100644 src/resources/webhooks.ts create mode 100644 src/resources/webhooks/deliveries.ts create mode 100644 src/resources/webhooks/index.ts create mode 100644 src/resources/webhooks/webhooks.ts create mode 100644 tests/api-resources/webhooks/deliveries.test.ts diff --git a/.stats.yml b/.stats.yml index 1fd29914..c7c071bd 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 41 +configured_endpoints: 45 diff --git a/api.md b/api.md index 725e8f12..8c1b1678 100644 --- a/api.md +++ b/api.md @@ -145,6 +145,30 @@ Methods: - client.batch.getResults(batchID, { ...params }) -> BatchGetResultsResponse - client.batch.submit({ ...params }) -> BatchSubmitResponse +# Webhooks + +Types: + +- RetryConfig + +## Deliveries + +Types: + +- Attempt +- Delivery +- DeliveryRetrieveResponse +- DeliveryListResponse +- DeliveryListAttemptsResponse +- DeliveryRetryResponse + +Methods: + +- client.webhooks.deliveries.retrieve(deliveryID, { ...params }) -> DeliveryRetrieveResponse +- client.webhooks.deliveries.list({ ...params }) -> DeliveryListResponse +- client.webhooks.deliveries.listAttempts(deliveryID, { ...params }) -> DeliveryListAttemptsResponse +- client.webhooks.deliveries.retry(deliveryID, { ...params }) -> DeliveryRetryResponse + # People Types: diff --git a/src/client.ts b/src/client.ts index 7df8cdc3..c9d1be53 100644 --- a/src/client.ts +++ b/src/client.ts @@ -110,6 +110,7 @@ import { WebWebScrapeSitemapParams, WebWebScrapeSitemapResponse, } from './resources/web'; +import { RetryConfig, Webhooks } from './resources/webhooks/webhooks'; import { type Fetch } from './internal/builtin-types'; import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers'; import { FinalRequestOptions, RequestOptions } from './internal/request-options'; @@ -841,6 +842,7 @@ export class ContextDev { * Scrape many pages or crawl a site asynchronously. */ batch: API.Batch = new API.Batch(this); + webhooks: API.Webhooks = new API.Webhooks(this); people: API.People = new API.People(this); /** * Search live first-party RSS and free historical news data by company identity. @@ -856,6 +858,7 @@ ContextDev.Industry = Industry; ContextDev.Utility = Utility; ContextDev.Monitors = Monitors; ContextDev.Batch = Batch; +ContextDev.Webhooks = Webhooks; ContextDev.People = People; ContextDev.News = News; @@ -969,6 +972,8 @@ export declare namespace ContextDev { type BatchSubmitParams as BatchSubmitParams, }; + export { Webhooks as Webhooks, type RetryConfig as RetryConfig }; + export { People as People, type PersonEnrichResponse as PersonEnrichResponse, diff --git a/src/resources/batch.ts b/src/resources/batch.ts index a7dd731c..094dc70b 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -2,6 +2,7 @@ import { APIResource } from '../core/resource'; import * as BatchAPI from './batch'; +import * as WebhooksAPI from './webhooks/webhooks'; import { APIPromise } from '../core/api-promise'; import { buildHeaders } from '../internal/headers'; import { RequestOptions } from '../internal/request-options'; @@ -328,6 +329,12 @@ export interface BatchRetrieveResponse { * API key usage for this request. */ key_metadata?: BatchRetrieveResponse.KeyMetadata; + + /** + * Retained completion delivery ID. Inspect or retry it through + * /webhooks/deliveries/{delivery_id}. Present once the delivery has been retained. + */ + webhook_delivery_id?: string; } export namespace BatchRetrieveResponse { @@ -1334,7 +1341,14 @@ export interface BatchSubmitParams { tags?: Array; /** - * Body param: URL notified when the batch finishes. + * Body param: Completion webhook settings. Cannot be combined with webhookUrl. + * Omitting retry preserves legacy delivery; retry: {} opts into durable retries. + */ + webhook?: BatchSubmitParams.Webhook; + + /** + * Body param: Legacy URL notified when the batch finishes. Preserves one + * best-effort attempt. Cannot be combined with webhook. */ webhookUrl?: string; @@ -2883,6 +2897,21 @@ export namespace BatchSubmitParams { } } } + + /** + * Completion webhook settings. Cannot be combined with webhookUrl. Omitting retry + * preserves legacy delivery; retry: {} opts into durable retries. + */ + export interface Webhook { + url: string; + + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry?: WebhooksAPI.RetryConfig; + } } export declare namespace Batch { diff --git a/src/resources/index.ts b/src/resources/index.ts index 93e0adeb..b64a0897 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -93,3 +93,4 @@ export { type WebWebScrapeMdParams, type WebWebScrapeSitemapParams, } from './web'; +export { Webhooks, type RetryConfig } from './webhooks/webhooks'; diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index e2f6302d..14c8f949 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -2,6 +2,7 @@ import { APIResource } from '../core/resource'; import * as MonitorsAPI from './monitors'; +import * as WebhooksAPI from './webhooks/webhooks'; import { APIPromise } from '../core/api-promise'; import { RequestOptions } from '../internal/request-options'; import { path } from '../internal/utils/path'; @@ -251,6 +252,12 @@ export interface WebhookDelivery { * the URL failed the public-endpoint safety check. */ status: 'delivered' | 'rejected' | 'failed' | 'skipped_unsafe_url'; + + /** + * Retained delivery ID for GET /webhooks/deliveries/{delivery_id}. Omitted for + * historical or unretained deliveries. + */ + delivery_id?: string; } export namespace WebhookDelivery { @@ -580,6 +587,13 @@ export namespace MonitorCreateResponse { */ events?: Array<'change.detected' | 'run.completed'>; + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry?: WebhooksAPI.RetryConfig; + /** * Signing secret used to verify webhook authenticity. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over @@ -929,6 +943,13 @@ export namespace MonitorRetrieveResponse { */ events?: Array<'change.detected' | 'run.completed'>; + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry?: WebhooksAPI.RetryConfig; + /** * Signing secret used to verify webhook authenticity. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over @@ -1278,6 +1299,13 @@ export namespace MonitorUpdateResponse { */ events?: Array<'change.detected' | 'run.completed'>; + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry?: WebhooksAPI.RetryConfig; + /** * Signing secret used to verify webhook authenticity. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over @@ -1627,6 +1655,13 @@ export namespace MonitorListResponse { */ events?: Array<'change.detected' | 'run.completed'>; + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry?: WebhooksAPI.RetryConfig; + /** * Signing secret used to verify webhook authenticity. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over @@ -1844,6 +1879,14 @@ export namespace MonitorListAccountRunsResponse { * attempted, including historical runs created before delivery tracking was added. */ webhook_delivery?: MonitorsAPI.WebhookDelivery; + + /** + * Retained webhook deliveries for this run. Inspect their live state and attempt + * history through /webhooks/deliveries. With webhook.retry configured, delivery is + * asynchronous and the legacy webhook_delivery/webhook_deliveries outcomes are + * omitted. + */ + webhook_delivery_ids?: Array; } export namespace Data { @@ -1980,6 +2023,14 @@ export namespace MonitorListRunsResponse { * attempted, including historical runs created before delivery tracking was added. */ webhook_delivery?: MonitorsAPI.WebhookDelivery; + + /** + * Retained webhook deliveries for this run. Inspect their live state and attempt + * history through /webhooks/deliveries. With webhook.retry configured, delivery is + * asynchronous and the legacy webhook_delivery/webhook_deliveries outcomes are + * omitted. + */ + webhook_delivery_ids?: Array; } export namespace Data { @@ -2290,6 +2341,13 @@ export namespace MonitorCreateParams { * to `["change.detected"]` when omitted. */ events?: Array<'change.detected' | 'run.completed'>; + + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry?: WebhooksAPI.RetryConfig; } } @@ -2485,6 +2543,13 @@ export namespace MonitorUpdateParams { * to `["change.detected"]` when omitted. */ events?: Array<'change.detected' | 'run.completed'>; + + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry?: WebhooksAPI.RetryConfig; } } diff --git a/src/resources/webhooks.ts b/src/resources/webhooks.ts new file mode 100644 index 00000000..8aad965f --- /dev/null +++ b/src/resources/webhooks.ts @@ -0,0 +1,3 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export * from './webhooks/index'; diff --git a/src/resources/webhooks/deliveries.ts b/src/resources/webhooks/deliveries.ts new file mode 100644 index 00000000..9f5bf77d --- /dev/null +++ b/src/resources/webhooks/deliveries.ts @@ -0,0 +1,406 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../../core/resource'; +import * as DeliveriesAPI from './deliveries'; +import * as WebhooksAPI from './webhooks'; +import { APIPromise } from '../../core/api-promise'; +import { buildHeaders } from '../../internal/headers'; +import { RequestOptions } from '../../internal/request-options'; +import { path } from '../../internal/utils/path'; + +/** + * Inspect and retry batch and monitor webhook deliveries without rerunning the underlying work. + */ +export class Deliveries extends APIResource { + /** + * Get the live status, retry policy, latest attempt, and replay expiration for a + * retained delivery. Use the attempts endpoint for its complete paginated history. + * This endpoint costs no credits. + * + * @example + * ```ts + * const delivery = await client.webhooks.deliveries.retrieve( + * 'whd_210b9798eb53baa4e69d31c1071cf03d', + * ); + * ``` + */ + retrieve( + deliveryID: string, + query: DeliveryRetrieveParams | null | undefined = {}, + options?: RequestOptions, + ): APIPromise { + return this._client.get(path`/webhooks/deliveries/${deliveryID}`, { query, ...options }); + } + + /** + * List retained batch and monitor webhook deliveries for your organization, newest + * first. Filter by at most one of batch_id, monitor_id, or run_id, optionally + * combined with status. Historical events without retained payloads are not + * listed. This endpoint costs no credits. + * + * @example + * ```ts + * const deliveries = await client.webhooks.deliveries.list(); + * ``` + */ + list( + query: DeliveryListParams | null | undefined = {}, + options?: RequestOptions, + ): APIPromise { + return this._client.get('/webhooks/deliveries', { query, ...options }); + } + + /** + * List individual HTTP attempts for a delivery, newest first, including their + * destination, timestamps, HTTP status, and error. An interrupted attempt may have + * reached the endpoint even when its outcome is unknown. This endpoint costs no + * credits. + * + * @example + * ```ts + * const response = + * await client.webhooks.deliveries.listAttempts( + * 'whd_210b9798eb53baa4e69d31c1071cf03d', + * ); + * ``` + */ + listAttempts( + deliveryID: string, + query: DeliveryListAttemptsParams | null | undefined = {}, + options?: RequestOptions, + ): APIPromise { + return this._client.get(path`/webhooks/deliveries/${deliveryID}/attempts`, { query, ...options }); + } + + /** + * Queue an immediate attempt without rerunning or billing the underlying batch or + * monitor. A waiting retry is brought forward. A failed delivery gets one + * additional attempt without restarting its automatic retry budget. Set force: + * true to resend an acknowledged delivery. An in-progress attempt cannot be + * duplicated. The stored event body, event ID, and creation time remain unchanged; + * each attempt receives a fresh signature. Monitor retries use the current URL and + * secret; removing the webhook cancels pending deliveries. Batch result URLs in + * old payloads may have expired: retrieve the batch to get fresh URLs. Replay is + * available for seven days. A successful attempt cancels remaining automatic + * retries. Idempotency-Key is scoped to your organization and retained with the + * delivery metadata; repeating the same key and input returns the original + * accepted response. + * + * @example + * ```ts + * const response = await client.webhooks.deliveries.retry( + * 'whd_210b9798eb53baa4e69d31c1071cf03d', + * ); + * ``` + */ + retry( + deliveryID: string, + params: DeliveryRetryParams | null | undefined = {}, + options?: RequestOptions, + ): APIPromise { + const { 'Idempotency-Key': idempotencyKey, ...body } = params ?? {}; + return this._client.post(path`/webhooks/deliveries/${deliveryID}/retry`, { + body, + ...options, + headers: buildHeaders([ + { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) }, + options?.headers, + ]), + }); + } +} + +export interface Attempt { + id: string; + + attempt: number; + + completed_at: string | null; + + error: Attempt.Error | null; + + http_status: number | null; + + started_at: string; + + trigger: 'initial' | 'automatic' | 'manual'; + + url: string; +} + +export namespace Attempt { + export interface Error { + code: string; + + message: string; + } +} + +export interface Delivery { + id: string; + + /** + * Number of delivery attempts started, including any attempt in progress. + */ + attempt_count: number; + + created_at: string; + + /** + * Most recent successful acknowledgment; retained if a later forced resend fails. + */ + delivered_at: string | null; + + event: 'batch.completed' | 'batch.failed' | 'batch.cancelled' | 'change.detected' | 'run.completed'; + + /** + * Stable event ID. Unchanged across automatic and manual attempts; use it to + * deduplicate events. + */ + event_id: string; + + last_attempt: Delivery.LastAttempt; + + last_error: Delivery.LastError | null; + + next_attempt_at: string | null; + + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry: WebhooksAPI.RetryConfig; + + /** + * Seven days after event creation. Manual retries after this time return 410. + * Delivery and attempt metadata remain available for up to 30 days. + */ + retry_expires_at: string; + + source: Delivery.UnionMember0 | Delivery.UnionMember1; + + status: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; + + /** + * Destination recorded for this delivery. Each attempt records the URL it used. + * Monitor retries use the currently configured URL and signing secret. + */ + url: string; +} + +export namespace Delivery { + export interface LastAttempt extends DeliveriesAPI.Attempt {} + + export interface LastError { + code: string; + + message: string; + } + + export interface UnionMember0 { + batch_id: string; + + type: 'batch'; + } + + export interface UnionMember1 { + monitor_id: string; + + run_id: string; + + type: 'monitor'; + } +} + +export interface DeliveryRetrieveResponse extends Delivery { + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + key_metadata?: DeliveryRetrieveResponse.KeyMetadata; +} + +export namespace DeliveryRetrieveResponse { + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + export interface KeyMetadata { + /** + * The number of credits consumed by this request. + */ + credits_consumed: number; + + /** + * The number of credits remaining for your organization after this request. + */ + credits_remaining: number; + } +} + +export interface DeliveryListResponse { + data: Array; + + has_more: boolean; + + next_cursor: string | null; + + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + key_metadata?: DeliveryListResponse.KeyMetadata; +} + +export namespace DeliveryListResponse { + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + export interface KeyMetadata { + /** + * The number of credits consumed by this request. + */ + credits_consumed: number; + + /** + * The number of credits remaining for your organization after this request. + */ + credits_remaining: number; + } +} + +export interface DeliveryListAttemptsResponse { + data: Array; + + has_more: boolean; + + next_cursor: string | null; + + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + key_metadata?: DeliveryListAttemptsResponse.KeyMetadata; +} + +export namespace DeliveryListAttemptsResponse { + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + export interface KeyMetadata { + /** + * The number of credits consumed by this request. + */ + credits_consumed: number; + + /** + * The number of credits remaining for your organization after this request. + */ + credits_remaining: number; + } +} + +export interface DeliveryRetryResponse extends Delivery { + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + key_metadata?: DeliveryRetryResponse.KeyMetadata; +} + +export namespace DeliveryRetryResponse { + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + export interface KeyMetadata { + /** + * The number of credits consumed by this request. + */ + credits_consumed: number; + + /** + * The number of credits remaining for your organization after this request. + */ + credits_remaining: number; + } +} + +export interface DeliveryRetrieveParams { + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are + * recorded on the request's usage log and can be used to filter usage on the + * dashboard usage page. Up to 20 tags, each 1-50 characters. + */ + tags?: Array; +} + +export interface DeliveryListParams { + batch_id?: string; + + cursor?: string; + + limit?: number; + + monitor_id?: string; + + run_id?: string; + + status?: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; + + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are + * recorded on the request's usage log and can be used to filter usage on the + * dashboard usage page. Up to 20 tags, each 1-50 characters. + */ + tags?: Array; +} + +export interface DeliveryListAttemptsParams { + cursor?: string; + + limit?: number; + + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are + * recorded on the request's usage log and can be used to filter usage on the + * dashboard usage page. Up to 20 tags, each 1-50 characters. + */ + tags?: Array; +} + +export interface DeliveryRetryParams { + /** + * Body param + */ + force?: boolean; + + /** + * Body param: Optional tags for tracking usage. Up to 20 tags, each 1 to 50 + * characters. + */ + tags?: Array; + + /** + * Header param + */ + 'Idempotency-Key'?: string; +} + +export declare namespace Deliveries { + export { + type Attempt as Attempt, + type Delivery as Delivery, + type DeliveryRetrieveResponse as DeliveryRetrieveResponse, + type DeliveryListResponse as DeliveryListResponse, + type DeliveryListAttemptsResponse as DeliveryListAttemptsResponse, + type DeliveryRetryResponse as DeliveryRetryResponse, + type DeliveryRetrieveParams as DeliveryRetrieveParams, + type DeliveryListParams as DeliveryListParams, + type DeliveryListAttemptsParams as DeliveryListAttemptsParams, + type DeliveryRetryParams as DeliveryRetryParams, + }; +} diff --git a/src/resources/webhooks/index.ts b/src/resources/webhooks/index.ts new file mode 100644 index 00000000..19f0233b --- /dev/null +++ b/src/resources/webhooks/index.ts @@ -0,0 +1,16 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export { + Deliveries, + type Attempt, + type Delivery, + type DeliveryRetrieveResponse, + type DeliveryListResponse, + type DeliveryListAttemptsResponse, + type DeliveryRetryResponse, + type DeliveryRetrieveParams, + type DeliveryListParams, + type DeliveryListAttemptsParams, + type DeliveryRetryParams, +} from './deliveries'; +export { Webhooks, type RetryConfig } from './webhooks'; diff --git a/src/resources/webhooks/webhooks.ts b/src/resources/webhooks/webhooks.ts new file mode 100644 index 00000000..2b985e57 --- /dev/null +++ b/src/resources/webhooks/webhooks.ts @@ -0,0 +1,56 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../../core/resource'; +import * as DeliveriesAPI from './deliveries'; +import { + Attempt, + Deliveries, + Delivery, + DeliveryListAttemptsParams, + DeliveryListAttemptsResponse, + DeliveryListParams, + DeliveryListResponse, + DeliveryRetrieveParams, + DeliveryRetrieveResponse, + DeliveryRetryParams, + DeliveryRetryResponse, +} from './deliveries'; + +export class Webhooks extends APIResource { + deliveries: DeliveriesAPI.Deliveries = new DeliveriesAPI.Deliveries(this._client); +} + +/** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ +export interface RetryConfig { + /** + * Wait in seconds after each failed attempt. The first attempt is immediate. At + * most 10 delays, each 1–86400 seconds, totaling at most 72 hours. Small jitter is + * added automatically. An empty array disables automatic retries; manual retries + * remain available. + */ + delays_seconds?: Array; +} + +Webhooks.Deliveries = Deliveries; + +export declare namespace Webhooks { + export { type RetryConfig as RetryConfig }; + + export { + Deliveries as Deliveries, + type Attempt as Attempt, + type Delivery as Delivery, + type DeliveryRetrieveResponse as DeliveryRetrieveResponse, + type DeliveryListResponse as DeliveryListResponse, + type DeliveryListAttemptsResponse as DeliveryListAttemptsResponse, + type DeliveryRetryResponse as DeliveryRetryResponse, + type DeliveryRetrieveParams as DeliveryRetrieveParams, + type DeliveryListParams as DeliveryListParams, + type DeliveryListAttemptsParams as DeliveryListAttemptsParams, + type DeliveryRetryParams as DeliveryRetryParams, + }; +} diff --git a/tests/api-resources/batch.test.ts b/tests/api-resources/batch.test.ts index 737d2843..0d04e037 100644 --- a/tests/api-resources/batch.test.ts +++ b/tests/api-resources/batch.test.ts @@ -162,6 +162,10 @@ describe('resource batch', () => { mode: 'scrape', }, tags: ['docs', 'competitor'], + webhook: { + url: 'https://example.com', + retry: { delays_seconds: [10, 60, 300, 1800, 7200, 21600, 57600] }, + }, webhookUrl: 'webhookUrl', 'Idempotency-Key': 'Idempotency-Key', }); diff --git a/tests/api-resources/monitors.test.ts b/tests/api-resources/monitors.test.ts index cd7c9604..aa8f3b4a 100644 --- a/tests/api-resources/monitors.test.ts +++ b/tests/api-resources/monitors.test.ts @@ -42,7 +42,11 @@ describe('resource monitors', () => { unit: 'hours', }, tags: ['pricing', 'competitor'], - webhook: { url: 'https://example.com/webhook', events: ['change.detected', 'run.completed'] }, + webhook: { + url: 'https://example.com/webhook', + events: ['change.detected', 'run.completed'], + retry: { delays_seconds: [10, 60, 300, 1800, 7200, 21600, 57600] }, + }, }); }); diff --git a/tests/api-resources/webhooks/deliveries.test.ts b/tests/api-resources/webhooks/deliveries.test.ts new file mode 100644 index 00000000..0ccc75c4 --- /dev/null +++ b/tests/api-resources/webhooks/deliveries.test.ts @@ -0,0 +1,121 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import ContextDev from 'context.dev'; + +const client = new ContextDev({ + apiKey: 'My API Key', + baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', +}); + +describe('resource deliveries', () => { + // Mock server tests are disabled + test.skip('retrieve', async () => { + const responsePromise = client.webhooks.deliveries.retrieve('whd_210b9798eb53baa4e69d31c1071cf03d'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('retrieve: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.webhooks.deliveries.retrieve( + 'whd_210b9798eb53baa4e69d31c1071cf03d', + { tags: ['production', 'team-alpha'] }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(ContextDev.NotFoundError); + }); + + // Mock server tests are disabled + test.skip('list', async () => { + const responsePromise = client.webhooks.deliveries.list(); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('list: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.webhooks.deliveries.list( + { + batch_id: 'batch_id', + cursor: 'whd_210b9798eb53baa4e69d31c1071cf03d', + limit: 1, + monitor_id: 'monitor_id', + run_id: 'run_id', + status: 'pending', + tags: ['production', 'team-alpha'], + }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(ContextDev.NotFoundError); + }); + + // Mock server tests are disabled + test.skip('listAttempts', async () => { + const responsePromise = client.webhooks.deliveries.listAttempts('whd_210b9798eb53baa4e69d31c1071cf03d'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('listAttempts: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.webhooks.deliveries.listAttempts( + 'whd_210b9798eb53baa4e69d31c1071cf03d', + { + cursor: 'wha_210b9798eb53baa4e69d31c1071cf03d', + limit: 1, + tags: ['production', 'team-alpha'], + }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(ContextDev.NotFoundError); + }); + + // Mock server tests are disabled + test.skip('retry', async () => { + const responsePromise = client.webhooks.deliveries.retry('whd_210b9798eb53baa4e69d31c1071cf03d'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('retry: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.webhooks.deliveries.retry( + 'whd_210b9798eb53baa4e69d31c1071cf03d', + { + force: true, + tags: ['production', 'team-alpha'], + 'Idempotency-Key': 'Idempotency-Key', + }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(ContextDev.NotFoundError); + }); +}); From 6a11381d39a85c9f4d81957bce061678fd1794c3 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 7 Sep 2026 22:01:00 +0000 Subject: [PATCH 009/232] seal --- .stats.yml | 2 +- api.md | 24 ++ src/client.ts | 5 + src/resources/batch.ts | 31 +- src/resources/index.ts | 1 + src/resources/monitors.ts | 65 +++ src/resources/webhooks.ts | 3 + src/resources/webhooks/deliveries.ts | 406 ++++++++++++++++++ src/resources/webhooks/index.ts | 16 + src/resources/webhooks/webhooks.ts | 56 +++ tests/api-resources/batch.test.ts | 4 + tests/api-resources/monitors.test.ts | 6 +- .../api-resources/webhooks/deliveries.test.ts | 121 ++++++ 13 files changed, 737 insertions(+), 3 deletions(-) create mode 100644 src/resources/webhooks.ts create mode 100644 src/resources/webhooks/deliveries.ts create mode 100644 src/resources/webhooks/index.ts create mode 100644 src/resources/webhooks/webhooks.ts create mode 100644 tests/api-resources/webhooks/deliveries.test.ts diff --git a/.stats.yml b/.stats.yml index 1fd29914..c7c071bd 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 41 +configured_endpoints: 45 diff --git a/api.md b/api.md index 725e8f12..8c1b1678 100644 --- a/api.md +++ b/api.md @@ -145,6 +145,30 @@ Methods: - client.batch.getResults(batchID, { ...params }) -> BatchGetResultsResponse - client.batch.submit({ ...params }) -> BatchSubmitResponse +# Webhooks + +Types: + +- RetryConfig + +## Deliveries + +Types: + +- Attempt +- Delivery +- DeliveryRetrieveResponse +- DeliveryListResponse +- DeliveryListAttemptsResponse +- DeliveryRetryResponse + +Methods: + +- client.webhooks.deliveries.retrieve(deliveryID, { ...params }) -> DeliveryRetrieveResponse +- client.webhooks.deliveries.list({ ...params }) -> DeliveryListResponse +- client.webhooks.deliveries.listAttempts(deliveryID, { ...params }) -> DeliveryListAttemptsResponse +- client.webhooks.deliveries.retry(deliveryID, { ...params }) -> DeliveryRetryResponse + # People Types: diff --git a/src/client.ts b/src/client.ts index 7df8cdc3..c9d1be53 100644 --- a/src/client.ts +++ b/src/client.ts @@ -110,6 +110,7 @@ import { WebWebScrapeSitemapParams, WebWebScrapeSitemapResponse, } from './resources/web'; +import { RetryConfig, Webhooks } from './resources/webhooks/webhooks'; import { type Fetch } from './internal/builtin-types'; import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers'; import { FinalRequestOptions, RequestOptions } from './internal/request-options'; @@ -841,6 +842,7 @@ export class ContextDev { * Scrape many pages or crawl a site asynchronously. */ batch: API.Batch = new API.Batch(this); + webhooks: API.Webhooks = new API.Webhooks(this); people: API.People = new API.People(this); /** * Search live first-party RSS and free historical news data by company identity. @@ -856,6 +858,7 @@ ContextDev.Industry = Industry; ContextDev.Utility = Utility; ContextDev.Monitors = Monitors; ContextDev.Batch = Batch; +ContextDev.Webhooks = Webhooks; ContextDev.People = People; ContextDev.News = News; @@ -969,6 +972,8 @@ export declare namespace ContextDev { type BatchSubmitParams as BatchSubmitParams, }; + export { Webhooks as Webhooks, type RetryConfig as RetryConfig }; + export { People as People, type PersonEnrichResponse as PersonEnrichResponse, diff --git a/src/resources/batch.ts b/src/resources/batch.ts index a7dd731c..094dc70b 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -2,6 +2,7 @@ import { APIResource } from '../core/resource'; import * as BatchAPI from './batch'; +import * as WebhooksAPI from './webhooks/webhooks'; import { APIPromise } from '../core/api-promise'; import { buildHeaders } from '../internal/headers'; import { RequestOptions } from '../internal/request-options'; @@ -328,6 +329,12 @@ export interface BatchRetrieveResponse { * API key usage for this request. */ key_metadata?: BatchRetrieveResponse.KeyMetadata; + + /** + * Retained completion delivery ID. Inspect or retry it through + * /webhooks/deliveries/{delivery_id}. Present once the delivery has been retained. + */ + webhook_delivery_id?: string; } export namespace BatchRetrieveResponse { @@ -1334,7 +1341,14 @@ export interface BatchSubmitParams { tags?: Array; /** - * Body param: URL notified when the batch finishes. + * Body param: Completion webhook settings. Cannot be combined with webhookUrl. + * Omitting retry preserves legacy delivery; retry: {} opts into durable retries. + */ + webhook?: BatchSubmitParams.Webhook; + + /** + * Body param: Legacy URL notified when the batch finishes. Preserves one + * best-effort attempt. Cannot be combined with webhook. */ webhookUrl?: string; @@ -2883,6 +2897,21 @@ export namespace BatchSubmitParams { } } } + + /** + * Completion webhook settings. Cannot be combined with webhookUrl. Omitting retry + * preserves legacy delivery; retry: {} opts into durable retries. + */ + export interface Webhook { + url: string; + + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry?: WebhooksAPI.RetryConfig; + } } export declare namespace Batch { diff --git a/src/resources/index.ts b/src/resources/index.ts index 93e0adeb..b64a0897 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -93,3 +93,4 @@ export { type WebWebScrapeMdParams, type WebWebScrapeSitemapParams, } from './web'; +export { Webhooks, type RetryConfig } from './webhooks/webhooks'; diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index e2f6302d..14c8f949 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -2,6 +2,7 @@ import { APIResource } from '../core/resource'; import * as MonitorsAPI from './monitors'; +import * as WebhooksAPI from './webhooks/webhooks'; import { APIPromise } from '../core/api-promise'; import { RequestOptions } from '../internal/request-options'; import { path } from '../internal/utils/path'; @@ -251,6 +252,12 @@ export interface WebhookDelivery { * the URL failed the public-endpoint safety check. */ status: 'delivered' | 'rejected' | 'failed' | 'skipped_unsafe_url'; + + /** + * Retained delivery ID for GET /webhooks/deliveries/{delivery_id}. Omitted for + * historical or unretained deliveries. + */ + delivery_id?: string; } export namespace WebhookDelivery { @@ -580,6 +587,13 @@ export namespace MonitorCreateResponse { */ events?: Array<'change.detected' | 'run.completed'>; + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry?: WebhooksAPI.RetryConfig; + /** * Signing secret used to verify webhook authenticity. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over @@ -929,6 +943,13 @@ export namespace MonitorRetrieveResponse { */ events?: Array<'change.detected' | 'run.completed'>; + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry?: WebhooksAPI.RetryConfig; + /** * Signing secret used to verify webhook authenticity. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over @@ -1278,6 +1299,13 @@ export namespace MonitorUpdateResponse { */ events?: Array<'change.detected' | 'run.completed'>; + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry?: WebhooksAPI.RetryConfig; + /** * Signing secret used to verify webhook authenticity. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over @@ -1627,6 +1655,13 @@ export namespace MonitorListResponse { */ events?: Array<'change.detected' | 'run.completed'>; + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry?: WebhooksAPI.RetryConfig; + /** * Signing secret used to verify webhook authenticity. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over @@ -1844,6 +1879,14 @@ export namespace MonitorListAccountRunsResponse { * attempted, including historical runs created before delivery tracking was added. */ webhook_delivery?: MonitorsAPI.WebhookDelivery; + + /** + * Retained webhook deliveries for this run. Inspect their live state and attempt + * history through /webhooks/deliveries. With webhook.retry configured, delivery is + * asynchronous and the legacy webhook_delivery/webhook_deliveries outcomes are + * omitted. + */ + webhook_delivery_ids?: Array; } export namespace Data { @@ -1980,6 +2023,14 @@ export namespace MonitorListRunsResponse { * attempted, including historical runs created before delivery tracking was added. */ webhook_delivery?: MonitorsAPI.WebhookDelivery; + + /** + * Retained webhook deliveries for this run. Inspect their live state and attempt + * history through /webhooks/deliveries. With webhook.retry configured, delivery is + * asynchronous and the legacy webhook_delivery/webhook_deliveries outcomes are + * omitted. + */ + webhook_delivery_ids?: Array; } export namespace Data { @@ -2290,6 +2341,13 @@ export namespace MonitorCreateParams { * to `["change.detected"]` when omitted. */ events?: Array<'change.detected' | 'run.completed'>; + + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry?: WebhooksAPI.RetryConfig; } } @@ -2485,6 +2543,13 @@ export namespace MonitorUpdateParams { * to `["change.detected"]` when omitted. */ events?: Array<'change.detected' | 'run.completed'>; + + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry?: WebhooksAPI.RetryConfig; } } diff --git a/src/resources/webhooks.ts b/src/resources/webhooks.ts new file mode 100644 index 00000000..8aad965f --- /dev/null +++ b/src/resources/webhooks.ts @@ -0,0 +1,3 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export * from './webhooks/index'; diff --git a/src/resources/webhooks/deliveries.ts b/src/resources/webhooks/deliveries.ts new file mode 100644 index 00000000..9f5bf77d --- /dev/null +++ b/src/resources/webhooks/deliveries.ts @@ -0,0 +1,406 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../../core/resource'; +import * as DeliveriesAPI from './deliveries'; +import * as WebhooksAPI from './webhooks'; +import { APIPromise } from '../../core/api-promise'; +import { buildHeaders } from '../../internal/headers'; +import { RequestOptions } from '../../internal/request-options'; +import { path } from '../../internal/utils/path'; + +/** + * Inspect and retry batch and monitor webhook deliveries without rerunning the underlying work. + */ +export class Deliveries extends APIResource { + /** + * Get the live status, retry policy, latest attempt, and replay expiration for a + * retained delivery. Use the attempts endpoint for its complete paginated history. + * This endpoint costs no credits. + * + * @example + * ```ts + * const delivery = await client.webhooks.deliveries.retrieve( + * 'whd_210b9798eb53baa4e69d31c1071cf03d', + * ); + * ``` + */ + retrieve( + deliveryID: string, + query: DeliveryRetrieveParams | null | undefined = {}, + options?: RequestOptions, + ): APIPromise { + return this._client.get(path`/webhooks/deliveries/${deliveryID}`, { query, ...options }); + } + + /** + * List retained batch and monitor webhook deliveries for your organization, newest + * first. Filter by at most one of batch_id, monitor_id, or run_id, optionally + * combined with status. Historical events without retained payloads are not + * listed. This endpoint costs no credits. + * + * @example + * ```ts + * const deliveries = await client.webhooks.deliveries.list(); + * ``` + */ + list( + query: DeliveryListParams | null | undefined = {}, + options?: RequestOptions, + ): APIPromise { + return this._client.get('/webhooks/deliveries', { query, ...options }); + } + + /** + * List individual HTTP attempts for a delivery, newest first, including their + * destination, timestamps, HTTP status, and error. An interrupted attempt may have + * reached the endpoint even when its outcome is unknown. This endpoint costs no + * credits. + * + * @example + * ```ts + * const response = + * await client.webhooks.deliveries.listAttempts( + * 'whd_210b9798eb53baa4e69d31c1071cf03d', + * ); + * ``` + */ + listAttempts( + deliveryID: string, + query: DeliveryListAttemptsParams | null | undefined = {}, + options?: RequestOptions, + ): APIPromise { + return this._client.get(path`/webhooks/deliveries/${deliveryID}/attempts`, { query, ...options }); + } + + /** + * Queue an immediate attempt without rerunning or billing the underlying batch or + * monitor. A waiting retry is brought forward. A failed delivery gets one + * additional attempt without restarting its automatic retry budget. Set force: + * true to resend an acknowledged delivery. An in-progress attempt cannot be + * duplicated. The stored event body, event ID, and creation time remain unchanged; + * each attempt receives a fresh signature. Monitor retries use the current URL and + * secret; removing the webhook cancels pending deliveries. Batch result URLs in + * old payloads may have expired: retrieve the batch to get fresh URLs. Replay is + * available for seven days. A successful attempt cancels remaining automatic + * retries. Idempotency-Key is scoped to your organization and retained with the + * delivery metadata; repeating the same key and input returns the original + * accepted response. + * + * @example + * ```ts + * const response = await client.webhooks.deliveries.retry( + * 'whd_210b9798eb53baa4e69d31c1071cf03d', + * ); + * ``` + */ + retry( + deliveryID: string, + params: DeliveryRetryParams | null | undefined = {}, + options?: RequestOptions, + ): APIPromise { + const { 'Idempotency-Key': idempotencyKey, ...body } = params ?? {}; + return this._client.post(path`/webhooks/deliveries/${deliveryID}/retry`, { + body, + ...options, + headers: buildHeaders([ + { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) }, + options?.headers, + ]), + }); + } +} + +export interface Attempt { + id: string; + + attempt: number; + + completed_at: string | null; + + error: Attempt.Error | null; + + http_status: number | null; + + started_at: string; + + trigger: 'initial' | 'automatic' | 'manual'; + + url: string; +} + +export namespace Attempt { + export interface Error { + code: string; + + message: string; + } +} + +export interface Delivery { + id: string; + + /** + * Number of delivery attempts started, including any attempt in progress. + */ + attempt_count: number; + + created_at: string; + + /** + * Most recent successful acknowledgment; retained if a later forced resend fails. + */ + delivered_at: string | null; + + event: 'batch.completed' | 'batch.failed' | 'batch.cancelled' | 'change.detected' | 'run.completed'; + + /** + * Stable event ID. Unchanged across automatic and manual attempts; use it to + * deduplicate events. + */ + event_id: string; + + last_attempt: Delivery.LastAttempt; + + last_error: Delivery.LastError | null; + + next_attempt_at: string | null; + + /** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ + retry: WebhooksAPI.RetryConfig; + + /** + * Seven days after event creation. Manual retries after this time return 410. + * Delivery and attempt metadata remain available for up to 30 days. + */ + retry_expires_at: string; + + source: Delivery.UnionMember0 | Delivery.UnionMember1; + + status: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; + + /** + * Destination recorded for this delivery. Each attempt records the URL it used. + * Monitor retries use the currently configured URL and signing secret. + */ + url: string; +} + +export namespace Delivery { + export interface LastAttempt extends DeliveriesAPI.Attempt {} + + export interface LastError { + code: string; + + message: string; + } + + export interface UnionMember0 { + batch_id: string; + + type: 'batch'; + } + + export interface UnionMember1 { + monitor_id: string; + + run_id: string; + + type: 'monitor'; + } +} + +export interface DeliveryRetrieveResponse extends Delivery { + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + key_metadata?: DeliveryRetrieveResponse.KeyMetadata; +} + +export namespace DeliveryRetrieveResponse { + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + export interface KeyMetadata { + /** + * The number of credits consumed by this request. + */ + credits_consumed: number; + + /** + * The number of credits remaining for your organization after this request. + */ + credits_remaining: number; + } +} + +export interface DeliveryListResponse { + data: Array; + + has_more: boolean; + + next_cursor: string | null; + + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + key_metadata?: DeliveryListResponse.KeyMetadata; +} + +export namespace DeliveryListResponse { + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + export interface KeyMetadata { + /** + * The number of credits consumed by this request. + */ + credits_consumed: number; + + /** + * The number of credits remaining for your organization after this request. + */ + credits_remaining: number; + } +} + +export interface DeliveryListAttemptsResponse { + data: Array; + + has_more: boolean; + + next_cursor: string | null; + + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + key_metadata?: DeliveryListAttemptsResponse.KeyMetadata; +} + +export namespace DeliveryListAttemptsResponse { + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + export interface KeyMetadata { + /** + * The number of credits consumed by this request. + */ + credits_consumed: number; + + /** + * The number of credits remaining for your organization after this request. + */ + credits_remaining: number; + } +} + +export interface DeliveryRetryResponse extends Delivery { + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + key_metadata?: DeliveryRetryResponse.KeyMetadata; +} + +export namespace DeliveryRetryResponse { + /** + * Metadata about the API key used for the request. Included in every response + * whenever a valid API key is provided, even when the response status is not 200. + */ + export interface KeyMetadata { + /** + * The number of credits consumed by this request. + */ + credits_consumed: number; + + /** + * The number of credits remaining for your organization after this request. + */ + credits_remaining: number; + } +} + +export interface DeliveryRetrieveParams { + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are + * recorded on the request's usage log and can be used to filter usage on the + * dashboard usage page. Up to 20 tags, each 1-50 characters. + */ + tags?: Array; +} + +export interface DeliveryListParams { + batch_id?: string; + + cursor?: string; + + limit?: number; + + monitor_id?: string; + + run_id?: string; + + status?: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; + + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are + * recorded on the request's usage log and can be used to filter usage on the + * dashboard usage page. Up to 20 tags, each 1-50 characters. + */ + tags?: Array; +} + +export interface DeliveryListAttemptsParams { + cursor?: string; + + limit?: number; + + /** + * Optional comma-separated caller-defined tags for tracking this request. Tags are + * recorded on the request's usage log and can be used to filter usage on the + * dashboard usage page. Up to 20 tags, each 1-50 characters. + */ + tags?: Array; +} + +export interface DeliveryRetryParams { + /** + * Body param + */ + force?: boolean; + + /** + * Body param: Optional tags for tracking usage. Up to 20 tags, each 1 to 50 + * characters. + */ + tags?: Array; + + /** + * Header param + */ + 'Idempotency-Key'?: string; +} + +export declare namespace Deliveries { + export { + type Attempt as Attempt, + type Delivery as Delivery, + type DeliveryRetrieveResponse as DeliveryRetrieveResponse, + type DeliveryListResponse as DeliveryListResponse, + type DeliveryListAttemptsResponse as DeliveryListAttemptsResponse, + type DeliveryRetryResponse as DeliveryRetryResponse, + type DeliveryRetrieveParams as DeliveryRetrieveParams, + type DeliveryListParams as DeliveryListParams, + type DeliveryListAttemptsParams as DeliveryListAttemptsParams, + type DeliveryRetryParams as DeliveryRetryParams, + }; +} diff --git a/src/resources/webhooks/index.ts b/src/resources/webhooks/index.ts new file mode 100644 index 00000000..19f0233b --- /dev/null +++ b/src/resources/webhooks/index.ts @@ -0,0 +1,16 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export { + Deliveries, + type Attempt, + type Delivery, + type DeliveryRetrieveResponse, + type DeliveryListResponse, + type DeliveryListAttemptsResponse, + type DeliveryRetryResponse, + type DeliveryRetrieveParams, + type DeliveryListParams, + type DeliveryListAttemptsParams, + type DeliveryRetryParams, +} from './deliveries'; +export { Webhooks, type RetryConfig } from './webhooks'; diff --git a/src/resources/webhooks/webhooks.ts b/src/resources/webhooks/webhooks.ts new file mode 100644 index 00000000..2b985e57 --- /dev/null +++ b/src/resources/webhooks/webhooks.ts @@ -0,0 +1,56 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../../core/resource'; +import * as DeliveriesAPI from './deliveries'; +import { + Attempt, + Deliveries, + Delivery, + DeliveryListAttemptsParams, + DeliveryListAttemptsResponse, + DeliveryListParams, + DeliveryListResponse, + DeliveryRetrieveParams, + DeliveryRetrieveResponse, + DeliveryRetryParams, + DeliveryRetryResponse, +} from './deliveries'; + +export class Webhooks extends APIResource { + deliveries: DeliveriesAPI.Deliveries = new DeliveriesAPI.Deliveries(this._client); +} + +/** + * Opt into durable webhook delivery. An empty object uses the default retry + * schedule. Omit retry to preserve legacy delivery behavior. The policy is + * snapshotted for each event. + */ +export interface RetryConfig { + /** + * Wait in seconds after each failed attempt. The first attempt is immediate. At + * most 10 delays, each 1–86400 seconds, totaling at most 72 hours. Small jitter is + * added automatically. An empty array disables automatic retries; manual retries + * remain available. + */ + delays_seconds?: Array; +} + +Webhooks.Deliveries = Deliveries; + +export declare namespace Webhooks { + export { type RetryConfig as RetryConfig }; + + export { + Deliveries as Deliveries, + type Attempt as Attempt, + type Delivery as Delivery, + type DeliveryRetrieveResponse as DeliveryRetrieveResponse, + type DeliveryListResponse as DeliveryListResponse, + type DeliveryListAttemptsResponse as DeliveryListAttemptsResponse, + type DeliveryRetryResponse as DeliveryRetryResponse, + type DeliveryRetrieveParams as DeliveryRetrieveParams, + type DeliveryListParams as DeliveryListParams, + type DeliveryListAttemptsParams as DeliveryListAttemptsParams, + type DeliveryRetryParams as DeliveryRetryParams, + }; +} diff --git a/tests/api-resources/batch.test.ts b/tests/api-resources/batch.test.ts index 737d2843..0d04e037 100644 --- a/tests/api-resources/batch.test.ts +++ b/tests/api-resources/batch.test.ts @@ -162,6 +162,10 @@ describe('resource batch', () => { mode: 'scrape', }, tags: ['docs', 'competitor'], + webhook: { + url: 'https://example.com', + retry: { delays_seconds: [10, 60, 300, 1800, 7200, 21600, 57600] }, + }, webhookUrl: 'webhookUrl', 'Idempotency-Key': 'Idempotency-Key', }); diff --git a/tests/api-resources/monitors.test.ts b/tests/api-resources/monitors.test.ts index cd7c9604..aa8f3b4a 100644 --- a/tests/api-resources/monitors.test.ts +++ b/tests/api-resources/monitors.test.ts @@ -42,7 +42,11 @@ describe('resource monitors', () => { unit: 'hours', }, tags: ['pricing', 'competitor'], - webhook: { url: 'https://example.com/webhook', events: ['change.detected', 'run.completed'] }, + webhook: { + url: 'https://example.com/webhook', + events: ['change.detected', 'run.completed'], + retry: { delays_seconds: [10, 60, 300, 1800, 7200, 21600, 57600] }, + }, }); }); diff --git a/tests/api-resources/webhooks/deliveries.test.ts b/tests/api-resources/webhooks/deliveries.test.ts new file mode 100644 index 00000000..0ccc75c4 --- /dev/null +++ b/tests/api-resources/webhooks/deliveries.test.ts @@ -0,0 +1,121 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import ContextDev from 'context.dev'; + +const client = new ContextDev({ + apiKey: 'My API Key', + baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', +}); + +describe('resource deliveries', () => { + // Mock server tests are disabled + test.skip('retrieve', async () => { + const responsePromise = client.webhooks.deliveries.retrieve('whd_210b9798eb53baa4e69d31c1071cf03d'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('retrieve: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.webhooks.deliveries.retrieve( + 'whd_210b9798eb53baa4e69d31c1071cf03d', + { tags: ['production', 'team-alpha'] }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(ContextDev.NotFoundError); + }); + + // Mock server tests are disabled + test.skip('list', async () => { + const responsePromise = client.webhooks.deliveries.list(); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('list: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.webhooks.deliveries.list( + { + batch_id: 'batch_id', + cursor: 'whd_210b9798eb53baa4e69d31c1071cf03d', + limit: 1, + monitor_id: 'monitor_id', + run_id: 'run_id', + status: 'pending', + tags: ['production', 'team-alpha'], + }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(ContextDev.NotFoundError); + }); + + // Mock server tests are disabled + test.skip('listAttempts', async () => { + const responsePromise = client.webhooks.deliveries.listAttempts('whd_210b9798eb53baa4e69d31c1071cf03d'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('listAttempts: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.webhooks.deliveries.listAttempts( + 'whd_210b9798eb53baa4e69d31c1071cf03d', + { + cursor: 'wha_210b9798eb53baa4e69d31c1071cf03d', + limit: 1, + tags: ['production', 'team-alpha'], + }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(ContextDev.NotFoundError); + }); + + // Mock server tests are disabled + test.skip('retry', async () => { + const responsePromise = client.webhooks.deliveries.retry('whd_210b9798eb53baa4e69d31c1071cf03d'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('retry: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.webhooks.deliveries.retry( + 'whd_210b9798eb53baa4e69d31c1071cf03d', + { + force: true, + tags: ['production', 'team-alpha'], + 'Idempotency-Key': 'Idempotency-Key', + }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(ContextDev.NotFoundError); + }); +}); From 680fd86d86fc05ec1d0f0a7bb5993b13834bdb70 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 8 Sep 2026 00:01:58 +0000 Subject: [PATCH 010/232] feat(webhooks): simplify delivery APIs Stainless-Generated-From: 458138bd6722c6a0f26ae856533524f94e98ea8a --- api.md | 3 +- src/resources/ai.ts | 20 +- src/resources/batch.ts | 49 +- src/resources/brand.ts | 40 +- src/resources/industry.ts | 30 +- src/resources/monitors.ts | 37 +- src/resources/news.ts | 10 +- src/resources/parse.ts | 15 +- src/resources/people.ts | 10 +- src/resources/utility.ts | 10 +- src/resources/web.ts | 150 +++---- src/resources/webhooks/deliveries.ts | 421 ++++++++++++++---- src/resources/webhooks/index.ts | 1 + src/resources/webhooks/webhooks.ts | 12 +- .../api-resources/webhooks/deliveries.test.ts | 30 +- 15 files changed, 486 insertions(+), 352 deletions(-) diff --git a/api.md b/api.md index 8c1b1678..d98480d7 100644 --- a/api.md +++ b/api.md @@ -157,6 +157,7 @@ Types: - Attempt - Delivery +- DeliverySummary - DeliveryRetrieveResponse - DeliveryListResponse - DeliveryListAttemptsResponse @@ -165,7 +166,7 @@ Types: Methods: - client.webhooks.deliveries.retrieve(deliveryID, { ...params }) -> DeliveryRetrieveResponse -- client.webhooks.deliveries.list({ ...params }) -> DeliveryListResponse +- client.webhooks.deliveries.list({ ...params }) -> DeliveryListResponse - client.webhooks.deliveries.listAttempts(deliveryID, { ...params }) -> DeliveryListAttemptsResponse - client.webhooks.deliveries.retry(deliveryID, { ...params }) -> DeliveryRetryResponse diff --git a/src/resources/ai.ts b/src/resources/ai.ts index 24688abb..ffbb023f 100644 --- a/src/resources/ai.ts +++ b/src/resources/ai.ts @@ -57,8 +57,7 @@ export interface AIExtractProductResponse { is_product_page?: boolean; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: AIExtractProductResponse.KeyMetadata; @@ -93,17 +92,16 @@ export namespace AIExtractProductResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -216,8 +214,7 @@ export interface AIExtractProductsResponse { cache_metadata: AIExtractProductsResponse.CacheMetadata; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: AIExtractProductsResponse.KeyMetadata; @@ -247,17 +244,16 @@ export namespace AIExtractProductsResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 094dc70b..39e970ae 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -331,8 +331,7 @@ export interface BatchRetrieveResponse { key_metadata?: BatchRetrieveResponse.KeyMetadata; /** - * Retained completion delivery ID. Inspect or retry it through - * /webhooks/deliveries/{delivery_id}. Present once the delivery has been retained. + * Batch completion delivery ID, when available. */ webhook_delivery_id?: string; } @@ -458,12 +457,12 @@ export namespace BatchRetrieveResponse { */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -481,8 +480,7 @@ export interface BatchListResponse { has_more?: boolean; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: BatchListResponse.KeyMetadata; @@ -671,17 +669,16 @@ export namespace BatchListResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -699,25 +696,23 @@ export interface BatchDeleteResponse { deleted?: boolean; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: BatchDeleteResponse.KeyMetadata; } export namespace BatchDeleteResponse { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -839,12 +834,12 @@ export namespace BatchCancelResponse { */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -862,8 +857,7 @@ export interface BatchGetResultsResponse { has_more?: boolean; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: BatchGetResultsResponse.KeyMetadata; @@ -1137,17 +1131,16 @@ export namespace BatchGetResultsResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -1271,12 +1264,12 @@ export namespace BatchSubmitResponse { */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -2906,9 +2899,7 @@ export namespace BatchSubmitParams { url: string; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry?: WebhooksAPI.RetryConfig; } diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 73c289b4..ae4346fe 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -75,8 +75,7 @@ export interface BrandRetrieveResponse { code?: number; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: BrandRetrieveResponse.KeyMetadata; @@ -880,17 +879,16 @@ export namespace BrandRetrieveResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -915,8 +913,7 @@ export interface BrandRetrieveSimplifiedResponse { code?: number; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: BrandRetrieveSimplifiedResponse.KeyMetadata; @@ -1111,17 +1108,16 @@ export namespace BrandRetrieveSimplifiedResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -1135,8 +1131,7 @@ export interface BrandSearchResponse { results: Array; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: BrandSearchResponse.KeyMetadata; } @@ -1161,17 +1156,16 @@ export namespace BrandSearchResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -2069,9 +2063,8 @@ export interface BrandRetrieveSimplifiedParams { maxAgeMs?: number | null; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -2108,9 +2101,8 @@ export interface BrandSearchParams { queryBy?: Array<'name' | 'domain'>; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; diff --git a/src/resources/industry.ts b/src/resources/industry.ts index 278a6fe6..5758ee3b 100644 --- a/src/resources/industry.ts +++ b/src/resources/industry.ts @@ -40,8 +40,7 @@ export interface IndustryRetrieveNaicsResponse { domain?: string; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: IndustryRetrieveNaicsResponse.KeyMetadata; @@ -75,17 +74,16 @@ export namespace IndustryRetrieveNaicsResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -110,8 +108,7 @@ export interface IndustryRetrieveSicResponse { domain?: string; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: IndustryRetrieveSicResponse.KeyMetadata; @@ -163,17 +160,16 @@ export namespace IndustryRetrieveSicResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -199,9 +195,8 @@ export interface IndustryRetrieveNaicsParams { minResults?: number; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -232,9 +227,8 @@ export interface IndustryRetrieveSicParams { minResults?: number; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index 14c8f949..626a6dbd 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -254,8 +254,7 @@ export interface WebhookDelivery { status: 'delivered' | 'rejected' | 'failed' | 'skipped_unsafe_url'; /** - * Retained delivery ID for GET /webhooks/deliveries/{delivery_id}. Omitted for - * historical or unretained deliveries. + * Delivery ID for status checks and retries, when available. */ delivery_id?: string; } @@ -588,9 +587,7 @@ export namespace MonitorCreateResponse { events?: Array<'change.detected' | 'run.completed'>; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry?: WebhooksAPI.RetryConfig; @@ -944,9 +941,7 @@ export namespace MonitorRetrieveResponse { events?: Array<'change.detected' | 'run.completed'>; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry?: WebhooksAPI.RetryConfig; @@ -1300,9 +1295,7 @@ export namespace MonitorUpdateResponse { events?: Array<'change.detected' | 'run.completed'>; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry?: WebhooksAPI.RetryConfig; @@ -1656,9 +1649,7 @@ export namespace MonitorListResponse { events?: Array<'change.detected' | 'run.completed'>; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry?: WebhooksAPI.RetryConfig; @@ -1881,10 +1872,7 @@ export namespace MonitorListAccountRunsResponse { webhook_delivery?: MonitorsAPI.WebhookDelivery; /** - * Retained webhook deliveries for this run. Inspect their live state and attempt - * history through /webhooks/deliveries. With webhook.retry configured, delivery is - * asynchronous and the legacy webhook_delivery/webhook_deliveries outcomes are - * omitted. + * Webhook delivery IDs for this run. */ webhook_delivery_ids?: Array; } @@ -2025,10 +2013,7 @@ export namespace MonitorListRunsResponse { webhook_delivery?: MonitorsAPI.WebhookDelivery; /** - * Retained webhook deliveries for this run. Inspect their live state and attempt - * history through /webhooks/deliveries. With webhook.retry configured, delivery is - * asynchronous and the legacy webhook_delivery/webhook_deliveries outcomes are - * omitted. + * Webhook delivery IDs for this run. */ webhook_delivery_ids?: Array; } @@ -2343,9 +2328,7 @@ export namespace MonitorCreateParams { events?: Array<'change.detected' | 'run.completed'>; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry?: WebhooksAPI.RetryConfig; } @@ -2545,9 +2528,7 @@ export namespace MonitorUpdateParams { events?: Array<'change.detected' | 'run.completed'>; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry?: WebhooksAPI.RetryConfig; } diff --git a/src/resources/news.ts b/src/resources/news.ts index 015dbc50..3bebf178 100644 --- a/src/resources/news.ts +++ b/src/resources/news.ts @@ -53,8 +53,7 @@ export interface NewsSearchResponse { next_cursor: string | null; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: NewsSearchResponse.KeyMetadata; } @@ -176,17 +175,16 @@ export namespace NewsSearchResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } diff --git a/src/resources/parse.ts b/src/resources/parse.ts index efb00e0c..2e047532 100644 --- a/src/resources/parse.ts +++ b/src/resources/parse.ts @@ -106,25 +106,23 @@ export interface ParseHandleResponse { | 'pnm'; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: ParseHandleResponse.KeyMetadata; } export namespace ParseHandleResponse { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -243,9 +241,8 @@ export interface ParseHandleParams { shortenBase64Images?: boolean; /** - * Query param: Optional comma-separated caller-defined tags for tracking this - * request. Tags are recorded on the request's usage log and can be used to filter - * usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * Query param: Comma-separated tags for tracking request usage. Up to 20 tags, + * each 1-50 characters. */ tags?: Array; diff --git a/src/resources/people.ts b/src/resources/people.ts index 89a0b6e2..102d2772 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -39,8 +39,7 @@ export interface PersonEnrichResponse { | PersonEnrichResponse.PersonEnrichmentNotFoundMatch; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: PersonEnrichResponse.KeyMetadata; } @@ -254,17 +253,16 @@ export namespace PersonEnrichResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } diff --git a/src/resources/utility.ts b/src/resources/utility.ts index b972fe9c..486a063f 100644 --- a/src/resources/utility.ts +++ b/src/resources/utility.ts @@ -32,8 +32,7 @@ export interface UtilityPrefetchResponse { domain?: string; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: UtilityPrefetchResponse.KeyMetadata; @@ -55,17 +54,16 @@ export interface UtilityPrefetchResponse { export namespace UtilityPrefetchResponse { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } diff --git a/src/resources/web.ts b/src/resources/web.ts index 8f4d97d5..0adbf6be 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -253,8 +253,7 @@ export interface WebExtractResponse { urls_analyzed: Array; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebExtractResponse.KeyMetadata; } @@ -327,17 +326,16 @@ export namespace WebExtractResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -365,8 +363,7 @@ export interface WebExtractCompetitorsResponse { target: WebExtractCompetitorsResponse.Target; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebExtractCompetitorsResponse.KeyMetadata; } @@ -430,17 +427,16 @@ export namespace WebExtractCompetitorsResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -482,8 +478,7 @@ export interface WebExtractFontsResponse { fontLinks?: { [key: string]: WebExtractFontsResponse.FontLinks }; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebExtractFontsResponse.KeyMetadata; } @@ -568,17 +563,16 @@ export namespace WebExtractFontsResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -603,8 +597,7 @@ export interface WebExtractStyleguideResponse { domain?: string; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebExtractStyleguideResponse.KeyMetadata; @@ -639,17 +632,16 @@ export namespace WebExtractStyleguideResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -1168,8 +1160,7 @@ export interface WebScreenshotResponse { height?: number; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebScreenshotResponse.KeyMetadata; @@ -1215,17 +1206,16 @@ export namespace WebScreenshotResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -1247,8 +1237,7 @@ export interface WebSearchResponse { results: Array; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebSearchResponse.KeyMetadata; } @@ -1318,17 +1307,16 @@ export namespace WebSearchResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -1347,8 +1335,7 @@ export interface WebWebCrawlMdResponse { results: Array; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebCrawlMdResponse.KeyMetadata; } @@ -1572,17 +1559,16 @@ export namespace WebWebCrawlMdResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -1652,8 +1638,7 @@ export interface WebWebScrapeHTMLResponse { actionsHtmlStale?: boolean; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebScrapeHTMLResponse.KeyMetadata; } @@ -1844,17 +1829,16 @@ export namespace WebWebScrapeHTMLResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -1889,8 +1873,7 @@ export interface WebWebScrapeImagesResponse { actionsApplied?: Array; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebScrapeImagesResponse.KeyMetadata; } @@ -1997,17 +1980,16 @@ export namespace WebWebScrapeImagesResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -2067,8 +2049,7 @@ export interface WebWebScrapeMdResponse { html?: string; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebScrapeMdResponse.KeyMetadata; } @@ -2259,17 +2240,16 @@ export namespace WebWebScrapeMdResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -2298,8 +2278,7 @@ export interface WebWebScrapeSitemapResponse { urls: Array; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebScrapeSitemapResponse.KeyMetadata; } @@ -2331,17 +2310,16 @@ export namespace WebWebScrapeSitemapResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -2534,9 +2512,8 @@ export interface WebExtractCompetitorsParams { numCompetitors?: number; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -2572,9 +2549,8 @@ export interface WebExtractFontsParams { maxAgeMs?: number | null; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -2617,9 +2593,8 @@ export interface WebExtractStyleguideParams { maxAgeMs?: number | null; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -2912,9 +2887,8 @@ export interface WebScreenshotParams { scrollOffset?: number | null; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -3988,9 +3962,8 @@ export interface WebWebScrapeHTMLParams { settleAnimations?: boolean; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -4148,9 +4121,8 @@ export interface WebWebScrapeImagesParams { maxAgeMs?: number | null; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -4542,9 +4514,8 @@ export interface WebWebScrapeMdParams { shortenBase64Images?: boolean; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -4696,9 +4667,8 @@ export interface WebWebScrapeSitemapParams { sitemapUrl?: string; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; diff --git a/src/resources/webhooks/deliveries.ts b/src/resources/webhooks/deliveries.ts index 9f5bf77d..978d45dd 100644 --- a/src/resources/webhooks/deliveries.ts +++ b/src/resources/webhooks/deliveries.ts @@ -1,7 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. import { APIResource } from '../../core/resource'; -import * as DeliveriesAPI from './deliveries'; import * as WebhooksAPI from './webhooks'; import { APIPromise } from '../../core/api-promise'; import { buildHeaders } from '../../internal/headers'; @@ -9,13 +8,11 @@ import { RequestOptions } from '../../internal/request-options'; import { path } from '../../internal/utils/path'; /** - * Inspect and retry batch and monitor webhook deliveries without rerunning the underlying work. + * Inspect and retry webhook deliveries. These endpoints cost no credits. */ export class Deliveries extends APIResource { /** - * Get the live status, retry policy, latest attempt, and replay expiration for a - * retained delivery. Use the attempts endpoint for its complete paginated history. - * This endpoint costs no credits. + * Get a webhook delivery, including its status and latest attempt. * * @example * ```ts @@ -33,28 +30,23 @@ export class Deliveries extends APIResource { } /** - * List retained batch and monitor webhook deliveries for your organization, newest - * first. Filter by at most one of batch_id, monitor_id, or run_id, optionally - * combined with status. Historical events without retained payloads are not - * listed. This endpoint costs no credits. + * List your batch or monitor webhook deliveries, newest first. * * @example * ```ts - * const deliveries = await client.webhooks.deliveries.list(); + * const deliveries = await client.webhooks.deliveries.list({ + * type: 'batch', + * limit: 25, + * status: 'failed', + * }); * ``` */ - list( - query: DeliveryListParams | null | undefined = {}, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/webhooks/deliveries', { query, ...options }); + list(body: DeliveryListParams, options?: RequestOptions): APIPromise { + return this._client.post('/webhooks/deliveries', { body, ...options }); } /** - * List individual HTTP attempts for a delivery, newest first, including their - * destination, timestamps, HTTP status, and error. An interrupted attempt may have - * reached the endpoint even when its outcome is unknown. This endpoint costs no - * credits. + * List delivery attempts, newest first. * * @example * ```ts @@ -73,18 +65,7 @@ export class Deliveries extends APIResource { } /** - * Queue an immediate attempt without rerunning or billing the underlying batch or - * monitor. A waiting retry is brought forward. A failed delivery gets one - * additional attempt without restarting its automatic retry budget. Set force: - * true to resend an acknowledged delivery. An in-progress attempt cannot be - * duplicated. The stored event body, event ID, and creation time remain unchanged; - * each attempt receives a fresh signature. Monitor retries use the current URL and - * secret; removing the webhook cancels pending deliveries. Batch result URLs in - * old payloads may have expired: retrieve the batch to get fresh URLs. Replay is - * available for seven days. A successful attempt cancels remaining automatic - * retries. Idempotency-Key is scoped to your organization and retained with the - * delivery metadata; repeating the same key and input returns the original - * accepted response. + * Retry a webhook delivery within seven days of creation. * * @example * ```ts @@ -111,219 +92,396 @@ export class Deliveries extends APIResource { } export interface Attempt { - id: string; - + /** + * Attempt number, starting at 1. + */ attempt: number; + /** + * Completion time, or null while in progress. + */ completed_at: string | null; + /** + * Attempt error, or null if none. + */ error: Attempt.Error | null; + /** + * HTTP response status, or null if no response was received. + */ http_status: number | null; + /** + * Attempt start time. + */ started_at: string; + /** + * What started this attempt. + */ trigger: 'initial' | 'automatic' | 'manual'; + /** + * URL used for this attempt. + */ url: string; } export namespace Attempt { + /** + * Attempt error, or null if none. + */ export interface Error { + /** + * Error code. + */ code: string; + /** + * Error details. + */ message: string; } } export interface Delivery { + /** + * Delivery ID. + */ id: string; /** - * Number of delivery attempts started, including any attempt in progress. + * Event creation time. */ - attempt_count: number; - created_at: string; /** - * Most recent successful acknowledgment; retained if a later forced resend fails. + * Last successful delivery time, or null if never delivered. */ delivered_at: string | null; + /** + * Webhook event type. + */ event: 'batch.completed' | 'batch.failed' | 'batch.cancelled' | 'change.detected' | 'run.completed'; /** - * Stable event ID. Unchanged across automatic and manual attempts; use it to - * deduplicate events. + * Stable event ID for deduplicating received webhooks. */ event_id: string; - last_attempt: Delivery.LastAttempt; + /** + * Latest attempt, or null if none. + */ + last_attempt: Attempt | null; + /** + * Latest delivery error, or null if none. + */ last_error: Delivery.LastError | null; + /** + * Next scheduled attempt, or null if none. + */ next_attempt_at: string | null; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry: WebhooksAPI.RetryConfig; /** - * Seven days after event creation. Manual retries after this time return 410. - * Delivery and attempt metadata remain available for up to 30 days. + * Manual retry deadline, seven days after event creation. */ retry_expires_at: string; - source: Delivery.UnionMember0 | Delivery.UnionMember1; + /** + * Batch or monitor run that produced the event. + */ + source: Delivery.Batch | Delivery.Monitor; + /** + * Current delivery status. + */ status: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; /** - * Destination recorded for this delivery. Each attempt records the URL it used. - * Monitor retries use the currently configured URL and signing secret. + * Webhook destination URL. */ url: string; } export namespace Delivery { - export interface LastAttempt extends DeliveriesAPI.Attempt {} + /** + * Latest delivery error, or null if none. + */ + export interface LastError { + /** + * Error code. + */ + code: string; + + /** + * Error details. + */ + message: string; + } + + export interface Batch { + /** + * Batch ID. + */ + batch_id: string; + + /** + * Delivery source. + */ + type: 'batch'; + } + + export interface Monitor { + /** + * Monitor ID. + */ + monitor_id: string; + + /** + * Monitor run ID. + */ + run_id: string; + + /** + * Delivery source. + */ + type: 'monitor'; + } +} + +export interface DeliverySummary { + /** + * Delivery ID. + */ + id: string; + + /** + * Event creation time. + */ + created_at: string; + + /** + * Last successful delivery time, or null if never delivered. + */ + delivered_at: string | null; + + /** + * Webhook event type. + */ + event: 'batch.completed' | 'batch.failed' | 'batch.cancelled' | 'change.detected' | 'run.completed'; + + /** + * Latest delivery error, or null if none. + */ + last_error: DeliverySummary.LastError | null; + + /** + * Next scheduled attempt, or null if none. + */ + next_attempt_at: string | null; + + /** + * Manual retry deadline, seven days after event creation. + */ + retry_expires_at: string; + /** + * Batch or monitor run that produced the event. + */ + source: DeliverySummary.Batch | DeliverySummary.Monitor; + + /** + * Current delivery status. + */ + status: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; + + /** + * Webhook destination URL. + */ + url: string; +} + +export namespace DeliverySummary { + /** + * Latest delivery error, or null if none. + */ export interface LastError { + /** + * Error code. + */ code: string; + /** + * Error details. + */ message: string; } - export interface UnionMember0 { + export interface Batch { + /** + * Batch ID. + */ batch_id: string; + /** + * Delivery source. + */ type: 'batch'; } - export interface UnionMember1 { + export interface Monitor { + /** + * Monitor ID. + */ monitor_id: string; + /** + * Monitor run ID. + */ run_id: string; + /** + * Delivery source. + */ type: 'monitor'; } } export interface DeliveryRetrieveResponse extends Delivery { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: DeliveryRetrieveResponse.KeyMetadata; } export namespace DeliveryRetrieveResponse { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } } export interface DeliveryListResponse { - data: Array; + /** + * Webhook deliveries. + */ + data: Array; + /** + * Whether more deliveries are available. + */ has_more: boolean; + /** + * Next page cursor, or null on the last page. + */ next_cursor: string | null; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: DeliveryListResponse.KeyMetadata; } export namespace DeliveryListResponse { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } } export interface DeliveryListAttemptsResponse { + /** + * Delivery attempts. + */ data: Array; + /** + * Whether more attempts are available. + */ has_more: boolean; + /** + * Next page cursor, or null on the last page. + */ next_cursor: string | null; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: DeliveryListAttemptsResponse.KeyMetadata; } export namespace DeliveryListAttemptsResponse { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } } -export interface DeliveryRetryResponse extends Delivery { +export interface DeliveryRetryResponse { + /** + * Delivery ID. + */ + id: string; + /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: DeliveryRetryResponse.KeyMetadata; } export namespace DeliveryRetryResponse { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -331,50 +489,116 @@ export namespace DeliveryRetryResponse { export interface DeliveryRetrieveParams { /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; } -export interface DeliveryListParams { - batch_id?: string; +export type DeliveryListParams = DeliveryListParams.ByBatch | DeliveryListParams.ByMonitor; - cursor?: string; +export declare namespace DeliveryListParams { + export interface ByBatch { + /** + * Delivery source. + */ + type: 'batch'; - limit?: number; + /** + * Filter by batch ID. + */ + batch_id?: string; - monitor_id?: string; + /** + * Only include events created after this ISO 8601 timestamp. + */ + created_after?: string; - run_id?: string; + /** + * The next_cursor from the previous response. + */ + cursor?: string; - status?: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; + /** + * Number of deliveries to return. + */ + limit?: number; - /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. - */ - tags?: Array; + /** + * Filter by delivery status. + */ + status?: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; + + /** + * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + */ + tags?: Array; + } + + export interface ByMonitor { + /** + * Delivery source. + */ + type: 'monitor'; + + /** + * Only include events created after this ISO 8601 timestamp. + */ + created_after?: string; + + /** + * The next_cursor from the previous response. + */ + cursor?: string; + + /** + * Number of deliveries to return. + */ + limit?: number; + + /** + * Filter by monitor ID. + */ + monitor_id?: string; + + /** + * Filter by monitor run ID. + */ + run_id?: string; + + /** + * Filter by delivery status. + */ + status?: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; + + /** + * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + */ + tags?: Array; + } } export interface DeliveryListAttemptsParams { + /** + * The next_cursor from the previous response. + */ cursor?: string; + /** + * Number of attempts to return. + */ limit?: number; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; } export interface DeliveryRetryParams { /** - * Body param + * Body param: Resend a delivery that already succeeded. */ force?: boolean; @@ -385,7 +609,7 @@ export interface DeliveryRetryParams { tags?: Array; /** - * Header param + * Header param: Unique key to prevent duplicate retry requests. */ 'Idempotency-Key'?: string; } @@ -394,6 +618,7 @@ export declare namespace Deliveries { export { type Attempt as Attempt, type Delivery as Delivery, + type DeliverySummary as DeliverySummary, type DeliveryRetrieveResponse as DeliveryRetrieveResponse, type DeliveryListResponse as DeliveryListResponse, type DeliveryListAttemptsResponse as DeliveryListAttemptsResponse, diff --git a/src/resources/webhooks/index.ts b/src/resources/webhooks/index.ts index 19f0233b..ba38693c 100644 --- a/src/resources/webhooks/index.ts +++ b/src/resources/webhooks/index.ts @@ -4,6 +4,7 @@ export { Deliveries, type Attempt, type Delivery, + type DeliverySummary, type DeliveryRetrieveResponse, type DeliveryListResponse, type DeliveryListAttemptsResponse, diff --git a/src/resources/webhooks/webhooks.ts b/src/resources/webhooks/webhooks.ts index 2b985e57..e21a221a 100644 --- a/src/resources/webhooks/webhooks.ts +++ b/src/resources/webhooks/webhooks.ts @@ -14,6 +14,7 @@ import { DeliveryRetrieveResponse, DeliveryRetryParams, DeliveryRetryResponse, + DeliverySummary, } from './deliveries'; export class Webhooks extends APIResource { @@ -21,16 +22,12 @@ export class Webhooks extends APIResource { } /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ export interface RetryConfig { /** - * Wait in seconds after each failed attempt. The first attempt is immediate. At - * most 10 delays, each 1–86400 seconds, totaling at most 72 hours. Small jitter is - * added automatically. An empty array disables automatic retries; manual retries - * remain available. + * Retry delays in seconds, totaling at most 72 hours. Use [] to disable automatic + * retries. */ delays_seconds?: Array; } @@ -44,6 +41,7 @@ export declare namespace Webhooks { Deliveries as Deliveries, type Attempt as Attempt, type Delivery as Delivery, + type DeliverySummary as DeliverySummary, type DeliveryRetrieveResponse as DeliveryRetrieveResponse, type DeliveryListResponse as DeliveryListResponse, type DeliveryListAttemptsResponse as DeliveryListAttemptsResponse, diff --git a/tests/api-resources/webhooks/deliveries.test.ts b/tests/api-resources/webhooks/deliveries.test.ts index 0ccc75c4..a04ea49f 100644 --- a/tests/api-resources/webhooks/deliveries.test.ts +++ b/tests/api-resources/webhooks/deliveries.test.ts @@ -33,8 +33,8 @@ describe('resource deliveries', () => { }); // Mock server tests are disabled - test.skip('list', async () => { - const responsePromise = client.webhooks.deliveries.list(); + test.skip('list: only required params', async () => { + const responsePromise = client.webhooks.deliveries.list({ type: 'batch' }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -45,22 +45,16 @@ describe('resource deliveries', () => { }); // Mock server tests are disabled - test.skip('list: request options and params are passed correctly', async () => { - // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error - await expect( - client.webhooks.deliveries.list( - { - batch_id: 'batch_id', - cursor: 'whd_210b9798eb53baa4e69d31c1071cf03d', - limit: 1, - monitor_id: 'monitor_id', - run_id: 'run_id', - status: 'pending', - tags: ['production', 'team-alpha'], - }, - { path: '/_stainless_unknown_path' }, - ), - ).rejects.toThrow(ContextDev.NotFoundError); + test.skip('list: required and optional params', async () => { + const response = await client.webhooks.deliveries.list({ + type: 'batch', + batch_id: 'batch_id', + created_after: '2026-09-01T00:00:00Z', + cursor: 'whd_210b9798eb53baa4e69d31c1071cf03d', + limit: 1, + status: 'pending', + tags: ['production', 'team-alpha'], + }); }); // Mock server tests are disabled From 458138bd6722c6a0f26ae856533524f94e98ea8a Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 8 Sep 2026 00:01:58 +0000 Subject: [PATCH 011/232] seal --- api.md | 3 +- src/resources/ai.ts | 20 +- src/resources/batch.ts | 49 +- src/resources/brand.ts | 40 +- src/resources/industry.ts | 30 +- src/resources/monitors.ts | 37 +- src/resources/news.ts | 10 +- src/resources/parse.ts | 15 +- src/resources/people.ts | 10 +- src/resources/utility.ts | 10 +- src/resources/web.ts | 150 +++---- src/resources/webhooks/deliveries.ts | 421 ++++++++++++++---- src/resources/webhooks/index.ts | 1 + src/resources/webhooks/webhooks.ts | 12 +- .../api-resources/webhooks/deliveries.test.ts | 30 +- 15 files changed, 486 insertions(+), 352 deletions(-) diff --git a/api.md b/api.md index 8c1b1678..d98480d7 100644 --- a/api.md +++ b/api.md @@ -157,6 +157,7 @@ Types: - Attempt - Delivery +- DeliverySummary - DeliveryRetrieveResponse - DeliveryListResponse - DeliveryListAttemptsResponse @@ -165,7 +166,7 @@ Types: Methods: - client.webhooks.deliveries.retrieve(deliveryID, { ...params }) -> DeliveryRetrieveResponse -- client.webhooks.deliveries.list({ ...params }) -> DeliveryListResponse +- client.webhooks.deliveries.list({ ...params }) -> DeliveryListResponse - client.webhooks.deliveries.listAttempts(deliveryID, { ...params }) -> DeliveryListAttemptsResponse - client.webhooks.deliveries.retry(deliveryID, { ...params }) -> DeliveryRetryResponse diff --git a/src/resources/ai.ts b/src/resources/ai.ts index 24688abb..ffbb023f 100644 --- a/src/resources/ai.ts +++ b/src/resources/ai.ts @@ -57,8 +57,7 @@ export interface AIExtractProductResponse { is_product_page?: boolean; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: AIExtractProductResponse.KeyMetadata; @@ -93,17 +92,16 @@ export namespace AIExtractProductResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -216,8 +214,7 @@ export interface AIExtractProductsResponse { cache_metadata: AIExtractProductsResponse.CacheMetadata; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: AIExtractProductsResponse.KeyMetadata; @@ -247,17 +244,16 @@ export namespace AIExtractProductsResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 094dc70b..39e970ae 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -331,8 +331,7 @@ export interface BatchRetrieveResponse { key_metadata?: BatchRetrieveResponse.KeyMetadata; /** - * Retained completion delivery ID. Inspect or retry it through - * /webhooks/deliveries/{delivery_id}. Present once the delivery has been retained. + * Batch completion delivery ID, when available. */ webhook_delivery_id?: string; } @@ -458,12 +457,12 @@ export namespace BatchRetrieveResponse { */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -481,8 +480,7 @@ export interface BatchListResponse { has_more?: boolean; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: BatchListResponse.KeyMetadata; @@ -671,17 +669,16 @@ export namespace BatchListResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -699,25 +696,23 @@ export interface BatchDeleteResponse { deleted?: boolean; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: BatchDeleteResponse.KeyMetadata; } export namespace BatchDeleteResponse { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -839,12 +834,12 @@ export namespace BatchCancelResponse { */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -862,8 +857,7 @@ export interface BatchGetResultsResponse { has_more?: boolean; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: BatchGetResultsResponse.KeyMetadata; @@ -1137,17 +1131,16 @@ export namespace BatchGetResultsResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -1271,12 +1264,12 @@ export namespace BatchSubmitResponse { */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -2906,9 +2899,7 @@ export namespace BatchSubmitParams { url: string; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry?: WebhooksAPI.RetryConfig; } diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 73c289b4..ae4346fe 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -75,8 +75,7 @@ export interface BrandRetrieveResponse { code?: number; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: BrandRetrieveResponse.KeyMetadata; @@ -880,17 +879,16 @@ export namespace BrandRetrieveResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -915,8 +913,7 @@ export interface BrandRetrieveSimplifiedResponse { code?: number; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: BrandRetrieveSimplifiedResponse.KeyMetadata; @@ -1111,17 +1108,16 @@ export namespace BrandRetrieveSimplifiedResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -1135,8 +1131,7 @@ export interface BrandSearchResponse { results: Array; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: BrandSearchResponse.KeyMetadata; } @@ -1161,17 +1156,16 @@ export namespace BrandSearchResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -2069,9 +2063,8 @@ export interface BrandRetrieveSimplifiedParams { maxAgeMs?: number | null; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -2108,9 +2101,8 @@ export interface BrandSearchParams { queryBy?: Array<'name' | 'domain'>; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; diff --git a/src/resources/industry.ts b/src/resources/industry.ts index 278a6fe6..5758ee3b 100644 --- a/src/resources/industry.ts +++ b/src/resources/industry.ts @@ -40,8 +40,7 @@ export interface IndustryRetrieveNaicsResponse { domain?: string; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: IndustryRetrieveNaicsResponse.KeyMetadata; @@ -75,17 +74,16 @@ export namespace IndustryRetrieveNaicsResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -110,8 +108,7 @@ export interface IndustryRetrieveSicResponse { domain?: string; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: IndustryRetrieveSicResponse.KeyMetadata; @@ -163,17 +160,16 @@ export namespace IndustryRetrieveSicResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -199,9 +195,8 @@ export interface IndustryRetrieveNaicsParams { minResults?: number; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -232,9 +227,8 @@ export interface IndustryRetrieveSicParams { minResults?: number; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index 14c8f949..626a6dbd 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -254,8 +254,7 @@ export interface WebhookDelivery { status: 'delivered' | 'rejected' | 'failed' | 'skipped_unsafe_url'; /** - * Retained delivery ID for GET /webhooks/deliveries/{delivery_id}. Omitted for - * historical or unretained deliveries. + * Delivery ID for status checks and retries, when available. */ delivery_id?: string; } @@ -588,9 +587,7 @@ export namespace MonitorCreateResponse { events?: Array<'change.detected' | 'run.completed'>; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry?: WebhooksAPI.RetryConfig; @@ -944,9 +941,7 @@ export namespace MonitorRetrieveResponse { events?: Array<'change.detected' | 'run.completed'>; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry?: WebhooksAPI.RetryConfig; @@ -1300,9 +1295,7 @@ export namespace MonitorUpdateResponse { events?: Array<'change.detected' | 'run.completed'>; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry?: WebhooksAPI.RetryConfig; @@ -1656,9 +1649,7 @@ export namespace MonitorListResponse { events?: Array<'change.detected' | 'run.completed'>; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry?: WebhooksAPI.RetryConfig; @@ -1881,10 +1872,7 @@ export namespace MonitorListAccountRunsResponse { webhook_delivery?: MonitorsAPI.WebhookDelivery; /** - * Retained webhook deliveries for this run. Inspect their live state and attempt - * history through /webhooks/deliveries. With webhook.retry configured, delivery is - * asynchronous and the legacy webhook_delivery/webhook_deliveries outcomes are - * omitted. + * Webhook delivery IDs for this run. */ webhook_delivery_ids?: Array; } @@ -2025,10 +2013,7 @@ export namespace MonitorListRunsResponse { webhook_delivery?: MonitorsAPI.WebhookDelivery; /** - * Retained webhook deliveries for this run. Inspect their live state and attempt - * history through /webhooks/deliveries. With webhook.retry configured, delivery is - * asynchronous and the legacy webhook_delivery/webhook_deliveries outcomes are - * omitted. + * Webhook delivery IDs for this run. */ webhook_delivery_ids?: Array; } @@ -2343,9 +2328,7 @@ export namespace MonitorCreateParams { events?: Array<'change.detected' | 'run.completed'>; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry?: WebhooksAPI.RetryConfig; } @@ -2545,9 +2528,7 @@ export namespace MonitorUpdateParams { events?: Array<'change.detected' | 'run.completed'>; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry?: WebhooksAPI.RetryConfig; } diff --git a/src/resources/news.ts b/src/resources/news.ts index 015dbc50..3bebf178 100644 --- a/src/resources/news.ts +++ b/src/resources/news.ts @@ -53,8 +53,7 @@ export interface NewsSearchResponse { next_cursor: string | null; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: NewsSearchResponse.KeyMetadata; } @@ -176,17 +175,16 @@ export namespace NewsSearchResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } diff --git a/src/resources/parse.ts b/src/resources/parse.ts index efb00e0c..2e047532 100644 --- a/src/resources/parse.ts +++ b/src/resources/parse.ts @@ -106,25 +106,23 @@ export interface ParseHandleResponse { | 'pnm'; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: ParseHandleResponse.KeyMetadata; } export namespace ParseHandleResponse { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -243,9 +241,8 @@ export interface ParseHandleParams { shortenBase64Images?: boolean; /** - * Query param: Optional comma-separated caller-defined tags for tracking this - * request. Tags are recorded on the request's usage log and can be used to filter - * usage on the dashboard usage page. Up to 20 tags, each 1-50 characters. + * Query param: Comma-separated tags for tracking request usage. Up to 20 tags, + * each 1-50 characters. */ tags?: Array; diff --git a/src/resources/people.ts b/src/resources/people.ts index 89a0b6e2..102d2772 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -39,8 +39,7 @@ export interface PersonEnrichResponse { | PersonEnrichResponse.PersonEnrichmentNotFoundMatch; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: PersonEnrichResponse.KeyMetadata; } @@ -254,17 +253,16 @@ export namespace PersonEnrichResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } diff --git a/src/resources/utility.ts b/src/resources/utility.ts index b972fe9c..486a063f 100644 --- a/src/resources/utility.ts +++ b/src/resources/utility.ts @@ -32,8 +32,7 @@ export interface UtilityPrefetchResponse { domain?: string; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: UtilityPrefetchResponse.KeyMetadata; @@ -55,17 +54,16 @@ export interface UtilityPrefetchResponse { export namespace UtilityPrefetchResponse { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } diff --git a/src/resources/web.ts b/src/resources/web.ts index 8f4d97d5..0adbf6be 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -253,8 +253,7 @@ export interface WebExtractResponse { urls_analyzed: Array; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebExtractResponse.KeyMetadata; } @@ -327,17 +326,16 @@ export namespace WebExtractResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -365,8 +363,7 @@ export interface WebExtractCompetitorsResponse { target: WebExtractCompetitorsResponse.Target; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebExtractCompetitorsResponse.KeyMetadata; } @@ -430,17 +427,16 @@ export namespace WebExtractCompetitorsResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -482,8 +478,7 @@ export interface WebExtractFontsResponse { fontLinks?: { [key: string]: WebExtractFontsResponse.FontLinks }; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebExtractFontsResponse.KeyMetadata; } @@ -568,17 +563,16 @@ export namespace WebExtractFontsResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -603,8 +597,7 @@ export interface WebExtractStyleguideResponse { domain?: string; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebExtractStyleguideResponse.KeyMetadata; @@ -639,17 +632,16 @@ export namespace WebExtractStyleguideResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -1168,8 +1160,7 @@ export interface WebScreenshotResponse { height?: number; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebScreenshotResponse.KeyMetadata; @@ -1215,17 +1206,16 @@ export namespace WebScreenshotResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -1247,8 +1237,7 @@ export interface WebSearchResponse { results: Array; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebSearchResponse.KeyMetadata; } @@ -1318,17 +1307,16 @@ export namespace WebSearchResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -1347,8 +1335,7 @@ export interface WebWebCrawlMdResponse { results: Array; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebCrawlMdResponse.KeyMetadata; } @@ -1572,17 +1559,16 @@ export namespace WebWebCrawlMdResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -1652,8 +1638,7 @@ export interface WebWebScrapeHTMLResponse { actionsHtmlStale?: boolean; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebScrapeHTMLResponse.KeyMetadata; } @@ -1844,17 +1829,16 @@ export namespace WebWebScrapeHTMLResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -1889,8 +1873,7 @@ export interface WebWebScrapeImagesResponse { actionsApplied?: Array; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebScrapeImagesResponse.KeyMetadata; } @@ -1997,17 +1980,16 @@ export namespace WebWebScrapeImagesResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -2067,8 +2049,7 @@ export interface WebWebScrapeMdResponse { html?: string; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebScrapeMdResponse.KeyMetadata; } @@ -2259,17 +2240,16 @@ export namespace WebWebScrapeMdResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -2298,8 +2278,7 @@ export interface WebWebScrapeSitemapResponse { urls: Array; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebScrapeSitemapResponse.KeyMetadata; } @@ -2331,17 +2310,16 @@ export namespace WebWebScrapeSitemapResponse { } /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -2534,9 +2512,8 @@ export interface WebExtractCompetitorsParams { numCompetitors?: number; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -2572,9 +2549,8 @@ export interface WebExtractFontsParams { maxAgeMs?: number | null; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -2617,9 +2593,8 @@ export interface WebExtractStyleguideParams { maxAgeMs?: number | null; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -2912,9 +2887,8 @@ export interface WebScreenshotParams { scrollOffset?: number | null; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -3988,9 +3962,8 @@ export interface WebWebScrapeHTMLParams { settleAnimations?: boolean; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -4148,9 +4121,8 @@ export interface WebWebScrapeImagesParams { maxAgeMs?: number | null; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -4542,9 +4514,8 @@ export interface WebWebScrapeMdParams { shortenBase64Images?: boolean; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; @@ -4696,9 +4667,8 @@ export interface WebWebScrapeSitemapParams { sitemapUrl?: string; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; diff --git a/src/resources/webhooks/deliveries.ts b/src/resources/webhooks/deliveries.ts index 9f5bf77d..978d45dd 100644 --- a/src/resources/webhooks/deliveries.ts +++ b/src/resources/webhooks/deliveries.ts @@ -1,7 +1,6 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. import { APIResource } from '../../core/resource'; -import * as DeliveriesAPI from './deliveries'; import * as WebhooksAPI from './webhooks'; import { APIPromise } from '../../core/api-promise'; import { buildHeaders } from '../../internal/headers'; @@ -9,13 +8,11 @@ import { RequestOptions } from '../../internal/request-options'; import { path } from '../../internal/utils/path'; /** - * Inspect and retry batch and monitor webhook deliveries without rerunning the underlying work. + * Inspect and retry webhook deliveries. These endpoints cost no credits. */ export class Deliveries extends APIResource { /** - * Get the live status, retry policy, latest attempt, and replay expiration for a - * retained delivery. Use the attempts endpoint for its complete paginated history. - * This endpoint costs no credits. + * Get a webhook delivery, including its status and latest attempt. * * @example * ```ts @@ -33,28 +30,23 @@ export class Deliveries extends APIResource { } /** - * List retained batch and monitor webhook deliveries for your organization, newest - * first. Filter by at most one of batch_id, monitor_id, or run_id, optionally - * combined with status. Historical events without retained payloads are not - * listed. This endpoint costs no credits. + * List your batch or monitor webhook deliveries, newest first. * * @example * ```ts - * const deliveries = await client.webhooks.deliveries.list(); + * const deliveries = await client.webhooks.deliveries.list({ + * type: 'batch', + * limit: 25, + * status: 'failed', + * }); * ``` */ - list( - query: DeliveryListParams | null | undefined = {}, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/webhooks/deliveries', { query, ...options }); + list(body: DeliveryListParams, options?: RequestOptions): APIPromise { + return this._client.post('/webhooks/deliveries', { body, ...options }); } /** - * List individual HTTP attempts for a delivery, newest first, including their - * destination, timestamps, HTTP status, and error. An interrupted attempt may have - * reached the endpoint even when its outcome is unknown. This endpoint costs no - * credits. + * List delivery attempts, newest first. * * @example * ```ts @@ -73,18 +65,7 @@ export class Deliveries extends APIResource { } /** - * Queue an immediate attempt without rerunning or billing the underlying batch or - * monitor. A waiting retry is brought forward. A failed delivery gets one - * additional attempt without restarting its automatic retry budget. Set force: - * true to resend an acknowledged delivery. An in-progress attempt cannot be - * duplicated. The stored event body, event ID, and creation time remain unchanged; - * each attempt receives a fresh signature. Monitor retries use the current URL and - * secret; removing the webhook cancels pending deliveries. Batch result URLs in - * old payloads may have expired: retrieve the batch to get fresh URLs. Replay is - * available for seven days. A successful attempt cancels remaining automatic - * retries. Idempotency-Key is scoped to your organization and retained with the - * delivery metadata; repeating the same key and input returns the original - * accepted response. + * Retry a webhook delivery within seven days of creation. * * @example * ```ts @@ -111,219 +92,396 @@ export class Deliveries extends APIResource { } export interface Attempt { - id: string; - + /** + * Attempt number, starting at 1. + */ attempt: number; + /** + * Completion time, or null while in progress. + */ completed_at: string | null; + /** + * Attempt error, or null if none. + */ error: Attempt.Error | null; + /** + * HTTP response status, or null if no response was received. + */ http_status: number | null; + /** + * Attempt start time. + */ started_at: string; + /** + * What started this attempt. + */ trigger: 'initial' | 'automatic' | 'manual'; + /** + * URL used for this attempt. + */ url: string; } export namespace Attempt { + /** + * Attempt error, or null if none. + */ export interface Error { + /** + * Error code. + */ code: string; + /** + * Error details. + */ message: string; } } export interface Delivery { + /** + * Delivery ID. + */ id: string; /** - * Number of delivery attempts started, including any attempt in progress. + * Event creation time. */ - attempt_count: number; - created_at: string; /** - * Most recent successful acknowledgment; retained if a later forced resend fails. + * Last successful delivery time, or null if never delivered. */ delivered_at: string | null; + /** + * Webhook event type. + */ event: 'batch.completed' | 'batch.failed' | 'batch.cancelled' | 'change.detected' | 'run.completed'; /** - * Stable event ID. Unchanged across automatic and manual attempts; use it to - * deduplicate events. + * Stable event ID for deduplicating received webhooks. */ event_id: string; - last_attempt: Delivery.LastAttempt; + /** + * Latest attempt, or null if none. + */ + last_attempt: Attempt | null; + /** + * Latest delivery error, or null if none. + */ last_error: Delivery.LastError | null; + /** + * Next scheduled attempt, or null if none. + */ next_attempt_at: string | null; /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ retry: WebhooksAPI.RetryConfig; /** - * Seven days after event creation. Manual retries after this time return 410. - * Delivery and attempt metadata remain available for up to 30 days. + * Manual retry deadline, seven days after event creation. */ retry_expires_at: string; - source: Delivery.UnionMember0 | Delivery.UnionMember1; + /** + * Batch or monitor run that produced the event. + */ + source: Delivery.Batch | Delivery.Monitor; + /** + * Current delivery status. + */ status: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; /** - * Destination recorded for this delivery. Each attempt records the URL it used. - * Monitor retries use the currently configured URL and signing secret. + * Webhook destination URL. */ url: string; } export namespace Delivery { - export interface LastAttempt extends DeliveriesAPI.Attempt {} + /** + * Latest delivery error, or null if none. + */ + export interface LastError { + /** + * Error code. + */ + code: string; + + /** + * Error details. + */ + message: string; + } + + export interface Batch { + /** + * Batch ID. + */ + batch_id: string; + + /** + * Delivery source. + */ + type: 'batch'; + } + + export interface Monitor { + /** + * Monitor ID. + */ + monitor_id: string; + + /** + * Monitor run ID. + */ + run_id: string; + + /** + * Delivery source. + */ + type: 'monitor'; + } +} + +export interface DeliverySummary { + /** + * Delivery ID. + */ + id: string; + + /** + * Event creation time. + */ + created_at: string; + + /** + * Last successful delivery time, or null if never delivered. + */ + delivered_at: string | null; + + /** + * Webhook event type. + */ + event: 'batch.completed' | 'batch.failed' | 'batch.cancelled' | 'change.detected' | 'run.completed'; + + /** + * Latest delivery error, or null if none. + */ + last_error: DeliverySummary.LastError | null; + + /** + * Next scheduled attempt, or null if none. + */ + next_attempt_at: string | null; + + /** + * Manual retry deadline, seven days after event creation. + */ + retry_expires_at: string; + /** + * Batch or monitor run that produced the event. + */ + source: DeliverySummary.Batch | DeliverySummary.Monitor; + + /** + * Current delivery status. + */ + status: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; + + /** + * Webhook destination URL. + */ + url: string; +} + +export namespace DeliverySummary { + /** + * Latest delivery error, or null if none. + */ export interface LastError { + /** + * Error code. + */ code: string; + /** + * Error details. + */ message: string; } - export interface UnionMember0 { + export interface Batch { + /** + * Batch ID. + */ batch_id: string; + /** + * Delivery source. + */ type: 'batch'; } - export interface UnionMember1 { + export interface Monitor { + /** + * Monitor ID. + */ monitor_id: string; + /** + * Monitor run ID. + */ run_id: string; + /** + * Delivery source. + */ type: 'monitor'; } } export interface DeliveryRetrieveResponse extends Delivery { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: DeliveryRetrieveResponse.KeyMetadata; } export namespace DeliveryRetrieveResponse { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } } export interface DeliveryListResponse { - data: Array; + /** + * Webhook deliveries. + */ + data: Array; + /** + * Whether more deliveries are available. + */ has_more: boolean; + /** + * Next page cursor, or null on the last page. + */ next_cursor: string | null; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: DeliveryListResponse.KeyMetadata; } export namespace DeliveryListResponse { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } } export interface DeliveryListAttemptsResponse { + /** + * Delivery attempts. + */ data: Array; + /** + * Whether more attempts are available. + */ has_more: boolean; + /** + * Next page cursor, or null on the last page. + */ next_cursor: string | null; /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: DeliveryListAttemptsResponse.KeyMetadata; } export namespace DeliveryListAttemptsResponse { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } } -export interface DeliveryRetryResponse extends Delivery { +export interface DeliveryRetryResponse { + /** + * Delivery ID. + */ + id: string; + /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ key_metadata?: DeliveryRetryResponse.KeyMetadata; } export namespace DeliveryRetryResponse { /** - * Metadata about the API key used for the request. Included in every response - * whenever a valid API key is provided, even when the response status is not 200. + * Credit usage, included whenever a valid API key is provided. */ export interface KeyMetadata { /** - * The number of credits consumed by this request. + * Credits used by this request. */ credits_consumed: number; /** - * The number of credits remaining for your organization after this request. + * Credits remaining for your organization. */ credits_remaining: number; } @@ -331,50 +489,116 @@ export namespace DeliveryRetryResponse { export interface DeliveryRetrieveParams { /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; } -export interface DeliveryListParams { - batch_id?: string; +export type DeliveryListParams = DeliveryListParams.ByBatch | DeliveryListParams.ByMonitor; - cursor?: string; +export declare namespace DeliveryListParams { + export interface ByBatch { + /** + * Delivery source. + */ + type: 'batch'; - limit?: number; + /** + * Filter by batch ID. + */ + batch_id?: string; - monitor_id?: string; + /** + * Only include events created after this ISO 8601 timestamp. + */ + created_after?: string; - run_id?: string; + /** + * The next_cursor from the previous response. + */ + cursor?: string; - status?: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; + /** + * Number of deliveries to return. + */ + limit?: number; - /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. - */ - tags?: Array; + /** + * Filter by delivery status. + */ + status?: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; + + /** + * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + */ + tags?: Array; + } + + export interface ByMonitor { + /** + * Delivery source. + */ + type: 'monitor'; + + /** + * Only include events created after this ISO 8601 timestamp. + */ + created_after?: string; + + /** + * The next_cursor from the previous response. + */ + cursor?: string; + + /** + * Number of deliveries to return. + */ + limit?: number; + + /** + * Filter by monitor ID. + */ + monitor_id?: string; + + /** + * Filter by monitor run ID. + */ + run_id?: string; + + /** + * Filter by delivery status. + */ + status?: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; + + /** + * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + */ + tags?: Array; + } } export interface DeliveryListAttemptsParams { + /** + * The next_cursor from the previous response. + */ cursor?: string; + /** + * Number of attempts to return. + */ limit?: number; /** - * Optional comma-separated caller-defined tags for tracking this request. Tags are - * recorded on the request's usage log and can be used to filter usage on the - * dashboard usage page. Up to 20 tags, each 1-50 characters. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ tags?: Array; } export interface DeliveryRetryParams { /** - * Body param + * Body param: Resend a delivery that already succeeded. */ force?: boolean; @@ -385,7 +609,7 @@ export interface DeliveryRetryParams { tags?: Array; /** - * Header param + * Header param: Unique key to prevent duplicate retry requests. */ 'Idempotency-Key'?: string; } @@ -394,6 +618,7 @@ export declare namespace Deliveries { export { type Attempt as Attempt, type Delivery as Delivery, + type DeliverySummary as DeliverySummary, type DeliveryRetrieveResponse as DeliveryRetrieveResponse, type DeliveryListResponse as DeliveryListResponse, type DeliveryListAttemptsResponse as DeliveryListAttemptsResponse, diff --git a/src/resources/webhooks/index.ts b/src/resources/webhooks/index.ts index 19f0233b..ba38693c 100644 --- a/src/resources/webhooks/index.ts +++ b/src/resources/webhooks/index.ts @@ -4,6 +4,7 @@ export { Deliveries, type Attempt, type Delivery, + type DeliverySummary, type DeliveryRetrieveResponse, type DeliveryListResponse, type DeliveryListAttemptsResponse, diff --git a/src/resources/webhooks/webhooks.ts b/src/resources/webhooks/webhooks.ts index 2b985e57..e21a221a 100644 --- a/src/resources/webhooks/webhooks.ts +++ b/src/resources/webhooks/webhooks.ts @@ -14,6 +14,7 @@ import { DeliveryRetrieveResponse, DeliveryRetryParams, DeliveryRetryResponse, + DeliverySummary, } from './deliveries'; export class Webhooks extends APIResource { @@ -21,16 +22,12 @@ export class Webhooks extends APIResource { } /** - * Opt into durable webhook delivery. An empty object uses the default retry - * schedule. Omit retry to preserve legacy delivery behavior. The policy is - * snapshotted for each event. + * Webhook retry settings. Use {} for the default schedule. */ export interface RetryConfig { /** - * Wait in seconds after each failed attempt. The first attempt is immediate. At - * most 10 delays, each 1–86400 seconds, totaling at most 72 hours. Small jitter is - * added automatically. An empty array disables automatic retries; manual retries - * remain available. + * Retry delays in seconds, totaling at most 72 hours. Use [] to disable automatic + * retries. */ delays_seconds?: Array; } @@ -44,6 +41,7 @@ export declare namespace Webhooks { Deliveries as Deliveries, type Attempt as Attempt, type Delivery as Delivery, + type DeliverySummary as DeliverySummary, type DeliveryRetrieveResponse as DeliveryRetrieveResponse, type DeliveryListResponse as DeliveryListResponse, type DeliveryListAttemptsResponse as DeliveryListAttemptsResponse, diff --git a/tests/api-resources/webhooks/deliveries.test.ts b/tests/api-resources/webhooks/deliveries.test.ts index 0ccc75c4..a04ea49f 100644 --- a/tests/api-resources/webhooks/deliveries.test.ts +++ b/tests/api-resources/webhooks/deliveries.test.ts @@ -33,8 +33,8 @@ describe('resource deliveries', () => { }); // Mock server tests are disabled - test.skip('list', async () => { - const responsePromise = client.webhooks.deliveries.list(); + test.skip('list: only required params', async () => { + const responsePromise = client.webhooks.deliveries.list({ type: 'batch' }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -45,22 +45,16 @@ describe('resource deliveries', () => { }); // Mock server tests are disabled - test.skip('list: request options and params are passed correctly', async () => { - // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error - await expect( - client.webhooks.deliveries.list( - { - batch_id: 'batch_id', - cursor: 'whd_210b9798eb53baa4e69d31c1071cf03d', - limit: 1, - monitor_id: 'monitor_id', - run_id: 'run_id', - status: 'pending', - tags: ['production', 'team-alpha'], - }, - { path: '/_stainless_unknown_path' }, - ), - ).rejects.toThrow(ContextDev.NotFoundError); + test.skip('list: required and optional params', async () => { + const response = await client.webhooks.deliveries.list({ + type: 'batch', + batch_id: 'batch_id', + created_after: '2026-09-01T00:00:00Z', + cursor: 'whd_210b9798eb53baa4e69d31c1071cf03d', + limit: 1, + status: 'pending', + tags: ['production', 'team-alpha'], + }); }); // Mock server tests are disabled From c4fe2704c269eb13ce8c61552d22cc54440a7ff0 Mon Sep 17 00:00:00 2001 From: contextualbeer Date: Tue, 8 Sep 2026 02:03:15 +0200 Subject: [PATCH 012/232] release: 2.16.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 8 ++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 11 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 96a8c91d..7731f20e 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.15.0" + ".": "2.16.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 69878f88..7bb28e33 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## [2.16.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.15.0...v2.16.0) (2026-09-08) + + +### Features + +* **webhooks:** add configurable retries and manual replay ([da20ddb](https://github.com/context-dot-dev/context-typescript-sdk/commit/da20ddbcc80c966aaed048ddb3bef70e5c2d8e8e)) +* **webhooks:** simplify delivery APIs ([680fd86](https://github.com/context-dot-dev/context-typescript-sdk/commit/680fd86d86fc05ec1d0f0a7bb5993b13834bdb70)) + ## [2.15.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.14.0...v2.15.0) (2026-09-03) diff --git a/package.json b/package.json index 5fa53c5f..a828fee4 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.15.0", + "version": "2.16.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index ba989f03..f9cc5c13 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.15.0'; // x-release-please-version +export const VERSION = '2.16.0'; // x-release-please-version From 0905435f0651a16cc048d6298ad80ca074fab2df Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 8 Sep 2026 00:44:53 +0000 Subject: [PATCH 013/232] seal --- .release-please-manifest.json | 2 +- CHANGELOG.md | 8 ++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 11 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 96a8c91d..7731f20e 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.15.0" + ".": "2.16.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 69878f88..7bb28e33 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## [2.16.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.15.0...v2.16.0) (2026-09-08) + + +### Features + +* **webhooks:** add configurable retries and manual replay ([da20ddb](https://github.com/context-dot-dev/context-typescript-sdk/commit/da20ddbcc80c966aaed048ddb3bef70e5c2d8e8e)) +* **webhooks:** simplify delivery APIs ([680fd86](https://github.com/context-dot-dev/context-typescript-sdk/commit/680fd86d86fc05ec1d0f0a7bb5993b13834bdb70)) + ## [2.15.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.14.0...v2.15.0) (2026-09-03) diff --git a/package.json b/package.json index 5fa53c5f..a828fee4 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.15.0", + "version": "2.16.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index ba989f03..f9cc5c13 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.15.0'; // x-release-please-version +export const VERSION = '2.16.0'; // x-release-please-version From bbed97e56d6831767fd116c001e85c3138ce5d75 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 9 Sep 2026 12:38:38 +0000 Subject: [PATCH 014/232] seal --- src/resources/web.ts | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 0adbf6be..1a2dc3ba 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2907,7 +2907,8 @@ export interface WebScreenshotParams { /** * Optional browser wait time in milliseconds after initial page load before taking * the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when - * omitted. + * omitted. When combined with timeoutMS, timeoutMS must be at least waitForMs + + * 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; @@ -3982,7 +3983,9 @@ export interface WebWebScrapeHTMLParams { /** * Optional browser wait time in milliseconds after initial page load. Min: 0. Max: - * 30000 (30 seconds). + * 30000 (30 seconds). When combined with timeoutMS, timeoutMS must be at least + * waitForMs + 10000 ms; a shorter deadline is rejected with 400 + * TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; @@ -4135,7 +4138,9 @@ export interface WebWebScrapeImagesParams { /** * Optional browser wait time in milliseconds after initial page load before - * collecting images. Min: 0. Max: 30000 (30 seconds). + * collecting images. Min: 0. Max: 30000 (30 seconds). When combined with + * timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter deadline + * is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; } @@ -4534,7 +4539,9 @@ export interface WebWebScrapeMdParams { /** * Optional browser wait time in milliseconds after initial page load before - * converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). + * converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). When combined + * with timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter + * deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; From a46905a650e7d357657b9d27cfca7cf9b784576f Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 9 Sep 2026 12:38:38 +0000 Subject: [PATCH 015/232] fix(api): reject timeoutMS too short for waitForMs Stainless-Generated-From: bbed97e56d6831767fd116c001e85c3138ce5d75 --- src/resources/web.ts | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 0adbf6be..1a2dc3ba 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2907,7 +2907,8 @@ export interface WebScreenshotParams { /** * Optional browser wait time in milliseconds after initial page load before taking * the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when - * omitted. + * omitted. When combined with timeoutMS, timeoutMS must be at least waitForMs + + * 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; @@ -3982,7 +3983,9 @@ export interface WebWebScrapeHTMLParams { /** * Optional browser wait time in milliseconds after initial page load. Min: 0. Max: - * 30000 (30 seconds). + * 30000 (30 seconds). When combined with timeoutMS, timeoutMS must be at least + * waitForMs + 10000 ms; a shorter deadline is rejected with 400 + * TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; @@ -4135,7 +4138,9 @@ export interface WebWebScrapeImagesParams { /** * Optional browser wait time in milliseconds after initial page load before - * collecting images. Min: 0. Max: 30000 (30 seconds). + * collecting images. Min: 0. Max: 30000 (30 seconds). When combined with + * timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter deadline + * is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; } @@ -4534,7 +4539,9 @@ export interface WebWebScrapeMdParams { /** * Optional browser wait time in milliseconds after initial page load before - * converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). + * converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). When combined + * with timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter + * deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; From 722e11602fb5a280414f296aefa3e4fb9627f3b3 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 11 Sep 2026 18:22:09 +0000 Subject: [PATCH 016/232] seal --- README.md | 4 +- src/resources/ai.ts | 12 +++++ src/resources/batch.ts | 36 +++++++++++++++ src/resources/brand.ts | 18 ++++++++ src/resources/industry.ts | 12 +++++ src/resources/news.ts | 6 +++ src/resources/parse.ts | 6 +++ src/resources/people.ts | 6 +++ src/resources/utility.ts | 6 +++ src/resources/web.ts | 66 ++++++++++++++++++++++++++++ src/resources/webhooks/deliveries.ts | 24 ++++++++++ 11 files changed, 194 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 503becae..08d23b4e 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ const client = new ContextDev({ const brand = await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }); -console.log(brand.cache_metadata); +console.log(brand.request_id); ``` ### Request & Response types @@ -149,7 +149,7 @@ const { data: brand, response: raw } = await client.brand .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }) .withResponse(); console.log(raw.headers.get('X-My-Header')); -console.log(brand.cache_metadata); +console.log(brand.request_id); ``` ### Logging diff --git a/src/resources/ai.ts b/src/resources/ai.ts index ffbb023f..a9b21b8e 100644 --- a/src/resources/ai.ts +++ b/src/resources/ai.ts @@ -51,6 +51,12 @@ export interface AIExtractProductResponse { */ cache_metadata: AIExtractProductResponse.CacheMetadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Whether the given URL is a product detail page */ @@ -213,6 +219,12 @@ export interface AIExtractProductsResponse { */ cache_metadata: AIExtractProductsResponse.CacheMetadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Credit usage, included whenever a valid API key is provided. */ diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 39e970ae..3149acd4 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -307,6 +307,12 @@ export interface BatchRetrieveResponse { */ progress: BatchRetrieveResponse.Progress; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * 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. @@ -469,6 +475,12 @@ export namespace BatchRetrieveResponse { } export interface BatchListResponse { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Batches on this page. */ @@ -685,6 +697,12 @@ export namespace BatchListResponse { } export interface BatchDeleteResponse { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * ID of the deleted batch. */ @@ -760,6 +778,12 @@ export interface BatchCancelResponse { */ progress: BatchCancelResponse.Progress; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Always `cancelling`. Work already in flight finishes; the batch reaches * `cancelled` shortly after. @@ -846,6 +870,12 @@ export namespace BatchCancelResponse { } export interface BatchGetResultsResponse { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Result records on this page. */ @@ -1195,6 +1225,12 @@ export interface BatchSubmitResponse { */ mode: 'scrape' | 'crawl'; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Always `queued`. An accepted batch has not started yet. */ diff --git a/src/resources/brand.ts b/src/resources/brand.ts index ae4346fe..5ea88c6a 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -64,6 +64,12 @@ export interface BrandRetrieveResponse { */ cache_metadata: BrandRetrieveResponse.CacheMetadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Detailed brand information */ @@ -902,6 +908,12 @@ export interface BrandRetrieveSimplifiedResponse { */ cache_metadata: BrandRetrieveSimplifiedResponse.CacheMetadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Simplified brand information */ @@ -1124,6 +1136,12 @@ export namespace BrandRetrieveSimplifiedResponse { } export interface BrandSearchResponse { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Up to 10 matching brands, name matches first, then domain matches, most popular * first within each group. Empty when nothing matches. diff --git a/src/resources/industry.ts b/src/resources/industry.ts index 5758ee3b..5e7b6175 100644 --- a/src/resources/industry.ts +++ b/src/resources/industry.ts @@ -29,6 +29,12 @@ export class Industry extends APIResource { } export interface IndustryRetrieveNaicsResponse { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Array of NAICS codes and titles. */ @@ -90,6 +96,12 @@ export namespace IndustryRetrieveNaicsResponse { } export interface IndustryRetrieveSicResponse { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Echoes back which SIC dataset was used to classify the brand. */ diff --git a/src/resources/news.ts b/src/resources/news.ts index 3bebf178..9653f44f 100644 --- a/src/resources/news.ts +++ b/src/resources/news.ts @@ -52,6 +52,12 @@ export interface NewsSearchResponse { */ next_cursor: string | null; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Credit usage, included whenever a valid API key is provided. */ diff --git a/src/resources/parse.ts b/src/resources/parse.ts index 2e047532..3448644e 100644 --- a/src/resources/parse.ts +++ b/src/resources/parse.ts @@ -54,6 +54,12 @@ export interface ParseHandleResponse { */ markdown: string; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Indicates success */ diff --git a/src/resources/people.ts b/src/resources/people.ts index 102d2772..9da7e1e5 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -38,6 +38,12 @@ export interface PersonEnrichResponse { | PersonEnrichResponse.PersonEnrichmentCandidateMatch | PersonEnrichResponse.PersonEnrichmentNotFoundMatch; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Credit usage, included whenever a valid API key is provided. */ diff --git a/src/resources/utility.ts b/src/resources/utility.ts index 486a063f..289797da 100644 --- a/src/resources/utility.ts +++ b/src/resources/utility.ts @@ -26,6 +26,12 @@ export class Utility extends APIResource { } export interface UtilityPrefetchResponse { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * The domain that was queued for prefetching */ diff --git a/src/resources/web.ts b/src/resources/web.ts index 1a2dc3ba..e50fb665 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -237,6 +237,12 @@ export interface WebExtractResponse { metadata: WebExtractResponse.Metadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Status of the response, e.g., 'ok' */ @@ -352,6 +358,12 @@ export interface WebExtractCompetitorsResponse { */ domain: string; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Status of the response. */ @@ -465,6 +477,12 @@ export interface WebExtractFontsResponse { */ fonts: Array; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Status of the response, e.g., 'ok' */ @@ -586,6 +604,12 @@ export interface WebExtractStyleguideResponse { */ cache_metadata: WebExtractStyleguideResponse.CacheMetadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * HTTP status code */ @@ -1144,6 +1168,12 @@ export interface WebScreenshotResponse { */ cache_metadata: WebScreenshotResponse.CacheMetadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * HTTP status code */ @@ -1234,6 +1264,12 @@ export interface WebSearchResponse { */ query: string; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + results: Array; /** @@ -1332,6 +1368,12 @@ export interface WebWebCrawlMdResponse { metadata: WebWebCrawlMdResponse.Metadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + results: Array; /** @@ -1594,6 +1636,12 @@ export interface WebWebScrapeHTMLResponse { */ metadata: WebWebScrapeHTMLResponse.Metadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Indicates success */ @@ -1857,6 +1905,12 @@ export interface WebWebScrapeImagesResponse { */ images: Array; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Always true on success. */ @@ -2020,6 +2074,12 @@ export interface WebWebScrapeMdResponse { */ metadata: WebWebScrapeMdResponse.Metadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Indicates success */ @@ -2266,6 +2326,12 @@ export interface WebWebScrapeSitemapResponse { */ meta: WebWebScrapeSitemapResponse.Meta; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Indicates success */ diff --git a/src/resources/webhooks/deliveries.ts b/src/resources/webhooks/deliveries.ts index 978d45dd..89b1f012 100644 --- a/src/resources/webhooks/deliveries.ts +++ b/src/resources/webhooks/deliveries.ts @@ -357,6 +357,12 @@ export namespace DeliverySummary { } export interface DeliveryRetrieveResponse extends Delivery { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Credit usage, included whenever a valid API key is provided. */ @@ -396,6 +402,12 @@ export interface DeliveryListResponse { */ next_cursor: string | null; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Credit usage, included whenever a valid API key is provided. */ @@ -435,6 +447,12 @@ export interface DeliveryListAttemptsResponse { */ next_cursor: string | null; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Credit usage, included whenever a valid API key is provided. */ @@ -464,6 +482,12 @@ export interface DeliveryRetryResponse { */ id: string; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Credit usage, included whenever a valid API key is provided. */ From 37e1f63aeea80c7ece0a33029864fe2dd40637c4 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 11 Sep 2026 18:22:09 +0000 Subject: [PATCH 017/232] feat(api): return request_id on every response Stainless-Generated-From: 722e11602fb5a280414f296aefa3e4fb9627f3b3 --- README.md | 4 +- src/resources/ai.ts | 12 +++++ src/resources/batch.ts | 36 +++++++++++++++ src/resources/brand.ts | 18 ++++++++ src/resources/industry.ts | 12 +++++ src/resources/news.ts | 6 +++ src/resources/parse.ts | 6 +++ src/resources/people.ts | 6 +++ src/resources/utility.ts | 6 +++ src/resources/web.ts | 66 ++++++++++++++++++++++++++++ src/resources/webhooks/deliveries.ts | 24 ++++++++++ 11 files changed, 194 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 503becae..08d23b4e 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ const client = new ContextDev({ const brand = await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }); -console.log(brand.cache_metadata); +console.log(brand.request_id); ``` ### Request & Response types @@ -149,7 +149,7 @@ const { data: brand, response: raw } = await client.brand .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }) .withResponse(); console.log(raw.headers.get('X-My-Header')); -console.log(brand.cache_metadata); +console.log(brand.request_id); ``` ### Logging diff --git a/src/resources/ai.ts b/src/resources/ai.ts index ffbb023f..a9b21b8e 100644 --- a/src/resources/ai.ts +++ b/src/resources/ai.ts @@ -51,6 +51,12 @@ export interface AIExtractProductResponse { */ cache_metadata: AIExtractProductResponse.CacheMetadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Whether the given URL is a product detail page */ @@ -213,6 +219,12 @@ export interface AIExtractProductsResponse { */ cache_metadata: AIExtractProductsResponse.CacheMetadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Credit usage, included whenever a valid API key is provided. */ diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 39e970ae..3149acd4 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -307,6 +307,12 @@ export interface BatchRetrieveResponse { */ progress: BatchRetrieveResponse.Progress; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * 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. @@ -469,6 +475,12 @@ export namespace BatchRetrieveResponse { } export interface BatchListResponse { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Batches on this page. */ @@ -685,6 +697,12 @@ export namespace BatchListResponse { } export interface BatchDeleteResponse { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * ID of the deleted batch. */ @@ -760,6 +778,12 @@ export interface BatchCancelResponse { */ progress: BatchCancelResponse.Progress; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Always `cancelling`. Work already in flight finishes; the batch reaches * `cancelled` shortly after. @@ -846,6 +870,12 @@ export namespace BatchCancelResponse { } export interface BatchGetResultsResponse { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Result records on this page. */ @@ -1195,6 +1225,12 @@ export interface BatchSubmitResponse { */ mode: 'scrape' | 'crawl'; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Always `queued`. An accepted batch has not started yet. */ diff --git a/src/resources/brand.ts b/src/resources/brand.ts index ae4346fe..5ea88c6a 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -64,6 +64,12 @@ export interface BrandRetrieveResponse { */ cache_metadata: BrandRetrieveResponse.CacheMetadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Detailed brand information */ @@ -902,6 +908,12 @@ export interface BrandRetrieveSimplifiedResponse { */ cache_metadata: BrandRetrieveSimplifiedResponse.CacheMetadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Simplified brand information */ @@ -1124,6 +1136,12 @@ export namespace BrandRetrieveSimplifiedResponse { } export interface BrandSearchResponse { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Up to 10 matching brands, name matches first, then domain matches, most popular * first within each group. Empty when nothing matches. diff --git a/src/resources/industry.ts b/src/resources/industry.ts index 5758ee3b..5e7b6175 100644 --- a/src/resources/industry.ts +++ b/src/resources/industry.ts @@ -29,6 +29,12 @@ export class Industry extends APIResource { } export interface IndustryRetrieveNaicsResponse { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Array of NAICS codes and titles. */ @@ -90,6 +96,12 @@ export namespace IndustryRetrieveNaicsResponse { } export interface IndustryRetrieveSicResponse { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Echoes back which SIC dataset was used to classify the brand. */ diff --git a/src/resources/news.ts b/src/resources/news.ts index 3bebf178..9653f44f 100644 --- a/src/resources/news.ts +++ b/src/resources/news.ts @@ -52,6 +52,12 @@ export interface NewsSearchResponse { */ next_cursor: string | null; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Credit usage, included whenever a valid API key is provided. */ diff --git a/src/resources/parse.ts b/src/resources/parse.ts index 2e047532..3448644e 100644 --- a/src/resources/parse.ts +++ b/src/resources/parse.ts @@ -54,6 +54,12 @@ export interface ParseHandleResponse { */ markdown: string; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Indicates success */ diff --git a/src/resources/people.ts b/src/resources/people.ts index 102d2772..9da7e1e5 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -38,6 +38,12 @@ export interface PersonEnrichResponse { | PersonEnrichResponse.PersonEnrichmentCandidateMatch | PersonEnrichResponse.PersonEnrichmentNotFoundMatch; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Credit usage, included whenever a valid API key is provided. */ diff --git a/src/resources/utility.ts b/src/resources/utility.ts index 486a063f..289797da 100644 --- a/src/resources/utility.ts +++ b/src/resources/utility.ts @@ -26,6 +26,12 @@ export class Utility extends APIResource { } export interface UtilityPrefetchResponse { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * The domain that was queued for prefetching */ diff --git a/src/resources/web.ts b/src/resources/web.ts index 1a2dc3ba..e50fb665 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -237,6 +237,12 @@ export interface WebExtractResponse { metadata: WebExtractResponse.Metadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Status of the response, e.g., 'ok' */ @@ -352,6 +358,12 @@ export interface WebExtractCompetitorsResponse { */ domain: string; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Status of the response. */ @@ -465,6 +477,12 @@ export interface WebExtractFontsResponse { */ fonts: Array; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Status of the response, e.g., 'ok' */ @@ -586,6 +604,12 @@ export interface WebExtractStyleguideResponse { */ cache_metadata: WebExtractStyleguideResponse.CacheMetadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * HTTP status code */ @@ -1144,6 +1168,12 @@ export interface WebScreenshotResponse { */ cache_metadata: WebScreenshotResponse.CacheMetadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * HTTP status code */ @@ -1234,6 +1264,12 @@ export interface WebSearchResponse { */ query: string; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + results: Array; /** @@ -1332,6 +1368,12 @@ export interface WebWebCrawlMdResponse { metadata: WebWebCrawlMdResponse.Metadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + results: Array; /** @@ -1594,6 +1636,12 @@ export interface WebWebScrapeHTMLResponse { */ metadata: WebWebScrapeHTMLResponse.Metadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Indicates success */ @@ -1857,6 +1905,12 @@ export interface WebWebScrapeImagesResponse { */ images: Array; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Always true on success. */ @@ -2020,6 +2074,12 @@ export interface WebWebScrapeMdResponse { */ metadata: WebWebScrapeMdResponse.Metadata; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Indicates success */ @@ -2266,6 +2326,12 @@ export interface WebWebScrapeSitemapResponse { */ meta: WebWebScrapeSitemapResponse.Meta; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Indicates success */ diff --git a/src/resources/webhooks/deliveries.ts b/src/resources/webhooks/deliveries.ts index 978d45dd..89b1f012 100644 --- a/src/resources/webhooks/deliveries.ts +++ b/src/resources/webhooks/deliveries.ts @@ -357,6 +357,12 @@ export namespace DeliverySummary { } export interface DeliveryRetrieveResponse extends Delivery { + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Credit usage, included whenever a valid API key is provided. */ @@ -396,6 +402,12 @@ export interface DeliveryListResponse { */ next_cursor: string | null; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Credit usage, included whenever a valid API key is provided. */ @@ -435,6 +447,12 @@ export interface DeliveryListAttemptsResponse { */ next_cursor: string | null; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Credit usage, included whenever a valid API key is provided. */ @@ -464,6 +482,12 @@ export interface DeliveryRetryResponse { */ id: string; + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + /** * Credit usage, included whenever a valid API key is provided. */ From 216d051facced848cdaa337d2c7c6c17565d763c Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 11 Sep 2026 20:56:48 +0000 Subject: [PATCH 018/232] seal --- .stats.yml | 2 +- api.md | 12 ++ src/client.ts | 13 ++ src/resources/index.ts | 1 + src/resources/logs.ts | 342 +++++++++++++++++++++++++++++++ tests/api-resources/logs.test.ts | 57 ++++++ 6 files changed, 426 insertions(+), 1 deletion(-) create mode 100644 src/resources/logs.ts create mode 100644 tests/api-resources/logs.test.ts diff --git a/.stats.yml b/.stats.yml index c7c071bd..006b15f4 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 45 +configured_endpoints: 47 diff --git a/api.md b/api.md index d98480d7..7597ed86 100644 --- a/api.md +++ b/api.md @@ -189,3 +189,15 @@ Types: Methods: - client.news.search({ ...params }) -> NewsSearchResponse + +# Logs + +Types: + +- LogRetrieveResponse +- LogListResponse + +Methods: + +- client.logs.retrieve(requestID) -> LogRetrieveResponse +- client.logs.list({ ...params }) -> LogListResponse diff --git a/src/client.ts b/src/client.ts index c9d1be53..1911624e 100644 --- a/src/client.ts +++ b/src/client.ts @@ -56,6 +56,7 @@ import { IndustryRetrieveSicParams, IndustryRetrieveSicResponse, } from './resources/industry'; +import { LogListParams, LogListResponse, LogRetrieveResponse, Logs } from './resources/logs'; import { MonitorCreateParams, MonitorCreateResponse, @@ -848,6 +849,10 @@ export class ContextDev { * Search live first-party RSS and free historical news data by company identity. */ news: API.News = new API.News(this); + /** + * Read your organization's API request logs to debug failed calls. These endpoints cost no credits and use a separate rate limit. + */ + logs: API.Logs = new API.Logs(this); } ContextDev.Parse = Parse; @@ -861,6 +866,7 @@ ContextDev.Batch = Batch; ContextDev.Webhooks = Webhooks; ContextDev.People = People; ContextDev.News = News; +ContextDev.Logs = Logs; export declare namespace ContextDev { export type RequestOptions = Opts.RequestOptions; @@ -985,4 +991,11 @@ export declare namespace ContextDev { type NewsSearchResponse as NewsSearchResponse, type NewsSearchParams as NewsSearchParams, }; + + export { + Logs as Logs, + type LogRetrieveResponse as LogRetrieveResponse, + type LogListResponse as LogListResponse, + type LogListParams as LogListParams, + }; } diff --git a/src/resources/index.ts b/src/resources/index.ts index b64a0897..b7d3e275 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -39,6 +39,7 @@ export { type IndustryRetrieveNaicsParams, type IndustryRetrieveSicParams, } from './industry'; +export { Logs, type LogRetrieveResponse, type LogListResponse, type LogListParams } from './logs'; export { Monitors, type WebhookDelivery, diff --git a/src/resources/logs.ts b/src/resources/logs.ts new file mode 100644 index 00000000..74f00c5d --- /dev/null +++ b/src/resources/logs.ts @@ -0,0 +1,342 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../core/resource'; +import { APIPromise } from '../core/api-promise'; +import { RequestOptions } from '../internal/request-options'; +import { path } from '../internal/utils/path'; + +/** + * Read your organization's API request logs to debug failed calls. These endpoints cost no credits and use a separate rate limit. + */ +export class Logs extends APIResource { + /** + * Get one logged API call, including its request input and response body. + */ + retrieve(requestID: string, options?: RequestOptions): APIPromise { + return this._client.get(path`/logs/${requestID}`, options); + } + + /** + * List your organization's API requests, newest first. Defaults to the last 24 + * hours. + */ + list(query: LogListParams | null | undefined = {}, options?: RequestOptions): APIPromise { + return this._client.get('/logs', { query, ...options }); + } +} + +export interface LogRetrieveResponse { + data: LogRetrieveResponse.Data; + + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: LogRetrieveResponse.KeyMetadata; +} + +export namespace LogRetrieveResponse { + export interface Data { + /** + * Credits charged for this request. + */ + credits_used: number; + + /** + * The `error_code` from the response, or null on success. + */ + error_code: string | null; + + /** + * What was sent with the request. + */ + input: Data.Input; + + /** + * ID of the API key that made the request. + */ + key_id: string | null; + + /** + * Server-side processing time in milliseconds. + */ + latency_ms: number; + + /** + * HTTP method. + */ + method: string; + + /** + * Endpoint path as called. + */ + path: string; + + /** + * Request ID of the logged API call. + */ + request_id: string; + + /** + * HTTP status code returned. + */ + status_code: number; + + /** + * Request tags supplied by the caller. + */ + tags: Array; + + /** + * When the request completed. + */ + timestamp: string; + + /** + * User-Agent header of the request. + */ + user_agent: string | null; + + /** + * Whether the request was made under zero data retention. + */ + zdr: boolean; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: Data.KeyMetadata; + + /** + * The retained JSON response with credentials redacted, or null when unavailable. + */ + response?: unknown; + } + + export namespace Data { + /** + * What was sent with the request. + */ + export interface Input { + /** + * Query parameters as sent. + */ + query: { [key: string]: unknown }; + + /** + * Request body with credentials and uploaded content redacted. + */ + body?: unknown; + } + + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } + } + + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + +export interface LogListResponse { + /** + * Log entries, newest first. + */ + data: Array; + + /** + * Whether a next page exists. + */ + has_more: boolean; + + /** + * Entries per page. + */ + limit: number; + + /** + * Current page number. + */ + page: number; + + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: LogListResponse.KeyMetadata; +} + +export namespace LogListResponse { + export interface Data { + /** + * Credits charged for this request. + */ + credits_used: number; + + /** + * The `error_code` from the response, or null on success. + */ + error_code: string | null; + + /** + * ID of the API key that made the request. + */ + key_id: string | null; + + /** + * Server-side processing time in milliseconds. + */ + latency_ms: number; + + /** + * HTTP method. + */ + method: string; + + /** + * Endpoint path as called. + */ + path: string; + + /** + * Request ID of the logged API call. + */ + request_id: string; + + /** + * HTTP status code returned. + */ + status_code: number; + + /** + * Request tags supplied by the caller. + */ + tags: Array; + + /** + * When the request completed. + */ + timestamp: string; + + /** + * Whether the request was made under zero data retention. + */ + zdr: boolean; + } + + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + +export interface LogListParams { + /** + * Filter by the `error_code` returned in the response. + */ + error_code?: string; + + /** + * Only include requests that returned a 4xx or 5xx status. + */ + errors_only?: boolean; + + /** + * Only include requests at or after this ISO 8601 timestamp. Defaults to 24 hours + * before `to`. + */ + from?: string; + + /** + * Filter by the API key that made the request. + */ + key_id?: string; + + /** + * Number of log entries per page. + */ + limit?: number; + + /** + * Page number, starting at 1. + */ + page?: number; + + /** + * Filter by endpoint path, with or without the /v1 prefix. + */ + path?: string; + + /** + * Case-insensitive substring match against the request query and body, e.g. a + * domain. + */ + search?: string; + + /** + * Filter by exact HTTP status code. + */ + status_code?: number; + + /** + * Comma-separated request tags. Matches requests carrying any of them. Up to 20 + * tags, each 1-50 characters. + */ + tags?: string; + + /** + * Only include requests at or before this ISO 8601 timestamp. Defaults to now. + */ + to?: string; +} + +export declare namespace Logs { + export { + type LogRetrieveResponse as LogRetrieveResponse, + type LogListResponse as LogListResponse, + type LogListParams as LogListParams, + }; +} diff --git a/tests/api-resources/logs.test.ts b/tests/api-resources/logs.test.ts new file mode 100644 index 00000000..4227b6f8 --- /dev/null +++ b/tests/api-resources/logs.test.ts @@ -0,0 +1,57 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import ContextDev from 'context.dev'; + +const client = new ContextDev({ + apiKey: 'My API Key', + baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', +}); + +describe('resource logs', () => { + // Mock server tests are disabled + test.skip('retrieve', async () => { + const responsePromise = client.logs.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('list', async () => { + const responsePromise = client.logs.list(); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('list: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.logs.list( + { + error_code: 'WEBSITE_ACCESS_ERROR', + errors_only: true, + from: '2026-09-10T00:00:00Z', + key_id: 'x', + limit: 1, + page: 1, + path: '/brand/retrieve', + search: 'acme.com', + status_code: 500, + tags: 'nightly-import,team-alpha', + to: '2026-09-11T00:00:00Z', + }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(ContextDev.NotFoundError); + }); +}); From ca7e22a3ba12d75961d940fb81d8a36ead6ea761 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 11 Sep 2026 20:56:49 +0000 Subject: [PATCH 019/232] feat(logs): expose request log endpoints in SDKs (#1025) Stainless-Generated-From: 216d051facced848cdaa337d2c7c6c17565d763c --- .stats.yml | 2 +- api.md | 12 ++ src/client.ts | 13 ++ src/resources/index.ts | 1 + src/resources/logs.ts | 342 +++++++++++++++++++++++++++++++ tests/api-resources/logs.test.ts | 57 ++++++ 6 files changed, 426 insertions(+), 1 deletion(-) create mode 100644 src/resources/logs.ts create mode 100644 tests/api-resources/logs.test.ts diff --git a/.stats.yml b/.stats.yml index c7c071bd..006b15f4 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 45 +configured_endpoints: 47 diff --git a/api.md b/api.md index d98480d7..7597ed86 100644 --- a/api.md +++ b/api.md @@ -189,3 +189,15 @@ Types: Methods: - client.news.search({ ...params }) -> NewsSearchResponse + +# Logs + +Types: + +- LogRetrieveResponse +- LogListResponse + +Methods: + +- client.logs.retrieve(requestID) -> LogRetrieveResponse +- client.logs.list({ ...params }) -> LogListResponse diff --git a/src/client.ts b/src/client.ts index c9d1be53..1911624e 100644 --- a/src/client.ts +++ b/src/client.ts @@ -56,6 +56,7 @@ import { IndustryRetrieveSicParams, IndustryRetrieveSicResponse, } from './resources/industry'; +import { LogListParams, LogListResponse, LogRetrieveResponse, Logs } from './resources/logs'; import { MonitorCreateParams, MonitorCreateResponse, @@ -848,6 +849,10 @@ export class ContextDev { * Search live first-party RSS and free historical news data by company identity. */ news: API.News = new API.News(this); + /** + * Read your organization's API request logs to debug failed calls. These endpoints cost no credits and use a separate rate limit. + */ + logs: API.Logs = new API.Logs(this); } ContextDev.Parse = Parse; @@ -861,6 +866,7 @@ ContextDev.Batch = Batch; ContextDev.Webhooks = Webhooks; ContextDev.People = People; ContextDev.News = News; +ContextDev.Logs = Logs; export declare namespace ContextDev { export type RequestOptions = Opts.RequestOptions; @@ -985,4 +991,11 @@ export declare namespace ContextDev { type NewsSearchResponse as NewsSearchResponse, type NewsSearchParams as NewsSearchParams, }; + + export { + Logs as Logs, + type LogRetrieveResponse as LogRetrieveResponse, + type LogListResponse as LogListResponse, + type LogListParams as LogListParams, + }; } diff --git a/src/resources/index.ts b/src/resources/index.ts index b64a0897..b7d3e275 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -39,6 +39,7 @@ export { type IndustryRetrieveNaicsParams, type IndustryRetrieveSicParams, } from './industry'; +export { Logs, type LogRetrieveResponse, type LogListResponse, type LogListParams } from './logs'; export { Monitors, type WebhookDelivery, diff --git a/src/resources/logs.ts b/src/resources/logs.ts new file mode 100644 index 00000000..74f00c5d --- /dev/null +++ b/src/resources/logs.ts @@ -0,0 +1,342 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../core/resource'; +import { APIPromise } from '../core/api-promise'; +import { RequestOptions } from '../internal/request-options'; +import { path } from '../internal/utils/path'; + +/** + * Read your organization's API request logs to debug failed calls. These endpoints cost no credits and use a separate rate limit. + */ +export class Logs extends APIResource { + /** + * Get one logged API call, including its request input and response body. + */ + retrieve(requestID: string, options?: RequestOptions): APIPromise { + return this._client.get(path`/logs/${requestID}`, options); + } + + /** + * List your organization's API requests, newest first. Defaults to the last 24 + * hours. + */ + list(query: LogListParams | null | undefined = {}, options?: RequestOptions): APIPromise { + return this._client.get('/logs', { query, ...options }); + } +} + +export interface LogRetrieveResponse { + data: LogRetrieveResponse.Data; + + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: LogRetrieveResponse.KeyMetadata; +} + +export namespace LogRetrieveResponse { + export interface Data { + /** + * Credits charged for this request. + */ + credits_used: number; + + /** + * The `error_code` from the response, or null on success. + */ + error_code: string | null; + + /** + * What was sent with the request. + */ + input: Data.Input; + + /** + * ID of the API key that made the request. + */ + key_id: string | null; + + /** + * Server-side processing time in milliseconds. + */ + latency_ms: number; + + /** + * HTTP method. + */ + method: string; + + /** + * Endpoint path as called. + */ + path: string; + + /** + * Request ID of the logged API call. + */ + request_id: string; + + /** + * HTTP status code returned. + */ + status_code: number; + + /** + * Request tags supplied by the caller. + */ + tags: Array; + + /** + * When the request completed. + */ + timestamp: string; + + /** + * User-Agent header of the request. + */ + user_agent: string | null; + + /** + * Whether the request was made under zero data retention. + */ + zdr: boolean; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: Data.KeyMetadata; + + /** + * The retained JSON response with credentials redacted, or null when unavailable. + */ + response?: unknown; + } + + export namespace Data { + /** + * What was sent with the request. + */ + export interface Input { + /** + * Query parameters as sent. + */ + query: { [key: string]: unknown }; + + /** + * Request body with credentials and uploaded content redacted. + */ + body?: unknown; + } + + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } + } + + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + +export interface LogListResponse { + /** + * Log entries, newest first. + */ + data: Array; + + /** + * Whether a next page exists. + */ + has_more: boolean; + + /** + * Entries per page. + */ + limit: number; + + /** + * Current page number. + */ + page: number; + + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: LogListResponse.KeyMetadata; +} + +export namespace LogListResponse { + export interface Data { + /** + * Credits charged for this request. + */ + credits_used: number; + + /** + * The `error_code` from the response, or null on success. + */ + error_code: string | null; + + /** + * ID of the API key that made the request. + */ + key_id: string | null; + + /** + * Server-side processing time in milliseconds. + */ + latency_ms: number; + + /** + * HTTP method. + */ + method: string; + + /** + * Endpoint path as called. + */ + path: string; + + /** + * Request ID of the logged API call. + */ + request_id: string; + + /** + * HTTP status code returned. + */ + status_code: number; + + /** + * Request tags supplied by the caller. + */ + tags: Array; + + /** + * When the request completed. + */ + timestamp: string; + + /** + * Whether the request was made under zero data retention. + */ + zdr: boolean; + } + + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + +export interface LogListParams { + /** + * Filter by the `error_code` returned in the response. + */ + error_code?: string; + + /** + * Only include requests that returned a 4xx or 5xx status. + */ + errors_only?: boolean; + + /** + * Only include requests at or after this ISO 8601 timestamp. Defaults to 24 hours + * before `to`. + */ + from?: string; + + /** + * Filter by the API key that made the request. + */ + key_id?: string; + + /** + * Number of log entries per page. + */ + limit?: number; + + /** + * Page number, starting at 1. + */ + page?: number; + + /** + * Filter by endpoint path, with or without the /v1 prefix. + */ + path?: string; + + /** + * Case-insensitive substring match against the request query and body, e.g. a + * domain. + */ + search?: string; + + /** + * Filter by exact HTTP status code. + */ + status_code?: number; + + /** + * Comma-separated request tags. Matches requests carrying any of them. Up to 20 + * tags, each 1-50 characters. + */ + tags?: string; + + /** + * Only include requests at or before this ISO 8601 timestamp. Defaults to now. + */ + to?: string; +} + +export declare namespace Logs { + export { + type LogRetrieveResponse as LogRetrieveResponse, + type LogListResponse as LogListResponse, + type LogListParams as LogListParams, + }; +} diff --git a/tests/api-resources/logs.test.ts b/tests/api-resources/logs.test.ts new file mode 100644 index 00000000..4227b6f8 --- /dev/null +++ b/tests/api-resources/logs.test.ts @@ -0,0 +1,57 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import ContextDev from 'context.dev'; + +const client = new ContextDev({ + apiKey: 'My API Key', + baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', +}); + +describe('resource logs', () => { + // Mock server tests are disabled + test.skip('retrieve', async () => { + const responsePromise = client.logs.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('list', async () => { + const responsePromise = client.logs.list(); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('list: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.logs.list( + { + error_code: 'WEBSITE_ACCESS_ERROR', + errors_only: true, + from: '2026-09-10T00:00:00Z', + key_id: 'x', + limit: 1, + page: 1, + path: '/brand/retrieve', + search: 'acme.com', + status_code: 500, + tags: 'nightly-import,team-alpha', + to: '2026-09-11T00:00:00Z', + }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(ContextDev.NotFoundError); + }); +}); From ac71b320021a463012b05e68c2a1ca8c854eb67e Mon Sep 17 00:00:00 2001 From: contextualbeer Date: Fri, 11 Sep 2026 22:58:13 +0200 Subject: [PATCH 020/232] release: 2.17.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 13 +++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 16 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 7731f20e..9a61761c 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.16.0" + ".": "2.17.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 7bb28e33..32db6779 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,18 @@ # Changelog +## [2.17.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.16.0...v2.17.0) (2026-09-11) + + +### Features + +* **api:** return request_id on every response ([37e1f63](https://github.com/context-dot-dev/context-typescript-sdk/commit/37e1f63aeea80c7ece0a33029864fe2dd40637c4)) +* **logs:** expose request log endpoints in SDKs ([#1025](https://github.com/context-dot-dev/context-typescript-sdk/issues/1025)) ([ca7e22a](https://github.com/context-dot-dev/context-typescript-sdk/commit/ca7e22a3ba12d75961d940fb81d8a36ead6ea761)) + + +### Bug Fixes + +* **api:** reject timeoutMS too short for waitForMs ([a46905a](https://github.com/context-dot-dev/context-typescript-sdk/commit/a46905a650e7d357657b9d27cfca7cf9b784576f)) + ## [2.16.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.15.0...v2.16.0) (2026-09-08) diff --git a/package.json b/package.json index a828fee4..21e26d43 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.16.0", + "version": "2.17.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index f9cc5c13..acffe370 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.16.0'; // x-release-please-version +export const VERSION = '2.17.0'; // x-release-please-version From f27c6338c681d0007ac5b35202e2041b697e3338 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 11 Sep 2026 21:57:04 +0000 Subject: [PATCH 021/232] seal --- .release-please-manifest.json | 2 +- CHANGELOG.md | 13 +++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 16 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 7731f20e..9a61761c 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.16.0" + ".": "2.17.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 7bb28e33..32db6779 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,18 @@ # Changelog +## [2.17.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.16.0...v2.17.0) (2026-09-11) + + +### Features + +* **api:** return request_id on every response ([37e1f63](https://github.com/context-dot-dev/context-typescript-sdk/commit/37e1f63aeea80c7ece0a33029864fe2dd40637c4)) +* **logs:** expose request log endpoints in SDKs ([#1025](https://github.com/context-dot-dev/context-typescript-sdk/issues/1025)) ([ca7e22a](https://github.com/context-dot-dev/context-typescript-sdk/commit/ca7e22a3ba12d75961d940fb81d8a36ead6ea761)) + + +### Bug Fixes + +* **api:** reject timeoutMS too short for waitForMs ([a46905a](https://github.com/context-dot-dev/context-typescript-sdk/commit/a46905a650e7d357657b9d27cfca7cf9b784576f)) + ## [2.16.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.15.0...v2.16.0) (2026-09-08) diff --git a/package.json b/package.json index a828fee4..21e26d43 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.16.0", + "version": "2.17.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index f9cc5c13..acffe370 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.16.0'; // x-release-please-version +export const VERSION = '2.17.0'; // x-release-please-version From db2c9065d92e20c8db5dac07c65e5b1fd289e798 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 12 Sep 2026 19:30:22 +0000 Subject: [PATCH 022/232] fix(security): consolidate dependency updates and harden public fetches (#1040) Stainless-Generated-From: 5e66d2ddaf8874178034fa56736ffdad2f5a5730 --- src/resources/batch.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 3149acd4..afc77b45 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -92,7 +92,9 @@ export class Batch extends APIResource { * ```ts * const response = await client.batch.submit({ * input: { + * mode: 'scrape', * data: { + * format: 'markdown', * urls: [ * { * url: 'https://example.com/products/anvil', From 5e66d2ddaf8874178034fa56736ffdad2f5a5730 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 12 Sep 2026 19:30:22 +0000 Subject: [PATCH 023/232] seal --- src/resources/batch.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 3149acd4..afc77b45 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -92,7 +92,9 @@ export class Batch extends APIResource { * ```ts * const response = await client.batch.submit({ * input: { + * mode: 'scrape', * data: { + * format: 'markdown', * urls: [ * { * url: 'https://example.com/products/anvil', From 25fd26d00df62cd2bc4fc04f246940494e07828b Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 12 Sep 2026 19:55:06 +0000 Subject: [PATCH 024/232] feat(monitors): add page selector filters (#1037) Stainless-Generated-From: ce073648165681b57726fc14b549aa985cfb984f --- src/resources/monitors.ts | 102 +++++++++++++++++++++++++++ tests/api-resources/monitors.test.ts | 2 + 2 files changed, 104 insertions(+) diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index 626a6dbd..25c6bbdf 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -414,6 +414,23 @@ export namespace MonitorCreateResponse { url: string; + /** + * CSS selectors for HTML regions to remove before text extraction. Applied after + * include_selectors; exclusion takes precedence when an element matches both. Omit + * or pass an empty array to apply no explicit exclusions. Changing these selectors + * creates a new baseline. + */ + exclude_selectors?: Array; + + /** + * CSS selectors defining the HTML regions to monitor. Matching subtrees are + * combined in document order before text extraction, instead of automatic + * main-content selection. Omit or pass an empty array to use automatic + * main-content extraction. If the filtered page has no usable text, the run fails + * without replacing the baseline. Changing these selectors creates a new baseline. + */ + include_selectors?: Array; + /** * Plain-language goal describing which page changes matter. When provided without * change_detection, semantic detection is inferred. @@ -768,6 +785,23 @@ export namespace MonitorRetrieveResponse { url: string; + /** + * CSS selectors for HTML regions to remove before text extraction. Applied after + * include_selectors; exclusion takes precedence when an element matches both. Omit + * or pass an empty array to apply no explicit exclusions. Changing these selectors + * creates a new baseline. + */ + exclude_selectors?: Array; + + /** + * CSS selectors defining the HTML regions to monitor. Matching subtrees are + * combined in document order before text extraction, instead of automatic + * main-content selection. Omit or pass an empty array to use automatic + * main-content extraction. If the filtered page has no usable text, the run fails + * without replacing the baseline. Changing these selectors creates a new baseline. + */ + include_selectors?: Array; + /** * Plain-language goal describing which page changes matter. When provided without * change_detection, semantic detection is inferred. @@ -1122,6 +1156,23 @@ export namespace MonitorUpdateResponse { url: string; + /** + * CSS selectors for HTML regions to remove before text extraction. Applied after + * include_selectors; exclusion takes precedence when an element matches both. Omit + * or pass an empty array to apply no explicit exclusions. Changing these selectors + * creates a new baseline. + */ + exclude_selectors?: Array; + + /** + * CSS selectors defining the HTML regions to monitor. Matching subtrees are + * combined in document order before text extraction, instead of automatic + * main-content selection. Omit or pass an empty array to use automatic + * main-content extraction. If the filtered page has no usable text, the run fails + * without replacing the baseline. Changing these selectors creates a new baseline. + */ + include_selectors?: Array; + /** * Plain-language goal describing which page changes matter. When provided without * change_detection, semantic detection is inferred. @@ -1476,6 +1527,23 @@ export namespace MonitorListResponse { url: string; + /** + * CSS selectors for HTML regions to remove before text extraction. Applied after + * include_selectors; exclusion takes precedence when an element matches both. Omit + * or pass an empty array to apply no explicit exclusions. Changing these selectors + * creates a new baseline. + */ + exclude_selectors?: Array; + + /** + * CSS selectors defining the HTML regions to monitor. Matching subtrees are + * combined in document order before text extraction, instead of automatic + * main-content selection. Omit or pass an empty array to use automatic + * main-content extraction. If the filtered page has no usable text, the run fails + * without replacing the baseline. Changing these selectors creates a new baseline. + */ + include_selectors?: Array; + /** * Plain-language goal describing which page changes matter. When provided without * change_detection, semantic detection is inferred. @@ -2186,6 +2254,23 @@ export namespace MonitorCreateParams { url: string; + /** + * CSS selectors for HTML regions to remove before text extraction. Applied after + * include_selectors; exclusion takes precedence when an element matches both. Omit + * or pass an empty array to apply no explicit exclusions. Changing these selectors + * creates a new baseline. + */ + exclude_selectors?: Array; + + /** + * CSS selectors defining the HTML regions to monitor. Matching subtrees are + * combined in document order before text extraction, instead of automatic + * main-content selection. Omit or pass an empty array to use automatic + * main-content extraction. If the filtered page has no usable text, the run fails + * without replacing the baseline. Changing these selectors creates a new baseline. + */ + include_selectors?: Array; + /** * Plain-language goal describing which page changes matter. When provided without * change_detection, semantic detection is inferred. @@ -2421,6 +2506,23 @@ export namespace MonitorUpdateParams { url: string; + /** + * CSS selectors for HTML regions to remove before text extraction. Applied after + * include_selectors; exclusion takes precedence when an element matches both. Omit + * or pass an empty array to apply no explicit exclusions. Changing these selectors + * creates a new baseline. + */ + exclude_selectors?: Array; + + /** + * CSS selectors defining the HTML regions to monitor. Matching subtrees are + * combined in document order before text extraction, instead of automatic + * main-content selection. Omit or pass an empty array to use automatic + * main-content extraction. If the filtered page has no usable text, the run fails + * without replacing the baseline. Changing these selectors creates a new baseline. + */ + include_selectors?: Array; + /** * Plain-language goal describing which page changes matter. When provided without * change_detection, semantic detection is inferred. diff --git a/tests/api-resources/monitors.test.ts b/tests/api-resources/monitors.test.ts index aa8f3b4a..11777b0d 100644 --- a/tests/api-resources/monitors.test.ts +++ b/tests/api-resources/monitors.test.ts @@ -30,6 +30,8 @@ describe('resource monitors', () => { target: { type: 'page', url: 'https://acme.com/pricing', + exclude_selectors: ['.carousel', '[id^="TA_"]'], + include_selectors: ['#attraction-details'], instructions: 'Report pricing or plan availability changes. Ignore counters, timestamps, testimonials, and navigation.', normalize_whitespace: true, From ce073648165681b57726fc14b549aa985cfb984f Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 12 Sep 2026 19:55:06 +0000 Subject: [PATCH 025/232] seal --- src/resources/monitors.ts | 102 +++++++++++++++++++++++++++ tests/api-resources/monitors.test.ts | 2 + 2 files changed, 104 insertions(+) diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index 626a6dbd..25c6bbdf 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -414,6 +414,23 @@ export namespace MonitorCreateResponse { url: string; + /** + * CSS selectors for HTML regions to remove before text extraction. Applied after + * include_selectors; exclusion takes precedence when an element matches both. Omit + * or pass an empty array to apply no explicit exclusions. Changing these selectors + * creates a new baseline. + */ + exclude_selectors?: Array; + + /** + * CSS selectors defining the HTML regions to monitor. Matching subtrees are + * combined in document order before text extraction, instead of automatic + * main-content selection. Omit or pass an empty array to use automatic + * main-content extraction. If the filtered page has no usable text, the run fails + * without replacing the baseline. Changing these selectors creates a new baseline. + */ + include_selectors?: Array; + /** * Plain-language goal describing which page changes matter. When provided without * change_detection, semantic detection is inferred. @@ -768,6 +785,23 @@ export namespace MonitorRetrieveResponse { url: string; + /** + * CSS selectors for HTML regions to remove before text extraction. Applied after + * include_selectors; exclusion takes precedence when an element matches both. Omit + * or pass an empty array to apply no explicit exclusions. Changing these selectors + * creates a new baseline. + */ + exclude_selectors?: Array; + + /** + * CSS selectors defining the HTML regions to monitor. Matching subtrees are + * combined in document order before text extraction, instead of automatic + * main-content selection. Omit or pass an empty array to use automatic + * main-content extraction. If the filtered page has no usable text, the run fails + * without replacing the baseline. Changing these selectors creates a new baseline. + */ + include_selectors?: Array; + /** * Plain-language goal describing which page changes matter. When provided without * change_detection, semantic detection is inferred. @@ -1122,6 +1156,23 @@ export namespace MonitorUpdateResponse { url: string; + /** + * CSS selectors for HTML regions to remove before text extraction. Applied after + * include_selectors; exclusion takes precedence when an element matches both. Omit + * or pass an empty array to apply no explicit exclusions. Changing these selectors + * creates a new baseline. + */ + exclude_selectors?: Array; + + /** + * CSS selectors defining the HTML regions to monitor. Matching subtrees are + * combined in document order before text extraction, instead of automatic + * main-content selection. Omit or pass an empty array to use automatic + * main-content extraction. If the filtered page has no usable text, the run fails + * without replacing the baseline. Changing these selectors creates a new baseline. + */ + include_selectors?: Array; + /** * Plain-language goal describing which page changes matter. When provided without * change_detection, semantic detection is inferred. @@ -1476,6 +1527,23 @@ export namespace MonitorListResponse { url: string; + /** + * CSS selectors for HTML regions to remove before text extraction. Applied after + * include_selectors; exclusion takes precedence when an element matches both. Omit + * or pass an empty array to apply no explicit exclusions. Changing these selectors + * creates a new baseline. + */ + exclude_selectors?: Array; + + /** + * CSS selectors defining the HTML regions to monitor. Matching subtrees are + * combined in document order before text extraction, instead of automatic + * main-content selection. Omit or pass an empty array to use automatic + * main-content extraction. If the filtered page has no usable text, the run fails + * without replacing the baseline. Changing these selectors creates a new baseline. + */ + include_selectors?: Array; + /** * Plain-language goal describing which page changes matter. When provided without * change_detection, semantic detection is inferred. @@ -2186,6 +2254,23 @@ export namespace MonitorCreateParams { url: string; + /** + * CSS selectors for HTML regions to remove before text extraction. Applied after + * include_selectors; exclusion takes precedence when an element matches both. Omit + * or pass an empty array to apply no explicit exclusions. Changing these selectors + * creates a new baseline. + */ + exclude_selectors?: Array; + + /** + * CSS selectors defining the HTML regions to monitor. Matching subtrees are + * combined in document order before text extraction, instead of automatic + * main-content selection. Omit or pass an empty array to use automatic + * main-content extraction. If the filtered page has no usable text, the run fails + * without replacing the baseline. Changing these selectors creates a new baseline. + */ + include_selectors?: Array; + /** * Plain-language goal describing which page changes matter. When provided without * change_detection, semantic detection is inferred. @@ -2421,6 +2506,23 @@ export namespace MonitorUpdateParams { url: string; + /** + * CSS selectors for HTML regions to remove before text extraction. Applied after + * include_selectors; exclusion takes precedence when an element matches both. Omit + * or pass an empty array to apply no explicit exclusions. Changing these selectors + * creates a new baseline. + */ + exclude_selectors?: Array; + + /** + * CSS selectors defining the HTML regions to monitor. Matching subtrees are + * combined in document order before text extraction, instead of automatic + * main-content selection. Omit or pass an empty array to use automatic + * main-content extraction. If the filtered page has no usable text, the run fails + * without replacing the baseline. Changing these selectors creates a new baseline. + */ + include_selectors?: Array; + /** * Plain-language goal describing which page changes matter. When provided without * change_detection, semantic detection is inferred. diff --git a/tests/api-resources/monitors.test.ts b/tests/api-resources/monitors.test.ts index aa8f3b4a..11777b0d 100644 --- a/tests/api-resources/monitors.test.ts +++ b/tests/api-resources/monitors.test.ts @@ -30,6 +30,8 @@ describe('resource monitors', () => { target: { type: 'page', url: 'https://acme.com/pricing', + exclude_selectors: ['.carousel', '[id^="TA_"]'], + include_selectors: ['#attraction-details'], instructions: 'Report pricing or plan availability changes. Ignore counters, timestamps, testimonials, and navigation.', normalize_whitespace: true, From de5e60dcc85e3754302cec35060cffe8c238cd8a Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 12 Sep 2026 20:05:50 +0000 Subject: [PATCH 026/232] feat(api-keys): enforce scoped API key permissions (#1038) Stainless-Generated-From: 33db3d253a6044b67a9af9b2959dfa1204e286f3 --- src/resources/monitors.ts | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index 25c6bbdf..a92e85cc 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -609,7 +609,8 @@ export namespace MonitorCreateResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Each delivery includes an + * Signing secret used to verify webhook authenticity. Omitted unless the API key + * has monitors:write permission or full access. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time * compare and reject stale timestamps to prevent replay. Generated by the API; @@ -980,7 +981,8 @@ export namespace MonitorRetrieveResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Each delivery includes an + * Signing secret used to verify webhook authenticity. Omitted unless the API key + * has monitors:write permission or full access. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time * compare and reject stale timestamps to prevent replay. Generated by the API; @@ -1351,7 +1353,8 @@ export namespace MonitorUpdateResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Each delivery includes an + * Signing secret used to verify webhook authenticity. Omitted unless the API key + * has monitors:write permission or full access. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time * compare and reject stale timestamps to prevent replay. Generated by the API; @@ -1722,7 +1725,8 @@ export namespace MonitorListResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Each delivery includes an + * Signing secret used to verify webhook authenticity. Omitted unless the API key + * has monitors:write permission or full access. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time * compare and reject stale timestamps to prevent replay. Generated by the API; From 33db3d253a6044b67a9af9b2959dfa1204e286f3 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 12 Sep 2026 20:05:50 +0000 Subject: [PATCH 027/232] seal --- src/resources/monitors.ts | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index 25c6bbdf..a92e85cc 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -609,7 +609,8 @@ export namespace MonitorCreateResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Each delivery includes an + * Signing secret used to verify webhook authenticity. Omitted unless the API key + * has monitors:write permission or full access. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time * compare and reject stale timestamps to prevent replay. Generated by the API; @@ -980,7 +981,8 @@ export namespace MonitorRetrieveResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Each delivery includes an + * Signing secret used to verify webhook authenticity. Omitted unless the API key + * has monitors:write permission or full access. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time * compare and reject stale timestamps to prevent replay. Generated by the API; @@ -1351,7 +1353,8 @@ export namespace MonitorUpdateResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Each delivery includes an + * Signing secret used to verify webhook authenticity. Omitted unless the API key + * has monitors:write permission or full access. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time * compare and reject stale timestamps to prevent replay. Generated by the API; @@ -1722,7 +1725,8 @@ export namespace MonitorListResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Each delivery includes an + * Signing secret used to verify webhook authenticity. Omitted unless the API key + * has monitors:write permission or full access. Each delivery includes an * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time * compare and reject stale timestamps to prevent replay. Generated by the API; From 961534544b1fd85fdc351be36d7f8a4ba54b5da7 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 13 Sep 2026 01:08:33 +0000 Subject: [PATCH 028/232] fix(webhooks): format Slack webhook notifications (#1045) Stainless-Generated-From: 98e5f94d5946b22c8cfb55e56c8a359069e21f96 --- src/resources/monitors.ts | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index a92e85cc..ab847006 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -591,7 +591,8 @@ export namespace MonitorCreateResponse { export interface Webhook { /** - * Webhook URL events are delivered to. + * Webhook URL events are delivered to. Slack incoming webhook URLs are + * automatically formatted as Slack messages. */ url: string; @@ -963,7 +964,8 @@ export namespace MonitorRetrieveResponse { export interface Webhook { /** - * Webhook URL events are delivered to. + * Webhook URL events are delivered to. Slack incoming webhook URLs are + * automatically formatted as Slack messages. */ url: string; @@ -1335,7 +1337,8 @@ export namespace MonitorUpdateResponse { export interface Webhook { /** - * Webhook URL events are delivered to. + * Webhook URL events are delivered to. Slack incoming webhook URLs are + * automatically formatted as Slack messages. */ url: string; @@ -1707,7 +1710,8 @@ export namespace MonitorListResponse { export interface Webhook { /** - * Webhook URL events are delivered to. + * Webhook URL events are delivered to. Slack incoming webhook URLs are + * automatically formatted as Slack messages. */ url: string; @@ -2404,7 +2408,8 @@ export namespace MonitorCreateParams { export interface Webhook { /** - * Webhook URL events are delivered to. + * Webhook URL events are delivered to. Slack incoming webhook URLs are + * automatically formatted as Slack messages. */ url: string; @@ -2621,7 +2626,8 @@ export namespace MonitorUpdateParams { */ export interface Webhook { /** - * Webhook URL events are delivered to. + * Webhook URL events are delivered to. Slack incoming webhook URLs are + * automatically formatted as Slack messages. */ url: string; From 98e5f94d5946b22c8cfb55e56c8a359069e21f96 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 13 Sep 2026 01:08:33 +0000 Subject: [PATCH 029/232] seal --- src/resources/monitors.ts | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index a92e85cc..ab847006 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -591,7 +591,8 @@ export namespace MonitorCreateResponse { export interface Webhook { /** - * Webhook URL events are delivered to. + * Webhook URL events are delivered to. Slack incoming webhook URLs are + * automatically formatted as Slack messages. */ url: string; @@ -963,7 +964,8 @@ export namespace MonitorRetrieveResponse { export interface Webhook { /** - * Webhook URL events are delivered to. + * Webhook URL events are delivered to. Slack incoming webhook URLs are + * automatically formatted as Slack messages. */ url: string; @@ -1335,7 +1337,8 @@ export namespace MonitorUpdateResponse { export interface Webhook { /** - * Webhook URL events are delivered to. + * Webhook URL events are delivered to. Slack incoming webhook URLs are + * automatically formatted as Slack messages. */ url: string; @@ -1707,7 +1710,8 @@ export namespace MonitorListResponse { export interface Webhook { /** - * Webhook URL events are delivered to. + * Webhook URL events are delivered to. Slack incoming webhook URLs are + * automatically formatted as Slack messages. */ url: string; @@ -2404,7 +2408,8 @@ export namespace MonitorCreateParams { export interface Webhook { /** - * Webhook URL events are delivered to. + * Webhook URL events are delivered to. Slack incoming webhook URLs are + * automatically formatted as Slack messages. */ url: string; @@ -2621,7 +2626,8 @@ export namespace MonitorUpdateParams { */ export interface Webhook { /** - * Webhook URL events are delivered to. + * Webhook URL events are delivered to. Slack incoming webhook URLs are + * automatically formatted as Slack messages. */ url: string; From 503a20ed84b09182432bc164c2d4bfe6ca386505 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 13 Sep 2026 02:19:33 +0000 Subject: [PATCH 030/232] fix(api): honour maxAgeMs=0 on brand retrieve, styleguide and fonts endpoints (#998) Stainless-Generated-From: b67ac75cc87e095a144703101fdd35de97d878dc --- src/resources/brand.ts | 30 +++++++++++++++--------------- src/resources/web.ts | 12 ++++++------ 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 5ea88c6a..39b08183 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -1334,9 +1334,9 @@ export declare namespace BrandRetrieveParams { /** * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) - * are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 - * year. + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ maxAgeMs?: number; @@ -1502,9 +1502,9 @@ export declare namespace BrandRetrieveParams { /** * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) - * are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 - * year. + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ maxAgeMs?: number; @@ -1664,9 +1664,9 @@ export declare namespace BrandRetrieveParams { /** * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) - * are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 - * year. + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ maxAgeMs?: number; @@ -1826,9 +1826,9 @@ export declare namespace BrandRetrieveParams { /** * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) - * are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 - * year. + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ maxAgeMs?: number; @@ -2074,9 +2074,9 @@ export interface BrandRetrieveSimplifiedParams { /** * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) - * are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 - * year. + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ maxAgeMs?: number | null; diff --git a/src/resources/web.ts b/src/resources/web.ts index e50fb665..2b20f999 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2608,9 +2608,9 @@ export interface WebExtractFontsParams { /** * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) - * are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 - * year. + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ maxAgeMs?: number | null; @@ -2652,9 +2652,9 @@ export interface WebExtractStyleguideParams { /** * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) - * are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 - * year. + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ maxAgeMs?: number | null; From b67ac75cc87e095a144703101fdd35de97d878dc Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 13 Sep 2026 02:19:33 +0000 Subject: [PATCH 031/232] seal --- src/resources/brand.ts | 30 +++++++++++++++--------------- src/resources/web.ts | 12 ++++++------ 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 5ea88c6a..39b08183 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -1334,9 +1334,9 @@ export declare namespace BrandRetrieveParams { /** * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) - * are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 - * year. + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ maxAgeMs?: number; @@ -1502,9 +1502,9 @@ export declare namespace BrandRetrieveParams { /** * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) - * are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 - * year. + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ maxAgeMs?: number; @@ -1664,9 +1664,9 @@ export declare namespace BrandRetrieveParams { /** * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) - * are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 - * year. + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ maxAgeMs?: number; @@ -1826,9 +1826,9 @@ export declare namespace BrandRetrieveParams { /** * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) - * are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 - * year. + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ maxAgeMs?: number; @@ -2074,9 +2074,9 @@ export interface BrandRetrieveSimplifiedParams { /** * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) - * are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 - * year. + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ maxAgeMs?: number | null; diff --git a/src/resources/web.ts b/src/resources/web.ts index e50fb665..2b20f999 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2608,9 +2608,9 @@ export interface WebExtractFontsParams { /** * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) - * are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 - * year. + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ maxAgeMs?: number | null; @@ -2652,9 +2652,9 @@ export interface WebExtractStyleguideParams { /** * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Values below 1 day (86400000 ms) - * are clamped to 1 day; values above 1 year (31536000000 ms) are clamped to 1 - * year. + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ maxAgeMs?: number | null; From 8d9f4882f87378e63dcfd8737e067c9b17770406 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 13 Sep 2026 02:36:35 +0000 Subject: [PATCH 032/232] feat(answers): add live web research with fast and ultra modes (#954) Stainless-Generated-From: a7bec044880b22e79a3584134cbb8f15e26c9521 --- .stats.yml | 2 +- api.md | 2 + src/client.ts | 4 ++ src/resources/index.ts | 2 + src/resources/web.ts | 95 +++++++++++++++++++++++++++++++++ tests/api-resources/web.test.ts | 25 +++++++++ 6 files changed, 129 insertions(+), 1 deletion(-) diff --git a/.stats.yml b/.stats.yml index 006b15f4..58526a77 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 47 +configured_endpoints: 48 diff --git a/api.md b/api.md index 7597ed86..2b893367 100644 --- a/api.md +++ b/api.md @@ -12,6 +12,7 @@ Methods: Types: +- WebAnswersResponse - WebExtractResponse - WebExtractCompetitorsResponse - WebExtractFontsResponse @@ -26,6 +27,7 @@ Types: Methods: +- client.web.answers({ ...params }) -> WebAnswersResponse - client.web.extract({ ...params }) -> WebExtractResponse - client.web.extractCompetitors({ ...params }) -> WebExtractCompetitorsResponse - client.web.extractFonts({ ...params }) -> WebExtractFontsResponse diff --git a/src/client.ts b/src/client.ts index 1911624e..37b908a3 100644 --- a/src/client.ts +++ b/src/client.ts @@ -88,6 +88,8 @@ import { People, PersonEnrichParams, PersonEnrichResponse } from './resources/pe import { Utility, UtilityPrefetchParams, UtilityPrefetchResponse } from './resources/utility'; import { Web, + WebAnswersParams, + WebAnswersResponse, WebExtractCompetitorsParams, WebExtractCompetitorsResponse, WebExtractFontsParams, @@ -879,6 +881,7 @@ export declare namespace ContextDev { export { Web as Web, + type WebAnswersResponse as WebAnswersResponse, type WebExtractResponse as WebExtractResponse, type WebExtractCompetitorsResponse as WebExtractCompetitorsResponse, type WebExtractFontsResponse as WebExtractFontsResponse, @@ -890,6 +893,7 @@ export declare namespace ContextDev { type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, type WebWebScrapeMdResponse as WebWebScrapeMdResponse, type WebWebScrapeSitemapResponse as WebWebScrapeSitemapResponse, + type WebAnswersParams as WebAnswersParams, type WebExtractParams as WebExtractParams, type WebExtractCompetitorsParams as WebExtractCompetitorsParams, type WebExtractFontsParams as WebExtractFontsParams, diff --git a/src/resources/index.ts b/src/resources/index.ts index b7d3e275..55e34fce 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -71,6 +71,7 @@ export { People, type PersonEnrichResponse, type PersonEnrichParams } from './pe export { Utility, type UtilityPrefetchResponse, type UtilityPrefetchParams } from './utility'; export { Web, + type WebAnswersResponse, type WebExtractResponse, type WebExtractCompetitorsResponse, type WebExtractFontsResponse, @@ -82,6 +83,7 @@ export { type WebWebScrapeImagesResponse, type WebWebScrapeMdResponse, type WebWebScrapeSitemapResponse, + type WebAnswersParams, type WebExtractParams, type WebExtractCompetitorsParams, type WebExtractFontsParams, diff --git a/src/resources/web.ts b/src/resources/web.ts index 2b20f999..0208cb9e 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -5,6 +5,28 @@ import { APIPromise } from '../core/api-promise'; import { RequestOptions } from '../internal/request-options'; export class Web extends APIResource { + /** + * Researches the live web and returns a sourced answer in your requested JSON + * shape. Select fast for a smaller research budget at 10 credits or ultra for + * deeper reasoning at 100 credits. Defaults to ultra. Fast research is limited to + * 30 seconds and ultra to 50 seconds; timeoutMS can shorten either deadline. + * + * @example + * ```ts + * const response = await client.web.answers({ + * task: 'Find the pricing page URL and plan names for context.dev.', + * json_format: { + * pricing_page_url: '', + * plans: [{ name: '' }], + * }, + * mode: 'fast', + * }); + * ``` + */ + answers(body: WebAnswersParams, options?: RequestOptions): APIPromise { + return this._client.post('/web/answers', { body, ...options }); + } + /** * Crawl a website, use the provided JSON Schema and instructions to prioritize * relevant internal links, and extract structured data from the selected pages. @@ -222,6 +244,41 @@ export class Web extends APIResource { } } +export interface WebAnswersResponse { + /** + * The answer, in the shape requested by json_format. + */ + json_content: { [key: string]: unknown }; + + /** + * URLs that supplied search results or readable page content, in first-seen order. + * Unreadable pages are excluded. + */ + sources: Array; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: WebAnswersResponse.KeyMetadata; +} + +export namespace WebAnswersResponse { + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + export interface WebExtractResponse { /** * Cache outcome for this response. Composite responses are hits only when every @@ -2391,6 +2448,42 @@ export namespace WebWebScrapeSitemapResponse { } } +export interface WebAnswersParams { + /** + * What to research and answer, in plain language. Naming a domain in the task (for + * example "pricing on context.dev") makes the agent read that site before it + * searches. + */ + task: string; + + /** + * An example object with placeholder values (for example {"pricing_page_url": "", + * "plans": [{"name": "", "price": 0}]}). Object keys and value types are + * preserved; unknown values may be null. Empty arrays accept any JSON items. + * Defaults to {"result": ""}. Maximum 8 levels, 500 values, and 16000 characters. + */ + json_format?: { [key: string]: unknown }; + + /** + * Research level: fast uses a smaller model and research budget for 10 credits; + * ultra uses deeper reasoning and research for 100 credits. Defaults to ultra. + * Only successful requests consume credits. + */ + mode?: 'fast' | 'ultra'; + + /** + * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + */ + tags?: Array; + + /** + * Optional timeout in milliseconds for the request. If the request takes longer + * than this value, it will be aborted with a 408 status code. Maximum allowed + * value is 300000ms (5 minutes). + */ + timeoutMS?: number; +} + export interface WebExtractParams { /** * JSON Schema for the returned data object. Image fields such as `image_urls` or @@ -4769,6 +4862,7 @@ export interface WebWebScrapeSitemapParams { export declare namespace Web { export { + type WebAnswersResponse as WebAnswersResponse, type WebExtractResponse as WebExtractResponse, type WebExtractCompetitorsResponse as WebExtractCompetitorsResponse, type WebExtractFontsResponse as WebExtractFontsResponse, @@ -4780,6 +4874,7 @@ export declare namespace Web { type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, type WebWebScrapeMdResponse as WebWebScrapeMdResponse, type WebWebScrapeSitemapResponse as WebWebScrapeSitemapResponse, + type WebAnswersParams as WebAnswersParams, type WebExtractParams as WebExtractParams, type WebExtractCompetitorsParams as WebExtractCompetitorsParams, type WebExtractFontsParams as WebExtractFontsParams, diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index a513bb93..9f1ce931 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -8,6 +8,31 @@ const client = new ContextDev({ }); describe('resource web', () => { + // Mock server tests are disabled + test.skip('answers: only required params', async () => { + const responsePromise = client.web.answers({ + task: 'Find the pricing page URL and plan names for context.dev.', + }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('answers: required and optional params', async () => { + const response = await client.web.answers({ + task: 'Find the pricing page URL and plan names for context.dev.', + json_format: { pricing_page_url: 'bar', plans: 'bar' }, + mode: 'fast', + tags: ['production', 'team-alpha'], + timeoutMS: 1000, + }); + }); + // Mock server tests are disabled test.skip('extract: only required params', async () => { const responsePromise = client.web.extract({ From a7bec044880b22e79a3584134cbb8f15e26c9521 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 13 Sep 2026 02:36:35 +0000 Subject: [PATCH 033/232] seal --- .stats.yml | 2 +- api.md | 2 + src/client.ts | 4 ++ src/resources/index.ts | 2 + src/resources/web.ts | 95 +++++++++++++++++++++++++++++++++ tests/api-resources/web.test.ts | 25 +++++++++ 6 files changed, 129 insertions(+), 1 deletion(-) diff --git a/.stats.yml b/.stats.yml index 006b15f4..58526a77 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 47 +configured_endpoints: 48 diff --git a/api.md b/api.md index 7597ed86..2b893367 100644 --- a/api.md +++ b/api.md @@ -12,6 +12,7 @@ Methods: Types: +- WebAnswersResponse - WebExtractResponse - WebExtractCompetitorsResponse - WebExtractFontsResponse @@ -26,6 +27,7 @@ Types: Methods: +- client.web.answers({ ...params }) -> WebAnswersResponse - client.web.extract({ ...params }) -> WebExtractResponse - client.web.extractCompetitors({ ...params }) -> WebExtractCompetitorsResponse - client.web.extractFonts({ ...params }) -> WebExtractFontsResponse diff --git a/src/client.ts b/src/client.ts index 1911624e..37b908a3 100644 --- a/src/client.ts +++ b/src/client.ts @@ -88,6 +88,8 @@ import { People, PersonEnrichParams, PersonEnrichResponse } from './resources/pe import { Utility, UtilityPrefetchParams, UtilityPrefetchResponse } from './resources/utility'; import { Web, + WebAnswersParams, + WebAnswersResponse, WebExtractCompetitorsParams, WebExtractCompetitorsResponse, WebExtractFontsParams, @@ -879,6 +881,7 @@ export declare namespace ContextDev { export { Web as Web, + type WebAnswersResponse as WebAnswersResponse, type WebExtractResponse as WebExtractResponse, type WebExtractCompetitorsResponse as WebExtractCompetitorsResponse, type WebExtractFontsResponse as WebExtractFontsResponse, @@ -890,6 +893,7 @@ export declare namespace ContextDev { type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, type WebWebScrapeMdResponse as WebWebScrapeMdResponse, type WebWebScrapeSitemapResponse as WebWebScrapeSitemapResponse, + type WebAnswersParams as WebAnswersParams, type WebExtractParams as WebExtractParams, type WebExtractCompetitorsParams as WebExtractCompetitorsParams, type WebExtractFontsParams as WebExtractFontsParams, diff --git a/src/resources/index.ts b/src/resources/index.ts index b7d3e275..55e34fce 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -71,6 +71,7 @@ export { People, type PersonEnrichResponse, type PersonEnrichParams } from './pe export { Utility, type UtilityPrefetchResponse, type UtilityPrefetchParams } from './utility'; export { Web, + type WebAnswersResponse, type WebExtractResponse, type WebExtractCompetitorsResponse, type WebExtractFontsResponse, @@ -82,6 +83,7 @@ export { type WebWebScrapeImagesResponse, type WebWebScrapeMdResponse, type WebWebScrapeSitemapResponse, + type WebAnswersParams, type WebExtractParams, type WebExtractCompetitorsParams, type WebExtractFontsParams, diff --git a/src/resources/web.ts b/src/resources/web.ts index 2b20f999..0208cb9e 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -5,6 +5,28 @@ import { APIPromise } from '../core/api-promise'; import { RequestOptions } from '../internal/request-options'; export class Web extends APIResource { + /** + * Researches the live web and returns a sourced answer in your requested JSON + * shape. Select fast for a smaller research budget at 10 credits or ultra for + * deeper reasoning at 100 credits. Defaults to ultra. Fast research is limited to + * 30 seconds and ultra to 50 seconds; timeoutMS can shorten either deadline. + * + * @example + * ```ts + * const response = await client.web.answers({ + * task: 'Find the pricing page URL and plan names for context.dev.', + * json_format: { + * pricing_page_url: '', + * plans: [{ name: '' }], + * }, + * mode: 'fast', + * }); + * ``` + */ + answers(body: WebAnswersParams, options?: RequestOptions): APIPromise { + return this._client.post('/web/answers', { body, ...options }); + } + /** * Crawl a website, use the provided JSON Schema and instructions to prioritize * relevant internal links, and extract structured data from the selected pages. @@ -222,6 +244,41 @@ export class Web extends APIResource { } } +export interface WebAnswersResponse { + /** + * The answer, in the shape requested by json_format. + */ + json_content: { [key: string]: unknown }; + + /** + * URLs that supplied search results or readable page content, in first-seen order. + * Unreadable pages are excluded. + */ + sources: Array; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: WebAnswersResponse.KeyMetadata; +} + +export namespace WebAnswersResponse { + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + export interface WebExtractResponse { /** * Cache outcome for this response. Composite responses are hits only when every @@ -2391,6 +2448,42 @@ export namespace WebWebScrapeSitemapResponse { } } +export interface WebAnswersParams { + /** + * What to research and answer, in plain language. Naming a domain in the task (for + * example "pricing on context.dev") makes the agent read that site before it + * searches. + */ + task: string; + + /** + * An example object with placeholder values (for example {"pricing_page_url": "", + * "plans": [{"name": "", "price": 0}]}). Object keys and value types are + * preserved; unknown values may be null. Empty arrays accept any JSON items. + * Defaults to {"result": ""}. Maximum 8 levels, 500 values, and 16000 characters. + */ + json_format?: { [key: string]: unknown }; + + /** + * Research level: fast uses a smaller model and research budget for 10 credits; + * ultra uses deeper reasoning and research for 100 credits. Defaults to ultra. + * Only successful requests consume credits. + */ + mode?: 'fast' | 'ultra'; + + /** + * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + */ + tags?: Array; + + /** + * Optional timeout in milliseconds for the request. If the request takes longer + * than this value, it will be aborted with a 408 status code. Maximum allowed + * value is 300000ms (5 minutes). + */ + timeoutMS?: number; +} + export interface WebExtractParams { /** * JSON Schema for the returned data object. Image fields such as `image_urls` or @@ -4769,6 +4862,7 @@ export interface WebWebScrapeSitemapParams { export declare namespace Web { export { + type WebAnswersResponse as WebAnswersResponse, type WebExtractResponse as WebExtractResponse, type WebExtractCompetitorsResponse as WebExtractCompetitorsResponse, type WebExtractFontsResponse as WebExtractFontsResponse, @@ -4780,6 +4874,7 @@ export declare namespace Web { type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, type WebWebScrapeMdResponse as WebWebScrapeMdResponse, type WebWebScrapeSitemapResponse as WebWebScrapeSitemapResponse, + type WebAnswersParams as WebAnswersParams, type WebExtractParams as WebExtractParams, type WebExtractCompetitorsParams as WebExtractCompetitorsParams, type WebExtractFontsParams as WebExtractFontsParams, diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index a513bb93..9f1ce931 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -8,6 +8,31 @@ const client = new ContextDev({ }); describe('resource web', () => { + // Mock server tests are disabled + test.skip('answers: only required params', async () => { + const responsePromise = client.web.answers({ + task: 'Find the pricing page URL and plan names for context.dev.', + }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('answers: required and optional params', async () => { + const response = await client.web.answers({ + task: 'Find the pricing page URL and plan names for context.dev.', + json_format: { pricing_page_url: 'bar', plans: 'bar' }, + mode: 'fast', + tags: ['production', 'team-alpha'], + timeoutMS: 1000, + }); + }); + // Mock server tests are disabled test.skip('extract: only required params', async () => { const responsePromise = client.web.extract({ From 087f472a672be9479401821007d821bd7c2de0e7 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 15 Sep 2026 00:45:51 +0000 Subject: [PATCH 034/232] Build SDK Stainless-Generated-From: ef53cad9bcf22a4acaa0369cd5ec94681140a5cf --- yarn.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/yarn.lock b/yarn.lock index f16b683a..a3d6b14e 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1228,9 +1228,9 @@ baseline-browser-mapping@^2.9.0: integrity sha512-B0xUquLkiGLgHhpPBqvl7GWegWBUNuujQ6kXd/r1U38ElPT6Ok8KZ8e+FpUGEc2ZoRQUzq/aUnaKFc/svWUGSg== brace-expansion@^2.0.2: - version "2.1.4" - resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.1.4.tgz#589dab11c0018d0366be64cd8bf12c8dbecc8326" - integrity sha512-hGfVzPxthbf3+2yjg/RBs60cB0FhqBS/zvdV/4wn4/BmN0bNMMHPc4V/BbFieqf1TKAGGAHnY4eSjajCl0f2Xg== + version "2.1.7" + resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.1.7.tgz#14ea3836731823bb24740225ea43b941b436f9d1" + integrity sha512-uZbew1NqdmPDTMJ8ah1y+b+9QEJrfkXFk3RcTQw3X0jW/xRUvFKsg1CfQdSYGdTbXZWExtU3J3ccxtnfw1Fi0g== dependencies: balanced-match "^1.0.0" From ef53cad9bcf22a4acaa0369cd5ec94681140a5cf Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 15 Sep 2026 00:45:51 +0000 Subject: [PATCH 035/232] seal --- yarn.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/yarn.lock b/yarn.lock index f16b683a..a3d6b14e 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1228,9 +1228,9 @@ baseline-browser-mapping@^2.9.0: integrity sha512-B0xUquLkiGLgHhpPBqvl7GWegWBUNuujQ6kXd/r1U38ElPT6Ok8KZ8e+FpUGEc2ZoRQUzq/aUnaKFc/svWUGSg== brace-expansion@^2.0.2: - version "2.1.4" - resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.1.4.tgz#589dab11c0018d0366be64cd8bf12c8dbecc8326" - integrity sha512-hGfVzPxthbf3+2yjg/RBs60cB0FhqBS/zvdV/4wn4/BmN0bNMMHPc4V/BbFieqf1TKAGGAHnY4eSjajCl0f2Xg== + version "2.1.7" + resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.1.7.tgz#14ea3836731823bb24740225ea43b941b436f9d1" + integrity sha512-uZbew1NqdmPDTMJ8ah1y+b+9QEJrfkXFk3RcTQw3X0jW/xRUvFKsg1CfQdSYGdTbXZWExtU3J3ccxtnfw1Fi0g== dependencies: balanced-match "^1.0.0" From dec6eb854b4c25592a3c6eeb065e195417ab4cb4 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 15 Sep 2026 07:52:50 +0000 Subject: [PATCH 036/232] feat(web): add raw bytes scraping endpoint (#1081) Stainless-Generated-From: d1a5b059daea95fdef71e71f14d087e66de1e1ca --- .stats.yml | 2 +- api.md | 2 + src/client.ts | 4 + src/resources/index.ts | 2 + src/resources/web.ts | 341 ++++++++++++++++++++++++++++++++ tests/api-resources/web.test.ts | 24 +++ 6 files changed, 374 insertions(+), 1 deletion(-) diff --git a/.stats.yml b/.stats.yml index 58526a77..85f79b6a 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 48 +configured_endpoints: 49 diff --git a/api.md b/api.md index 2b893367..285cb482 100644 --- a/api.md +++ b/api.md @@ -20,6 +20,7 @@ Types: - WebScreenshotResponse - WebSearchResponse - WebWebCrawlMdResponse +- WebWebScrapeBytesResponse - WebWebScrapeHTMLResponse - WebWebScrapeImagesResponse - WebWebScrapeMdResponse @@ -35,6 +36,7 @@ Methods: - client.web.screenshot({ ...params }) -> WebScreenshotResponse - client.web.search({ ...params }) -> WebSearchResponse - client.web.webCrawlMd({ ...params }) -> WebWebCrawlMdResponse +- client.web.webScrapeBytes({ ...params }) -> WebWebScrapeBytesResponse - client.web.webScrapeHTML({ ...params }) -> WebWebScrapeHTMLResponse - client.web.webScrapeImages({ ...params }) -> WebWebScrapeImagesResponse - client.web.webScrapeMd({ ...params }) -> WebWebScrapeMdResponse diff --git a/src/client.ts b/src/client.ts index 37b908a3..35611ddf 100644 --- a/src/client.ts +++ b/src/client.ts @@ -104,6 +104,8 @@ import { WebSearchResponse, WebWebCrawlMdParams, WebWebCrawlMdResponse, + WebWebScrapeBytesParams, + WebWebScrapeBytesResponse, WebWebScrapeHTMLParams, WebWebScrapeHTMLResponse, WebWebScrapeImagesParams, @@ -889,6 +891,7 @@ export declare namespace ContextDev { type WebScreenshotResponse as WebScreenshotResponse, type WebSearchResponse as WebSearchResponse, type WebWebCrawlMdResponse as WebWebCrawlMdResponse, + type WebWebScrapeBytesResponse as WebWebScrapeBytesResponse, type WebWebScrapeHTMLResponse as WebWebScrapeHTMLResponse, type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, type WebWebScrapeMdResponse as WebWebScrapeMdResponse, @@ -901,6 +904,7 @@ export declare namespace ContextDev { type WebScreenshotParams as WebScreenshotParams, type WebSearchParams as WebSearchParams, type WebWebCrawlMdParams as WebWebCrawlMdParams, + type WebWebScrapeBytesParams as WebWebScrapeBytesParams, type WebWebScrapeHTMLParams as WebWebScrapeHTMLParams, type WebWebScrapeImagesParams as WebWebScrapeImagesParams, type WebWebScrapeMdParams as WebWebScrapeMdParams, diff --git a/src/resources/index.ts b/src/resources/index.ts index 55e34fce..47b621a2 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -79,6 +79,7 @@ export { type WebScreenshotResponse, type WebSearchResponse, type WebWebCrawlMdResponse, + type WebWebScrapeBytesResponse, type WebWebScrapeHTMLResponse, type WebWebScrapeImagesResponse, type WebWebScrapeMdResponse, @@ -91,6 +92,7 @@ export { type WebScreenshotParams, type WebSearchParams, type WebWebCrawlMdParams, + type WebWebScrapeBytesParams, type WebWebScrapeHTMLParams, type WebWebScrapeImagesParams, type WebWebScrapeMdParams, diff --git a/src/resources/web.ts b/src/resources/web.ts index 0208cb9e..dc3a2f94 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -140,6 +140,32 @@ export class Web extends APIResource { return this._client.post('/web/crawl', { body, ...options }); } + /** + * Downloads a resource and returns its bytes as base64. Supports images, PDFs, + * HTML pages, and any other content type without image conversion, text + * extraction, or character-encoding changes. HTTP compression is decoded before + * base64 encoding. HTML is the original HTTP response; JavaScript is not rendered. + * Follows public redirects and retries failed downloads through ISP and + * residential proxies, with a direct fallback. When country is specified, only a + * residential proxy in that country is used. Supply headers such as Referer for + * images that require a referring page. Downloads are not cached. Maximum decoded + * resource size: 20 MiB (20971520 bytes), before base64 encoding. Successful + * requests cost 1 credit; errors are not billed. + * + * @example + * ```ts + * const response = await client.web.webScrapeBytes({ + * url: 'https://example.com', + * }); + * ``` + */ + webScrapeBytes( + query: WebWebScrapeBytesParams, + options?: RequestOptions, + ): APIPromise { + return this._client.get('/web/scrape/bytes', { query, ...options }); + } + /** * Scrapes the given URL and returns the raw HTML content of the page. The base * request costs 1 credit; requests with browser actions cost 2 credits. @@ -1673,6 +1699,72 @@ export namespace WebWebCrawlMdResponse { } } +export interface WebWebScrapeBytesResponse { + /** + * Base64-encoded resource bytes, without a data URI prefix. Decode this field to + * recover the downloaded file. + */ + bytes: string; + + /** + * Number of decoded resource bytes, before base64 encoding. + */ + contentLength: number; + + /** + * The Content-Type returned by the origin, including any charset. Defaults to + * application/octet-stream when absent. + */ + contentType: string; + + encoding: 'base64'; + + /** + * The resource URL after redirects. + */ + finalUrl: string; + + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + + /** + * HTTP status returned by the origin. + */ + statusCode: number; + + success: true; + + /** + * The requested resource URL. + */ + url: string; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: WebWebScrapeBytesResponse.KeyMetadata; +} + +export namespace WebWebScrapeBytesResponse { + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + export interface WebWebScrapeHTMLResponse { /** * Cache outcome for this response. Composite responses are hits only when every @@ -3848,6 +3940,253 @@ export namespace WebWebCrawlMdParams { } } +export interface WebWebScrapeBytesParams { + /** + * Full HTTP(S) URL of the resource to download, such as an image, PDF, or page. + */ + url: string; + + /** + * Fetch the target page through a residential proxy in this country (ISO 3166-1 + * alpha-2). + */ + country?: + | 'ad' + | 'ae' + | 'af' + | 'ag' + | 'ai' + | 'al' + | 'am' + | 'ao' + | 'ar' + | 'at' + | 'au' + | 'aw' + | 'az' + | 'ba' + | 'bb' + | 'bd' + | 'be' + | 'bf' + | 'bg' + | 'bh' + | 'bi' + | 'bj' + | 'bm' + | 'bn' + | 'bo' + | 'bq' + | 'br' + | 'bs' + | 'bw' + | 'by' + | 'bz' + | 'ca' + | 'cd' + | 'cf' + | 'cg' + | 'ch' + | 'ci' + | 'cl' + | 'cm' + | 'cn' + | 'co' + | 'cr' + | 'cv' + | 'cw' + | 'cy' + | 'cz' + | 'de' + | 'dj' + | 'dk' + | 'dm' + | 'do' + | 'dz' + | 'ec' + | 'ee' + | 'eg' + | 'es' + | 'et' + | 'fi' + | 'fj' + | 'fr' + | 'ga' + | 'gb' + | 'gd' + | 'ge' + | 'gf' + | 'gg' + | 'gh' + | 'gm' + | 'gn' + | 'gp' + | 'gq' + | 'gr' + | 'gt' + | 'gu' + | 'gw' + | 'gy' + | 'hk' + | 'hn' + | 'hr' + | 'ht' + | 'hu' + | 'id' + | 'ie' + | 'il' + | 'im' + | 'in' + | 'iq' + | 'ir' + | 'is' + | 'it' + | 'je' + | 'jm' + | 'jo' + | 'jp' + | 'ke' + | 'kg' + | 'kh' + | 'kn' + | 'kr' + | 'kw' + | 'ky' + | 'kz' + | 'la' + | 'lb' + | 'lc' + | 'lk' + | 'lr' + | 'ls' + | 'lt' + | 'lu' + | 'lv' + | 'ly' + | 'ma' + | 'mc' + | 'md' + | 'me' + | 'mf' + | 'mg' + | 'mk' + | 'ml' + | 'mm' + | 'mn' + | 'mo' + | 'mq' + | 'mr' + | 'mt' + | 'mu' + | 'mv' + | 'mw' + | 'mx' + | 'my' + | 'mz' + | 'na' + | 'nc' + | 'ne' + | 'ng' + | 'ni' + | 'nl' + | 'no' + | 'np' + | 'nz' + | 'om' + | 'pa' + | 'pe' + | 'pf' + | 'pg' + | 'ph' + | 'pk' + | 'pl' + | 'pr' + | 'ps' + | 'pt' + | 'py' + | 'qa' + | 're' + | 'ro' + | 'rs' + | 'ru' + | 'rw' + | 'sa' + | 'sc' + | 'sd' + | 'se' + | 'sg' + | 'si' + | 'sk' + | 'sl' + | 'sm' + | 'sn' + | 'so' + | 'sr' + | 'ss' + | 'st' + | 'sv' + | 'sx' + | 'sy' + | 'sz' + | 'tc' + | 'td' + | 'tg' + | 'th' + | 'tj' + | 'tl' + | 'tm' + | 'tn' + | 'tr' + | 'tt' + | 'tw' + | 'tz' + | 'ua' + | 'ug' + | 'us' + | 'uy' + | 'uz' + | 'vc' + | 've' + | 'vg' + | 'vi' + | 'vn' + | 'ye' + | 'yt' + | 'za' + | 'zm' + | 'zw'; + + /** + * Optional outbound HTTP headers, such as Referer, Cookie, or Authorization. Send + * as a JSON object or deep-object query params such as + * headers[Referer]=https://example.com/. Host, Content-Length, and hop-by-hop + * transport headers are rejected. Authorization and cookies are removed when a + * redirect changes origin. + */ + headers?: { [key: string]: string }; + + /** + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. + */ + tags?: Array; + + /** + * Optional timeout in milliseconds for the request. If the request takes longer + * than this value, it will be aborted with a 408 status code. Maximum allowed + * value is 300000ms (5 minutes). + */ + timeoutMS?: number; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Requires zero data retention to be enabled for your + * organization (contact support@context.dev), otherwise the request fails with + * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; +} + export interface WebWebScrapeHTMLParams { /** * Full URL to scrape (must include http:// or https:// protocol) @@ -4870,6 +5209,7 @@ export declare namespace Web { type WebScreenshotResponse as WebScreenshotResponse, type WebSearchResponse as WebSearchResponse, type WebWebCrawlMdResponse as WebWebCrawlMdResponse, + type WebWebScrapeBytesResponse as WebWebScrapeBytesResponse, type WebWebScrapeHTMLResponse as WebWebScrapeHTMLResponse, type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, type WebWebScrapeMdResponse as WebWebScrapeMdResponse, @@ -4882,6 +5222,7 @@ export declare namespace Web { type WebScreenshotParams as WebScreenshotParams, type WebSearchParams as WebSearchParams, type WebWebCrawlMdParams as WebWebCrawlMdParams, + type WebWebScrapeBytesParams as WebWebScrapeBytesParams, type WebWebScrapeHTMLParams as WebWebScrapeHTMLParams, type WebWebScrapeImagesParams as WebWebScrapeImagesParams, type WebWebScrapeMdParams as WebWebScrapeMdParams, diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 9f1ce931..39da3724 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -291,6 +291,30 @@ describe('resource web', () => { }); }); + // Mock server tests are disabled + test.skip('webScrapeBytes: only required params', async () => { + const responsePromise = client.web.webScrapeBytes({ url: 'https://example.com' }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('webScrapeBytes: required and optional params', async () => { + const response = await client.web.webScrapeBytes({ + url: 'https://example.com', + country: 'de', + headers: { foo: 'J!' }, + tags: ['production', 'team-alpha'], + timeoutMS: 1, + zdr: 'enabled', + }); + }); + // Mock server tests are disabled test.skip('webScrapeHTML: only required params', async () => { const responsePromise = client.web.webScrapeHTML({ url: 'https://example.com' }); From d1a5b059daea95fdef71e71f14d087e66de1e1ca Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 15 Sep 2026 07:52:50 +0000 Subject: [PATCH 037/232] seal --- .stats.yml | 2 +- api.md | 2 + src/client.ts | 4 + src/resources/index.ts | 2 + src/resources/web.ts | 341 ++++++++++++++++++++++++++++++++ tests/api-resources/web.test.ts | 24 +++ 6 files changed, 374 insertions(+), 1 deletion(-) diff --git a/.stats.yml b/.stats.yml index 58526a77..85f79b6a 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 48 +configured_endpoints: 49 diff --git a/api.md b/api.md index 2b893367..285cb482 100644 --- a/api.md +++ b/api.md @@ -20,6 +20,7 @@ Types: - WebScreenshotResponse - WebSearchResponse - WebWebCrawlMdResponse +- WebWebScrapeBytesResponse - WebWebScrapeHTMLResponse - WebWebScrapeImagesResponse - WebWebScrapeMdResponse @@ -35,6 +36,7 @@ Methods: - client.web.screenshot({ ...params }) -> WebScreenshotResponse - client.web.search({ ...params }) -> WebSearchResponse - client.web.webCrawlMd({ ...params }) -> WebWebCrawlMdResponse +- client.web.webScrapeBytes({ ...params }) -> WebWebScrapeBytesResponse - client.web.webScrapeHTML({ ...params }) -> WebWebScrapeHTMLResponse - client.web.webScrapeImages({ ...params }) -> WebWebScrapeImagesResponse - client.web.webScrapeMd({ ...params }) -> WebWebScrapeMdResponse diff --git a/src/client.ts b/src/client.ts index 37b908a3..35611ddf 100644 --- a/src/client.ts +++ b/src/client.ts @@ -104,6 +104,8 @@ import { WebSearchResponse, WebWebCrawlMdParams, WebWebCrawlMdResponse, + WebWebScrapeBytesParams, + WebWebScrapeBytesResponse, WebWebScrapeHTMLParams, WebWebScrapeHTMLResponse, WebWebScrapeImagesParams, @@ -889,6 +891,7 @@ export declare namespace ContextDev { type WebScreenshotResponse as WebScreenshotResponse, type WebSearchResponse as WebSearchResponse, type WebWebCrawlMdResponse as WebWebCrawlMdResponse, + type WebWebScrapeBytesResponse as WebWebScrapeBytesResponse, type WebWebScrapeHTMLResponse as WebWebScrapeHTMLResponse, type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, type WebWebScrapeMdResponse as WebWebScrapeMdResponse, @@ -901,6 +904,7 @@ export declare namespace ContextDev { type WebScreenshotParams as WebScreenshotParams, type WebSearchParams as WebSearchParams, type WebWebCrawlMdParams as WebWebCrawlMdParams, + type WebWebScrapeBytesParams as WebWebScrapeBytesParams, type WebWebScrapeHTMLParams as WebWebScrapeHTMLParams, type WebWebScrapeImagesParams as WebWebScrapeImagesParams, type WebWebScrapeMdParams as WebWebScrapeMdParams, diff --git a/src/resources/index.ts b/src/resources/index.ts index 55e34fce..47b621a2 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -79,6 +79,7 @@ export { type WebScreenshotResponse, type WebSearchResponse, type WebWebCrawlMdResponse, + type WebWebScrapeBytesResponse, type WebWebScrapeHTMLResponse, type WebWebScrapeImagesResponse, type WebWebScrapeMdResponse, @@ -91,6 +92,7 @@ export { type WebScreenshotParams, type WebSearchParams, type WebWebCrawlMdParams, + type WebWebScrapeBytesParams, type WebWebScrapeHTMLParams, type WebWebScrapeImagesParams, type WebWebScrapeMdParams, diff --git a/src/resources/web.ts b/src/resources/web.ts index 0208cb9e..dc3a2f94 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -140,6 +140,32 @@ export class Web extends APIResource { return this._client.post('/web/crawl', { body, ...options }); } + /** + * Downloads a resource and returns its bytes as base64. Supports images, PDFs, + * HTML pages, and any other content type without image conversion, text + * extraction, or character-encoding changes. HTTP compression is decoded before + * base64 encoding. HTML is the original HTTP response; JavaScript is not rendered. + * Follows public redirects and retries failed downloads through ISP and + * residential proxies, with a direct fallback. When country is specified, only a + * residential proxy in that country is used. Supply headers such as Referer for + * images that require a referring page. Downloads are not cached. Maximum decoded + * resource size: 20 MiB (20971520 bytes), before base64 encoding. Successful + * requests cost 1 credit; errors are not billed. + * + * @example + * ```ts + * const response = await client.web.webScrapeBytes({ + * url: 'https://example.com', + * }); + * ``` + */ + webScrapeBytes( + query: WebWebScrapeBytesParams, + options?: RequestOptions, + ): APIPromise { + return this._client.get('/web/scrape/bytes', { query, ...options }); + } + /** * Scrapes the given URL and returns the raw HTML content of the page. The base * request costs 1 credit; requests with browser actions cost 2 credits. @@ -1673,6 +1699,72 @@ export namespace WebWebCrawlMdResponse { } } +export interface WebWebScrapeBytesResponse { + /** + * Base64-encoded resource bytes, without a data URI prefix. Decode this field to + * recover the downloaded file. + */ + bytes: string; + + /** + * Number of decoded resource bytes, before base64 encoding. + */ + contentLength: number; + + /** + * The Content-Type returned by the origin, including any charset. Defaults to + * application/octet-stream when absent. + */ + contentType: string; + + encoding: 'base64'; + + /** + * The resource URL after redirects. + */ + finalUrl: string; + + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + + /** + * HTTP status returned by the origin. + */ + statusCode: number; + + success: true; + + /** + * The requested resource URL. + */ + url: string; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: WebWebScrapeBytesResponse.KeyMetadata; +} + +export namespace WebWebScrapeBytesResponse { + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + export interface WebWebScrapeHTMLResponse { /** * Cache outcome for this response. Composite responses are hits only when every @@ -3848,6 +3940,253 @@ export namespace WebWebCrawlMdParams { } } +export interface WebWebScrapeBytesParams { + /** + * Full HTTP(S) URL of the resource to download, such as an image, PDF, or page. + */ + url: string; + + /** + * Fetch the target page through a residential proxy in this country (ISO 3166-1 + * alpha-2). + */ + country?: + | 'ad' + | 'ae' + | 'af' + | 'ag' + | 'ai' + | 'al' + | 'am' + | 'ao' + | 'ar' + | 'at' + | 'au' + | 'aw' + | 'az' + | 'ba' + | 'bb' + | 'bd' + | 'be' + | 'bf' + | 'bg' + | 'bh' + | 'bi' + | 'bj' + | 'bm' + | 'bn' + | 'bo' + | 'bq' + | 'br' + | 'bs' + | 'bw' + | 'by' + | 'bz' + | 'ca' + | 'cd' + | 'cf' + | 'cg' + | 'ch' + | 'ci' + | 'cl' + | 'cm' + | 'cn' + | 'co' + | 'cr' + | 'cv' + | 'cw' + | 'cy' + | 'cz' + | 'de' + | 'dj' + | 'dk' + | 'dm' + | 'do' + | 'dz' + | 'ec' + | 'ee' + | 'eg' + | 'es' + | 'et' + | 'fi' + | 'fj' + | 'fr' + | 'ga' + | 'gb' + | 'gd' + | 'ge' + | 'gf' + | 'gg' + | 'gh' + | 'gm' + | 'gn' + | 'gp' + | 'gq' + | 'gr' + | 'gt' + | 'gu' + | 'gw' + | 'gy' + | 'hk' + | 'hn' + | 'hr' + | 'ht' + | 'hu' + | 'id' + | 'ie' + | 'il' + | 'im' + | 'in' + | 'iq' + | 'ir' + | 'is' + | 'it' + | 'je' + | 'jm' + | 'jo' + | 'jp' + | 'ke' + | 'kg' + | 'kh' + | 'kn' + | 'kr' + | 'kw' + | 'ky' + | 'kz' + | 'la' + | 'lb' + | 'lc' + | 'lk' + | 'lr' + | 'ls' + | 'lt' + | 'lu' + | 'lv' + | 'ly' + | 'ma' + | 'mc' + | 'md' + | 'me' + | 'mf' + | 'mg' + | 'mk' + | 'ml' + | 'mm' + | 'mn' + | 'mo' + | 'mq' + | 'mr' + | 'mt' + | 'mu' + | 'mv' + | 'mw' + | 'mx' + | 'my' + | 'mz' + | 'na' + | 'nc' + | 'ne' + | 'ng' + | 'ni' + | 'nl' + | 'no' + | 'np' + | 'nz' + | 'om' + | 'pa' + | 'pe' + | 'pf' + | 'pg' + | 'ph' + | 'pk' + | 'pl' + | 'pr' + | 'ps' + | 'pt' + | 'py' + | 'qa' + | 're' + | 'ro' + | 'rs' + | 'ru' + | 'rw' + | 'sa' + | 'sc' + | 'sd' + | 'se' + | 'sg' + | 'si' + | 'sk' + | 'sl' + | 'sm' + | 'sn' + | 'so' + | 'sr' + | 'ss' + | 'st' + | 'sv' + | 'sx' + | 'sy' + | 'sz' + | 'tc' + | 'td' + | 'tg' + | 'th' + | 'tj' + | 'tl' + | 'tm' + | 'tn' + | 'tr' + | 'tt' + | 'tw' + | 'tz' + | 'ua' + | 'ug' + | 'us' + | 'uy' + | 'uz' + | 'vc' + | 've' + | 'vg' + | 'vi' + | 'vn' + | 'ye' + | 'yt' + | 'za' + | 'zm' + | 'zw'; + + /** + * Optional outbound HTTP headers, such as Referer, Cookie, or Authorization. Send + * as a JSON object or deep-object query params such as + * headers[Referer]=https://example.com/. Host, Content-Length, and hop-by-hop + * transport headers are rejected. Authorization and cookies are removed when a + * redirect changes origin. + */ + headers?: { [key: string]: string }; + + /** + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. + */ + tags?: Array; + + /** + * Optional timeout in milliseconds for the request. If the request takes longer + * than this value, it will be aborted with a 408 status code. Maximum allowed + * value is 300000ms (5 minutes). + */ + timeoutMS?: number; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Requires zero data retention to be enabled for your + * organization (contact support@context.dev), otherwise the request fails with + * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; +} + export interface WebWebScrapeHTMLParams { /** * Full URL to scrape (must include http:// or https:// protocol) @@ -4870,6 +5209,7 @@ export declare namespace Web { type WebScreenshotResponse as WebScreenshotResponse, type WebSearchResponse as WebSearchResponse, type WebWebCrawlMdResponse as WebWebCrawlMdResponse, + type WebWebScrapeBytesResponse as WebWebScrapeBytesResponse, type WebWebScrapeHTMLResponse as WebWebScrapeHTMLResponse, type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, type WebWebScrapeMdResponse as WebWebScrapeMdResponse, @@ -4882,6 +5222,7 @@ export declare namespace Web { type WebScreenshotParams as WebScreenshotParams, type WebSearchParams as WebSearchParams, type WebWebCrawlMdParams as WebWebCrawlMdParams, + type WebWebScrapeBytesParams as WebWebScrapeBytesParams, type WebWebScrapeHTMLParams as WebWebScrapeHTMLParams, type WebWebScrapeImagesParams as WebWebScrapeImagesParams, type WebWebScrapeMdParams as WebWebScrapeMdParams, diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 9f1ce931..39da3724 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -291,6 +291,30 @@ describe('resource web', () => { }); }); + // Mock server tests are disabled + test.skip('webScrapeBytes: only required params', async () => { + const responsePromise = client.web.webScrapeBytes({ url: 'https://example.com' }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('webScrapeBytes: required and optional params', async () => { + const response = await client.web.webScrapeBytes({ + url: 'https://example.com', + country: 'de', + headers: { foo: 'J!' }, + tags: ['production', 'team-alpha'], + timeoutMS: 1, + zdr: 'enabled', + }); + }); + // Mock server tests are disabled test.skip('webScrapeHTML: only required params', async () => { const responsePromise = client.web.webScrapeHTML({ url: 'https://example.com' }); From b8e4d371a307f5f7effc7984cc3e6f458d9ab5fa Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 15 Sep 2026 09:05:09 +0000 Subject: [PATCH 038/232] feat(api): unify timeout configuration and return partial results (#1030) Stainless-Generated-From: 0e72299c6ae91939a3d989cea78127f4fec14709 --- src/resources/ai.ts | 103 ++++- src/resources/brand.ts | 222 +++++++++-- src/resources/industry.ts | 72 +++- src/resources/people.ts | 34 +- src/resources/utility.ts | 26 +- src/resources/web.ts | 548 +++++++++++++++++++++++---- tests/api-resources/ai.test.ts | 4 +- tests/api-resources/brand.test.ts | 4 +- tests/api-resources/industry.test.ts | 4 +- tests/api-resources/utility.test.ts | 2 +- tests/api-resources/web.test.ts | 28 +- 11 files changed, 902 insertions(+), 145 deletions(-) diff --git a/src/resources/ai.ts b/src/resources/ai.ts index a9b21b8e..14c0b1b5 100644 --- a/src/resources/ai.ts +++ b/src/resources/ai.ts @@ -67,6 +67,12 @@ export interface AIExtractProductResponse { */ key_metadata?: AIExtractProductResponse.KeyMetadata; + /** + * True when the timeout ended processing and this response contains only usable + * results completed so far. Unfinished results are omitted. + */ + partial?: boolean; + /** * The detected ecommerce platform, or null if not a product page */ @@ -230,6 +236,13 @@ export interface AIExtractProductsResponse { */ key_metadata?: AIExtractProductsResponse.KeyMetadata; + /** + * True when timeoutOpts.behavior=return-partial returned the usable results + * collected before the deadline. Partial collections are not cached as complete + * results. + */ + partial?: boolean; + /** * Array of products extracted from the website */ @@ -385,11 +398,33 @@ export interface AIExtractProductParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: AIExtractProductParams.TimeoutOpts; +} + +export namespace AIExtractProductParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export type AIExtractProductsParams = AIExtractProductsParams.ByDomain | AIExtractProductsParams.ByDirectURL; @@ -419,11 +454,33 @@ export declare namespace AIExtractProductsParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: ByDomain.TimeoutOpts; + } + + export namespace ByDomain { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface ByDirectURL { @@ -451,11 +508,33 @@ export declare namespace AIExtractProductsParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: ByDirectURL.TimeoutOpts; + } + + export namespace ByDirectURL { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } } diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 39b08183..9c544b40 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -85,6 +85,12 @@ export interface BrandRetrieveResponse { */ key_metadata?: BrandRetrieveResponse.KeyMetadata; + /** + * True when the timeout ended processing and this response contains the usable + * data completed so far. Unfinished fields are omitted. + */ + partial?: boolean; + /** * Status of the response, e.g., 'ok' */ @@ -929,6 +935,12 @@ export interface BrandRetrieveSimplifiedResponse { */ key_metadata?: BrandRetrieveSimplifiedResponse.KeyMetadata; + /** + * True when the timeout ended processing and only completed brand data is + * returned. + */ + partial?: boolean; + /** * Status of the response, e.g., 'ok' */ @@ -1353,11 +1365,33 @@ export declare namespace BrandRetrieveParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: BrandRetrieveByDomainRequest.TimeoutOpts; + } + + export namespace BrandRetrieveByDomainRequest { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface BrandRetrieveByNameRequest { @@ -1521,11 +1555,33 @@ export declare namespace BrandRetrieveParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: BrandRetrieveByNameRequest.TimeoutOpts; + } + + export namespace BrandRetrieveByNameRequest { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface BrandRetrieveByEmailRequest { @@ -1683,11 +1739,33 @@ export declare namespace BrandRetrieveParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: BrandRetrieveByEmailRequest.TimeoutOpts; + } + + export namespace BrandRetrieveByEmailRequest { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface BrandRetrieveByTickerRequest { @@ -1850,11 +1928,33 @@ export declare namespace BrandRetrieveParams { ticker_exchange?: string; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: BrandRetrieveByTickerRequest.TimeoutOpts; + } + + export namespace BrandRetrieveByTickerRequest { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface BrandRetrieveByDirectURLRequest { @@ -1876,11 +1976,33 @@ export declare namespace BrandRetrieveParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: BrandRetrieveByDirectURLRequest.TimeoutOpts; + } + + export namespace BrandRetrieveByDirectURLRequest { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface BrandRetrieveFromTransactionRequest { @@ -2058,11 +2180,33 @@ export declare namespace BrandRetrieveParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: BrandRetrieveFromTransactionRequest.TimeoutOpts; + } + + export namespace BrandRetrieveFromTransactionRequest { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } } @@ -2092,11 +2236,33 @@ export interface BrandRetrieveSimplifiedParams { theme?: 'light' | 'dark'; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: BrandRetrieveSimplifiedParams.TimeoutOpts; +} + +export namespace BrandRetrieveSimplifiedParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface BrandSearchParams { diff --git a/src/resources/industry.ts b/src/resources/industry.ts index 5e7b6175..606460d7 100644 --- a/src/resources/industry.ts +++ b/src/resources/industry.ts @@ -50,6 +50,12 @@ export interface IndustryRetrieveNaicsResponse { */ key_metadata?: IndustryRetrieveNaicsResponse.KeyMetadata; + /** + * True when the timeout ended processing and this response contains only usable + * results completed so far. Unfinished results are omitted. + */ + partial?: boolean; + /** * Status of the response, e.g., 'ok' */ @@ -124,6 +130,12 @@ export interface IndustryRetrieveSicResponse { */ key_metadata?: IndustryRetrieveSicResponse.KeyMetadata; + /** + * True when the timeout ended processing and this response contains only usable + * results completed so far. Unfinished results are omitted. + */ + partial?: boolean; + /** * Status of the response, e.g., 'ok' */ @@ -213,11 +225,33 @@ export interface IndustryRetrieveNaicsParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: IndustryRetrieveNaicsParams.TimeoutOpts; +} + +export namespace IndustryRetrieveNaicsParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface IndustryRetrieveSicParams { @@ -245,11 +279,11 @@ export interface IndustryRetrieveSicParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: IndustryRetrieveSicParams.TimeoutOpts; /** * Which SIC dataset to classify against. `original_sic` uses the 1987 Standard @@ -259,6 +293,28 @@ export interface IndustryRetrieveSicParams { type?: 'original_sic' | 'latest_sec'; } +export namespace IndustryRetrieveSicParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } +} + export declare namespace Industry { export { type IndustryRetrieveNaicsResponse as IndustryRetrieveNaicsResponse, diff --git a/src/resources/people.ts b/src/resources/people.ts index 9da7e1e5..3c8bec28 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -48,6 +48,12 @@ export interface PersonEnrichResponse { * Credit usage, included whenever a valid API key is provided. */ key_metadata?: PersonEnrichResponse.KeyMetadata; + + /** + * True when the timeout ended processing and this response contains the usable + * data completed so far. Unfinished fields are omitted. + */ + partial?: boolean; } export namespace PersonEnrichResponse { @@ -293,11 +299,11 @@ export interface PersonEnrichParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: PersonEnrichParams.TimeoutOpts; } export namespace PersonEnrichParams { @@ -338,6 +344,26 @@ export namespace PersonEnrichParams { last?: string; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export declare namespace People { diff --git a/src/resources/utility.ts b/src/resources/utility.ts index 289797da..683b587c 100644 --- a/src/resources/utility.ts +++ b/src/resources/utility.ts @@ -95,11 +95,11 @@ export interface UtilityPrefetchParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: UtilityPrefetchParams.TimeoutOpts; } export namespace UtilityPrefetchParams { @@ -124,6 +124,24 @@ export namespace UtilityPrefetchParams { */ email: string; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. This endpoint supports "fail": return 408 + * REQUEST_TIMEOUT without charging credits. + */ + behavior?: 'fail'; + } } export declare namespace Utility { diff --git a/src/resources/web.ts b/src/resources/web.ts index dc3a2f94..eaddc959 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -9,7 +9,8 @@ export class Web extends APIResource { * Researches the live web and returns a sourced answer in your requested JSON * shape. Select fast for a smaller research budget at 10 credits or ultra for * deeper reasoning at 100 credits. Defaults to ultra. Fast research is limited to - * 30 seconds and ultra to 50 seconds; timeoutMS can shorten either deadline. + * 30 seconds and ultra to 50 seconds; timeoutOpts.milliseconds can shorten either + * deadline. * * @example * ```ts @@ -168,7 +169,11 @@ export class Web extends APIResource { /** * Scrapes the given URL and returns the raw HTML content of the page. The base - * request costs 1 credit; requests with browser actions cost 2 credits. + * request costs 1 credit; requests with browser actions cost 2 credits. A request + * that hits its timeoutOpts.milliseconds deadline fails with 408 and is not + * billed, unless timeoutOpts.behavior=return-partial is set — then the page as + * rendered so far is returned with `finalDOMState: "still-loading"` and billed at + * the base cost of 1 credit. * * @example * ```ts @@ -226,11 +231,11 @@ export class Web extends APIResource { * * | HTTP status | Billed? | Meaning | * | ----------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - * | 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing | + * | 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing. A partial result (`finalDOMState: "still-loading"`, only with timeoutOpts.behavior=return-partial) is billed at the base 1 credit with no OCR or actions surcharge | * | 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds | * | 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code | * | 404 | No | Target page returned or fingerprinted as not found | - * | 408 | No | Request timed out | + * | 408 | No | Request timed out. With timeoutOpts.behavior=return-partial this only happens when nothing usable had rendered by the deadline | * | 413 | No | Target content exceeds the maximum supported size (20 MB) | * | 415 | No | Unsupported content type | * | 429 | No | Per-minute rate limit exceeded; honor Retry-After | @@ -286,6 +291,12 @@ export interface WebAnswersResponse { * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebAnswersResponse.KeyMetadata; + + /** + * True when the request deadline ended research and the answer uses the evidence + * collected so far. + */ + partial?: boolean; } export namespace WebAnswersResponse { @@ -345,6 +356,12 @@ export interface WebExtractResponse { * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebExtractResponse.KeyMetadata; + + /** + * True when the timeout ended processing and this response contains only usable + * results completed so far. Unfinished results are omitted. + */ + partial?: boolean; } export namespace WebExtractResponse { @@ -461,6 +478,12 @@ export interface WebExtractCompetitorsResponse { * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebExtractCompetitorsResponse.KeyMetadata; + + /** + * True when the timeout ended processing and this response contains only usable + * results completed so far. Unfinished results are omitted. + */ + partial?: boolean; } export namespace WebExtractCompetitorsResponse { @@ -571,6 +594,15 @@ export interface WebExtractFontsResponse { */ status: string; + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState?: 'loaded' | 'still-loading'; + /** * Font assets keyed by family name as it appears in the fonts array (non-generic * names only). Clients match entries in fonts to pick a file URL from files. @@ -703,6 +735,15 @@ export interface WebExtractStyleguideResponse { */ domain?: string; + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState?: 'loaded' | 'still-loading'; + /** * Credit usage, included whenever a valid API key is provided. */ @@ -1267,6 +1308,15 @@ export interface WebScreenshotResponse { */ domain?: string; + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState?: 'loaded' | 'still-loading'; + /** * Height in pixels of the returned screenshot image */ @@ -1359,6 +1409,13 @@ export interface WebSearchResponse { * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebSearchResponse.KeyMetadata; + + /** + * True when timeoutOpts.behavior=return-partial returned the usable results + * collected before the deadline. Partial collections are not cached as complete + * results. + */ + partial?: boolean; } export namespace WebSearchResponse { @@ -1422,6 +1479,15 @@ export namespace WebSearchResponse { * scraping succeeded. */ markdown: string | null; + + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState?: 'loaded' | 'still-loading'; } } @@ -1463,6 +1529,13 @@ export interface WebWebCrawlMdResponse { * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebCrawlMdResponse.KeyMetadata; + + /** + * True when timeoutOpts.behavior=return-partial returned the usable results + * collected before the deadline. Partial collections are not cached as complete + * results. + */ + partial?: boolean; } export namespace WebWebCrawlMdResponse { @@ -1773,6 +1846,15 @@ export interface WebWebScrapeHTMLResponse { */ cache_metadata: WebWebScrapeHTMLResponse.CacheMetadata; + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState: 'loaded' | 'still-loading'; + /** * The scraped content of the page. For normal pages this is the raw HTML. When the * page is a sitemap or feed served behind an XSL stylesheet (which browsers render @@ -2075,10 +2157,26 @@ export interface WebWebScrapeImagesResponse { */ actionsApplied?: Array; + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState?: 'loaded' | 'still-loading'; + /** * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebScrapeImagesResponse.KeyMetadata; + + /** + * True when the deadline interrupted rendering or image enrichment. Partial + * results are billed at the base request cost, without enrichment or actions + * surcharges. + */ + partial?: boolean; } export namespace WebWebScrapeImagesResponse { @@ -2213,6 +2311,15 @@ export interface WebWebScrapeMdResponse { */ contentLength: number; + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState: 'loaded' | 'still-loading'; + /** * Page content converted to GitHub Flavored Markdown */ @@ -2496,6 +2603,13 @@ export interface WebWebScrapeSitemapResponse { * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebScrapeSitemapResponse.KeyMetadata; + + /** + * True when timeoutOpts.behavior=return-partial returned the usable results + * collected before the deadline. Partial collections are not cached as complete + * results. + */ + partial?: boolean; } export namespace WebWebScrapeSitemapResponse { @@ -2569,11 +2683,33 @@ export interface WebAnswersParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: WebAnswersParams.TimeoutOpts; +} + +export namespace WebAnswersParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebExtractParams { @@ -2669,11 +2805,11 @@ export interface WebExtractParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebExtractParams.TimeoutOpts; /** * Optional browser wait time in milliseconds after initial page load for each @@ -2748,6 +2884,26 @@ export namespace WebExtractParams { */ start?: number; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebExtractCompetitorsParams { @@ -2769,11 +2925,33 @@ export interface WebExtractCompetitorsParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebExtractCompetitorsParams.TimeoutOpts; +} + +export namespace WebExtractCompetitorsParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebExtractFontsParams { @@ -2806,11 +2984,34 @@ export interface WebExtractFontsParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebExtractFontsParams.TimeoutOpts; +} + +export namespace WebExtractFontsParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 15000. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebExtractStyleguideParams { @@ -2850,11 +3051,34 @@ export interface WebExtractStyleguideParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebExtractStyleguideParams.TimeoutOpts; +} + +export namespace WebExtractStyleguideParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 15000. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebScreenshotParams { @@ -3144,11 +3368,11 @@ export interface WebScreenshotParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebScreenshotParams.TimeoutOpts; /** * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. @@ -3158,8 +3382,9 @@ export interface WebScreenshotParams { /** * Optional browser wait time in milliseconds after initial page load before taking * the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when - * omitted. When combined with timeoutMS, timeoutMS must be at least waitForMs + - * 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. + * omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at + * least waitForMs + 10000 ms; a shorter deadline is rejected with 400 + * TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; @@ -3173,6 +3398,27 @@ export interface WebScreenshotParams { } export namespace WebScreenshotParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 15000. + */ + behavior?: 'fail' | 'return-partial'; + } + /** * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. */ @@ -3479,11 +3725,11 @@ export interface WebSearchParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebSearchParams.TimeoutOpts; } export namespace WebSearchParams { @@ -3528,11 +3774,11 @@ export namespace WebSearchParams { shortenBase64Images?: boolean; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: MarkdownOptions.TimeoutOpts; /** * Strip nav, header, footer, and sidebar — keep only the primary article content. @@ -3567,6 +3813,47 @@ export namespace WebSearchParams { */ start?: number; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 15000. + */ + behavior?: 'fail' | 'return-partial'; + } + } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; } } @@ -3873,11 +4160,11 @@ export interface WebWebCrawlMdParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebWebCrawlMdParams.TimeoutOpts; /** * Regex pattern. Only URLs matching this pattern will be followed and scraped. An @@ -3938,6 +4225,26 @@ export namespace WebWebCrawlMdParams { */ start?: number; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebWebScrapeBytesParams { @@ -4172,11 +4479,11 @@ export interface WebWebScrapeBytesParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebWebScrapeBytesParams.TimeoutOpts; /** * Set to enabled to bypass shared caches and omit request and response content @@ -4187,6 +4494,26 @@ export interface WebWebScrapeBytesParams { zdr?: 'enabled' | 'disabled'; } +export namespace WebWebScrapeBytesParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. This endpoint supports "fail": return 408 + * REQUEST_TIMEOUT without charging credits. + */ + behavior?: 'fail'; + } +} + export interface WebWebScrapeHTMLParams { /** * Full URL to scrape (must include http:// or https:// protocol) @@ -4467,11 +4794,11 @@ export interface WebWebScrapeHTMLParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebWebScrapeHTMLParams.TimeoutOpts; /** * When true, return only the page's main content in the HTML response, excluding @@ -4481,8 +4808,8 @@ export interface WebWebScrapeHTMLParams { /** * Optional browser wait time in milliseconds after initial page load. Min: 0. Max: - * 30000 (30 seconds). When combined with timeoutMS, timeoutMS must be at least - * waitForMs + 10000 ms; a shorter deadline is rejected with 400 + * 30000 (30 seconds). When combined with timeoutOpts, timeoutOpts.milliseconds + * must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 * TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; @@ -4575,6 +4902,27 @@ export namespace WebWebScrapeHTMLParams { */ start?: number; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 15000. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebWebScrapeImagesParams { @@ -4628,17 +4976,17 @@ export interface WebWebScrapeImagesParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebWebScrapeImagesParams.TimeoutOpts; /** * Optional browser wait time in milliseconds after initial page load before * collecting images. Min: 0. Max: 30000 (30 seconds). When combined with - * timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter deadline - * is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. + * timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a + * shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; } @@ -4718,6 +5066,27 @@ export namespace WebWebScrapeImagesParams { */ resolution?: boolean; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 15000. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebWebScrapeMdParams { @@ -5023,11 +5392,11 @@ export interface WebWebScrapeMdParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebWebScrapeMdParams.TimeoutOpts; /** * Extract only the main content of the page, excluding headers, footers, sidebars, @@ -5038,8 +5407,8 @@ export interface WebWebScrapeMdParams { /** * Optional browser wait time in milliseconds after initial page load before * converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). When combined - * with timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter - * deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. + * with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 + * ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; @@ -5131,6 +5500,27 @@ export namespace WebWebScrapeMdParams { */ start?: number; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 15000. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebWebScrapeSitemapParams { @@ -5178,11 +5568,11 @@ export interface WebWebScrapeSitemapParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebWebScrapeSitemapParams.TimeoutOpts; /** * Optional RE2-compatible regex pattern. Only URLs matching this pattern are @@ -5199,6 +5589,28 @@ export interface WebWebScrapeSitemapParams { zdr?: 'enabled' | 'disabled'; } +export namespace WebWebScrapeSitemapParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } +} + export declare namespace Web { export { type WebAnswersResponse as WebAnswersResponse, diff --git a/tests/api-resources/ai.test.ts b/tests/api-resources/ai.test.ts index 72464aad..e87f6f3d 100644 --- a/tests/api-resources/ai.test.ts +++ b/tests/api-resources/ai.test.ts @@ -26,7 +26,7 @@ describe('resource ai', () => { url: 'https://example.com', maxAgeMs: 0, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); @@ -49,7 +49,7 @@ describe('resource ai', () => { maxAgeMs: 0, maxProducts: 1, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); }); diff --git a/tests/api-resources/brand.test.ts b/tests/api-resources/brand.test.ts index 5722af22..b92d3c70 100644 --- a/tests/api-resources/brand.test.ts +++ b/tests/api-resources/brand.test.ts @@ -29,7 +29,7 @@ describe('resource brand', () => { maxAgeMs: 0, maxSpeed: true, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); @@ -52,7 +52,7 @@ describe('resource brand', () => { maxAgeMs: 0, tags: ['production', 'team-alpha'], theme: 'light', - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); diff --git a/tests/api-resources/industry.test.ts b/tests/api-resources/industry.test.ts index 6d0a4a3e..e9907673 100644 --- a/tests/api-resources/industry.test.ts +++ b/tests/api-resources/industry.test.ts @@ -27,7 +27,7 @@ describe('resource industry', () => { maxResults: 1, minResults: 1, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); @@ -50,7 +50,7 @@ describe('resource industry', () => { maxResults: 1, minResults: 1, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, type: 'original_sic', }); }); diff --git a/tests/api-resources/utility.test.ts b/tests/api-resources/utility.test.ts index 63476b03..120bfd69 100644 --- a/tests/api-resources/utility.test.ts +++ b/tests/api-resources/utility.test.ts @@ -29,7 +29,7 @@ describe('resource utility', () => { identifier: { domain: 'xxx' }, type: 'brand', tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); }); diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 39da3724..9823adb7 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -29,7 +29,7 @@ describe('resource web', () => { json_format: { pricing_page_url: 'bar', plans: 'bar' }, mode: 'fast', tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); @@ -79,7 +79,7 @@ describe('resource web', () => { settleAnimations: true, stopAfterMs: 10000, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, waitForMs: 0, }); }); @@ -102,7 +102,7 @@ describe('resource web', () => { domain: 'xxx', numCompetitors: 1, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); @@ -128,7 +128,7 @@ describe('resource web', () => { domain: 'xxx', maxAgeMs: 0, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, }, { path: '/_stainless_unknown_path' }, ), @@ -158,7 +158,7 @@ describe('resource web', () => { domain: 'xxx', maxAgeMs: 0, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, }, { path: '/_stainless_unknown_path' }, ), @@ -194,7 +194,7 @@ describe('resource web', () => { page: 'login', scrollOffset: 0, tags: ['production', 'team-alpha'], - timeoutMS: 1, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, viewport: { height: 240, width: 240 }, waitForMs: 0, zdr: 'enabled', @@ -236,14 +236,14 @@ describe('resource web', () => { start: 1, }, shortenBase64Images: true, - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, useMainContentOnly: true, waitForMs: 0, }, numResults: 10, queryFanout: true, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); @@ -283,7 +283,7 @@ describe('resource web', () => { shortenBase64Images: true, stopAfterMs: 10000, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, urlRegex: '^https?://[^/]+/blog/', useMainContentOnly: true, waitForMs: 0, @@ -310,7 +310,7 @@ describe('resource web', () => { country: 'de', headers: { foo: 'J!' }, tags: ['production', 'team-alpha'], - timeoutMS: 1, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, zdr: 'enabled', }); }); @@ -346,7 +346,7 @@ describe('resource web', () => { }, settleAnimations: true, tags: ['production', 'team-alpha'], - timeoutMS: 1, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, useMainContentOnly: true, waitForMs: 0, zdr: 'enabled', @@ -380,7 +380,7 @@ describe('resource web', () => { headers: { foo: 'J!' }, maxAgeMs: 0, tags: ['production', 'team-alpha'], - timeoutMS: 1, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, waitForMs: 0, }); }); @@ -420,7 +420,7 @@ describe('resource web', () => { settleAnimations: true, shortenBase64Images: true, tags: ['production', 'team-alpha'], - timeoutMS: 1, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, useMainContentOnly: true, waitForMs: 0, zdr: 'enabled', @@ -449,7 +449,7 @@ describe('resource web', () => { search: 'help center and troubleshooting articles', sitemapUrl: 'https://example.com', tags: ['production', 'team-alpha'], - timeoutMS: 1, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, urlRegex: '^https?://[^/]+/blog/', zdr: 'enabled', }); From 0e72299c6ae91939a3d989cea78127f4fec14709 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 15 Sep 2026 09:05:09 +0000 Subject: [PATCH 039/232] seal --- src/resources/ai.ts | 103 ++++- src/resources/brand.ts | 222 +++++++++-- src/resources/industry.ts | 72 +++- src/resources/people.ts | 34 +- src/resources/utility.ts | 26 +- src/resources/web.ts | 548 +++++++++++++++++++++++---- tests/api-resources/ai.test.ts | 4 +- tests/api-resources/brand.test.ts | 4 +- tests/api-resources/industry.test.ts | 4 +- tests/api-resources/utility.test.ts | 2 +- tests/api-resources/web.test.ts | 28 +- 11 files changed, 902 insertions(+), 145 deletions(-) diff --git a/src/resources/ai.ts b/src/resources/ai.ts index a9b21b8e..14c0b1b5 100644 --- a/src/resources/ai.ts +++ b/src/resources/ai.ts @@ -67,6 +67,12 @@ export interface AIExtractProductResponse { */ key_metadata?: AIExtractProductResponse.KeyMetadata; + /** + * True when the timeout ended processing and this response contains only usable + * results completed so far. Unfinished results are omitted. + */ + partial?: boolean; + /** * The detected ecommerce platform, or null if not a product page */ @@ -230,6 +236,13 @@ export interface AIExtractProductsResponse { */ key_metadata?: AIExtractProductsResponse.KeyMetadata; + /** + * True when timeoutOpts.behavior=return-partial returned the usable results + * collected before the deadline. Partial collections are not cached as complete + * results. + */ + partial?: boolean; + /** * Array of products extracted from the website */ @@ -385,11 +398,33 @@ export interface AIExtractProductParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: AIExtractProductParams.TimeoutOpts; +} + +export namespace AIExtractProductParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export type AIExtractProductsParams = AIExtractProductsParams.ByDomain | AIExtractProductsParams.ByDirectURL; @@ -419,11 +454,33 @@ export declare namespace AIExtractProductsParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: ByDomain.TimeoutOpts; + } + + export namespace ByDomain { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface ByDirectURL { @@ -451,11 +508,33 @@ export declare namespace AIExtractProductsParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: ByDirectURL.TimeoutOpts; + } + + export namespace ByDirectURL { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } } diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 39b08183..9c544b40 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -85,6 +85,12 @@ export interface BrandRetrieveResponse { */ key_metadata?: BrandRetrieveResponse.KeyMetadata; + /** + * True when the timeout ended processing and this response contains the usable + * data completed so far. Unfinished fields are omitted. + */ + partial?: boolean; + /** * Status of the response, e.g., 'ok' */ @@ -929,6 +935,12 @@ export interface BrandRetrieveSimplifiedResponse { */ key_metadata?: BrandRetrieveSimplifiedResponse.KeyMetadata; + /** + * True when the timeout ended processing and only completed brand data is + * returned. + */ + partial?: boolean; + /** * Status of the response, e.g., 'ok' */ @@ -1353,11 +1365,33 @@ export declare namespace BrandRetrieveParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: BrandRetrieveByDomainRequest.TimeoutOpts; + } + + export namespace BrandRetrieveByDomainRequest { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface BrandRetrieveByNameRequest { @@ -1521,11 +1555,33 @@ export declare namespace BrandRetrieveParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: BrandRetrieveByNameRequest.TimeoutOpts; + } + + export namespace BrandRetrieveByNameRequest { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface BrandRetrieveByEmailRequest { @@ -1683,11 +1739,33 @@ export declare namespace BrandRetrieveParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: BrandRetrieveByEmailRequest.TimeoutOpts; + } + + export namespace BrandRetrieveByEmailRequest { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface BrandRetrieveByTickerRequest { @@ -1850,11 +1928,33 @@ export declare namespace BrandRetrieveParams { ticker_exchange?: string; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: BrandRetrieveByTickerRequest.TimeoutOpts; + } + + export namespace BrandRetrieveByTickerRequest { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface BrandRetrieveByDirectURLRequest { @@ -1876,11 +1976,33 @@ export declare namespace BrandRetrieveParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: BrandRetrieveByDirectURLRequest.TimeoutOpts; + } + + export namespace BrandRetrieveByDirectURLRequest { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface BrandRetrieveFromTransactionRequest { @@ -2058,11 +2180,33 @@ export declare namespace BrandRetrieveParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: BrandRetrieveFromTransactionRequest.TimeoutOpts; + } + + export namespace BrandRetrieveFromTransactionRequest { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } } @@ -2092,11 +2236,33 @@ export interface BrandRetrieveSimplifiedParams { theme?: 'light' | 'dark'; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: BrandRetrieveSimplifiedParams.TimeoutOpts; +} + +export namespace BrandRetrieveSimplifiedParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface BrandSearchParams { diff --git a/src/resources/industry.ts b/src/resources/industry.ts index 5e7b6175..606460d7 100644 --- a/src/resources/industry.ts +++ b/src/resources/industry.ts @@ -50,6 +50,12 @@ export interface IndustryRetrieveNaicsResponse { */ key_metadata?: IndustryRetrieveNaicsResponse.KeyMetadata; + /** + * True when the timeout ended processing and this response contains only usable + * results completed so far. Unfinished results are omitted. + */ + partial?: boolean; + /** * Status of the response, e.g., 'ok' */ @@ -124,6 +130,12 @@ export interface IndustryRetrieveSicResponse { */ key_metadata?: IndustryRetrieveSicResponse.KeyMetadata; + /** + * True when the timeout ended processing and this response contains only usable + * results completed so far. Unfinished results are omitted. + */ + partial?: boolean; + /** * Status of the response, e.g., 'ok' */ @@ -213,11 +225,33 @@ export interface IndustryRetrieveNaicsParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: IndustryRetrieveNaicsParams.TimeoutOpts; +} + +export namespace IndustryRetrieveNaicsParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface IndustryRetrieveSicParams { @@ -245,11 +279,11 @@ export interface IndustryRetrieveSicParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: IndustryRetrieveSicParams.TimeoutOpts; /** * Which SIC dataset to classify against. `original_sic` uses the 1987 Standard @@ -259,6 +293,28 @@ export interface IndustryRetrieveSicParams { type?: 'original_sic' | 'latest_sec'; } +export namespace IndustryRetrieveSicParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } +} + export declare namespace Industry { export { type IndustryRetrieveNaicsResponse as IndustryRetrieveNaicsResponse, diff --git a/src/resources/people.ts b/src/resources/people.ts index 9da7e1e5..3c8bec28 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -48,6 +48,12 @@ export interface PersonEnrichResponse { * Credit usage, included whenever a valid API key is provided. */ key_metadata?: PersonEnrichResponse.KeyMetadata; + + /** + * True when the timeout ended processing and this response contains the usable + * data completed so far. Unfinished fields are omitted. + */ + partial?: boolean; } export namespace PersonEnrichResponse { @@ -293,11 +299,11 @@ export interface PersonEnrichParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: PersonEnrichParams.TimeoutOpts; } export namespace PersonEnrichParams { @@ -338,6 +344,26 @@ export namespace PersonEnrichParams { last?: string; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export declare namespace People { diff --git a/src/resources/utility.ts b/src/resources/utility.ts index 289797da..683b587c 100644 --- a/src/resources/utility.ts +++ b/src/resources/utility.ts @@ -95,11 +95,11 @@ export interface UtilityPrefetchParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: UtilityPrefetchParams.TimeoutOpts; } export namespace UtilityPrefetchParams { @@ -124,6 +124,24 @@ export namespace UtilityPrefetchParams { */ email: string; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. This endpoint supports "fail": return 408 + * REQUEST_TIMEOUT without charging credits. + */ + behavior?: 'fail'; + } } export declare namespace Utility { diff --git a/src/resources/web.ts b/src/resources/web.ts index dc3a2f94..eaddc959 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -9,7 +9,8 @@ export class Web extends APIResource { * Researches the live web and returns a sourced answer in your requested JSON * shape. Select fast for a smaller research budget at 10 credits or ultra for * deeper reasoning at 100 credits. Defaults to ultra. Fast research is limited to - * 30 seconds and ultra to 50 seconds; timeoutMS can shorten either deadline. + * 30 seconds and ultra to 50 seconds; timeoutOpts.milliseconds can shorten either + * deadline. * * @example * ```ts @@ -168,7 +169,11 @@ export class Web extends APIResource { /** * Scrapes the given URL and returns the raw HTML content of the page. The base - * request costs 1 credit; requests with browser actions cost 2 credits. + * request costs 1 credit; requests with browser actions cost 2 credits. A request + * that hits its timeoutOpts.milliseconds deadline fails with 408 and is not + * billed, unless timeoutOpts.behavior=return-partial is set — then the page as + * rendered so far is returned with `finalDOMState: "still-loading"` and billed at + * the base cost of 1 credit. * * @example * ```ts @@ -226,11 +231,11 @@ export class Web extends APIResource { * * | HTTP status | Billed? | Meaning | * | ----------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - * | 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing | + * | 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing. A partial result (`finalDOMState: "still-loading"`, only with timeoutOpts.behavior=return-partial) is billed at the base 1 credit with no OCR or actions surcharge | * | 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds | * | 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code | * | 404 | No | Target page returned or fingerprinted as not found | - * | 408 | No | Request timed out | + * | 408 | No | Request timed out. With timeoutOpts.behavior=return-partial this only happens when nothing usable had rendered by the deadline | * | 413 | No | Target content exceeds the maximum supported size (20 MB) | * | 415 | No | Unsupported content type | * | 429 | No | Per-minute rate limit exceeded; honor Retry-After | @@ -286,6 +291,12 @@ export interface WebAnswersResponse { * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebAnswersResponse.KeyMetadata; + + /** + * True when the request deadline ended research and the answer uses the evidence + * collected so far. + */ + partial?: boolean; } export namespace WebAnswersResponse { @@ -345,6 +356,12 @@ export interface WebExtractResponse { * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebExtractResponse.KeyMetadata; + + /** + * True when the timeout ended processing and this response contains only usable + * results completed so far. Unfinished results are omitted. + */ + partial?: boolean; } export namespace WebExtractResponse { @@ -461,6 +478,12 @@ export interface WebExtractCompetitorsResponse { * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebExtractCompetitorsResponse.KeyMetadata; + + /** + * True when the timeout ended processing and this response contains only usable + * results completed so far. Unfinished results are omitted. + */ + partial?: boolean; } export namespace WebExtractCompetitorsResponse { @@ -571,6 +594,15 @@ export interface WebExtractFontsResponse { */ status: string; + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState?: 'loaded' | 'still-loading'; + /** * Font assets keyed by family name as it appears in the fonts array (non-generic * names only). Clients match entries in fonts to pick a file URL from files. @@ -703,6 +735,15 @@ export interface WebExtractStyleguideResponse { */ domain?: string; + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState?: 'loaded' | 'still-loading'; + /** * Credit usage, included whenever a valid API key is provided. */ @@ -1267,6 +1308,15 @@ export interface WebScreenshotResponse { */ domain?: string; + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState?: 'loaded' | 'still-loading'; + /** * Height in pixels of the returned screenshot image */ @@ -1359,6 +1409,13 @@ export interface WebSearchResponse { * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebSearchResponse.KeyMetadata; + + /** + * True when timeoutOpts.behavior=return-partial returned the usable results + * collected before the deadline. Partial collections are not cached as complete + * results. + */ + partial?: boolean; } export namespace WebSearchResponse { @@ -1422,6 +1479,15 @@ export namespace WebSearchResponse { * scraping succeeded. */ markdown: string | null; + + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState?: 'loaded' | 'still-loading'; } } @@ -1463,6 +1529,13 @@ export interface WebWebCrawlMdResponse { * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebCrawlMdResponse.KeyMetadata; + + /** + * True when timeoutOpts.behavior=return-partial returned the usable results + * collected before the deadline. Partial collections are not cached as complete + * results. + */ + partial?: boolean; } export namespace WebWebCrawlMdResponse { @@ -1773,6 +1846,15 @@ export interface WebWebScrapeHTMLResponse { */ cache_metadata: WebWebScrapeHTMLResponse.CacheMetadata; + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState: 'loaded' | 'still-loading'; + /** * The scraped content of the page. For normal pages this is the raw HTML. When the * page is a sitemap or feed served behind an XSL stylesheet (which browsers render @@ -2075,10 +2157,26 @@ export interface WebWebScrapeImagesResponse { */ actionsApplied?: Array; + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState?: 'loaded' | 'still-loading'; + /** * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebScrapeImagesResponse.KeyMetadata; + + /** + * True when the deadline interrupted rendering or image enrichment. Partial + * results are billed at the base request cost, without enrichment or actions + * surcharges. + */ + partial?: boolean; } export namespace WebWebScrapeImagesResponse { @@ -2213,6 +2311,15 @@ export interface WebWebScrapeMdResponse { */ contentLength: number; + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState: 'loaded' | 'still-loading'; + /** * Page content converted to GitHub Flavored Markdown */ @@ -2496,6 +2603,13 @@ export interface WebWebScrapeSitemapResponse { * Credit usage, included whenever a valid API key is provided. */ key_metadata?: WebWebScrapeSitemapResponse.KeyMetadata; + + /** + * True when timeoutOpts.behavior=return-partial returned the usable results + * collected before the deadline. Partial collections are not cached as complete + * results. + */ + partial?: boolean; } export namespace WebWebScrapeSitemapResponse { @@ -2569,11 +2683,33 @@ export interface WebAnswersParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: WebAnswersParams.TimeoutOpts; +} + +export namespace WebAnswersParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebExtractParams { @@ -2669,11 +2805,11 @@ export interface WebExtractParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebExtractParams.TimeoutOpts; /** * Optional browser wait time in milliseconds after initial page load for each @@ -2748,6 +2884,26 @@ export namespace WebExtractParams { */ start?: number; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebExtractCompetitorsParams { @@ -2769,11 +2925,33 @@ export interface WebExtractCompetitorsParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebExtractCompetitorsParams.TimeoutOpts; +} + +export namespace WebExtractCompetitorsParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebExtractFontsParams { @@ -2806,11 +2984,34 @@ export interface WebExtractFontsParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebExtractFontsParams.TimeoutOpts; +} + +export namespace WebExtractFontsParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 15000. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebExtractStyleguideParams { @@ -2850,11 +3051,34 @@ export interface WebExtractStyleguideParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebExtractStyleguideParams.TimeoutOpts; +} + +export namespace WebExtractStyleguideParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 15000. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebScreenshotParams { @@ -3144,11 +3368,11 @@ export interface WebScreenshotParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebScreenshotParams.TimeoutOpts; /** * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. @@ -3158,8 +3382,9 @@ export interface WebScreenshotParams { /** * Optional browser wait time in milliseconds after initial page load before taking * the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when - * omitted. When combined with timeoutMS, timeoutMS must be at least waitForMs + - * 10000 ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. + * omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at + * least waitForMs + 10000 ms; a shorter deadline is rejected with 400 + * TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; @@ -3173,6 +3398,27 @@ export interface WebScreenshotParams { } export namespace WebScreenshotParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 15000. + */ + behavior?: 'fail' | 'return-partial'; + } + /** * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. */ @@ -3479,11 +3725,11 @@ export interface WebSearchParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebSearchParams.TimeoutOpts; } export namespace WebSearchParams { @@ -3528,11 +3774,11 @@ export namespace WebSearchParams { shortenBase64Images?: boolean; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: MarkdownOptions.TimeoutOpts; /** * Strip nav, header, footer, and sidebar — keep only the primary article content. @@ -3567,6 +3813,47 @@ export namespace WebSearchParams { */ start?: number; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 15000. + */ + behavior?: 'fail' | 'return-partial'; + } + } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; } } @@ -3873,11 +4160,11 @@ export interface WebWebCrawlMdParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebWebCrawlMdParams.TimeoutOpts; /** * Regex pattern. Only URLs matching this pattern will be followed and scraped. An @@ -3938,6 +4225,26 @@ export namespace WebWebCrawlMdParams { */ start?: number; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebWebScrapeBytesParams { @@ -4172,11 +4479,11 @@ export interface WebWebScrapeBytesParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebWebScrapeBytesParams.TimeoutOpts; /** * Set to enabled to bypass shared caches and omit request and response content @@ -4187,6 +4494,26 @@ export interface WebWebScrapeBytesParams { zdr?: 'enabled' | 'disabled'; } +export namespace WebWebScrapeBytesParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. This endpoint supports "fail": return 408 + * REQUEST_TIMEOUT without charging credits. + */ + behavior?: 'fail'; + } +} + export interface WebWebScrapeHTMLParams { /** * Full URL to scrape (must include http:// or https:// protocol) @@ -4467,11 +4794,11 @@ export interface WebWebScrapeHTMLParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebWebScrapeHTMLParams.TimeoutOpts; /** * When true, return only the page's main content in the HTML response, excluding @@ -4481,8 +4808,8 @@ export interface WebWebScrapeHTMLParams { /** * Optional browser wait time in milliseconds after initial page load. Min: 0. Max: - * 30000 (30 seconds). When combined with timeoutMS, timeoutMS must be at least - * waitForMs + 10000 ms; a shorter deadline is rejected with 400 + * 30000 (30 seconds). When combined with timeoutOpts, timeoutOpts.milliseconds + * must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 * TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; @@ -4575,6 +4902,27 @@ export namespace WebWebScrapeHTMLParams { */ start?: number; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 15000. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebWebScrapeImagesParams { @@ -4628,17 +4976,17 @@ export interface WebWebScrapeImagesParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebWebScrapeImagesParams.TimeoutOpts; /** * Optional browser wait time in milliseconds after initial page load before * collecting images. Min: 0. Max: 30000 (30 seconds). When combined with - * timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter deadline - * is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. + * timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a + * shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; } @@ -4718,6 +5066,27 @@ export namespace WebWebScrapeImagesParams { */ resolution?: boolean; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 15000. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebWebScrapeMdParams { @@ -5023,11 +5392,11 @@ export interface WebWebScrapeMdParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebWebScrapeMdParams.TimeoutOpts; /** * Extract only the main content of the page, excluding headers, footers, sidebars, @@ -5038,8 +5407,8 @@ export interface WebWebScrapeMdParams { /** * Optional browser wait time in milliseconds after initial page load before * converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). When combined - * with timeoutMS, timeoutMS must be at least waitForMs + 10000 ms; a shorter - * deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. + * with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 + * ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; @@ -5131,6 +5500,27 @@ export namespace WebWebScrapeMdParams { */ start?: number; } + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 15000. + */ + behavior?: 'fail' | 'return-partial'; + } } export interface WebWebScrapeSitemapParams { @@ -5178,11 +5568,11 @@ export interface WebWebScrapeSitemapParams { tags?: Array; /** - * Optional timeout in milliseconds for the request. If the request takes longer - * than this value, it will be aborted with a 408 status code. Maximum allowed - * value is 300000ms (5 minutes). + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - timeoutMS?: number; + timeoutOpts?: WebWebScrapeSitemapParams.TimeoutOpts; /** * Optional RE2-compatible regex pattern. Only URLs matching this pattern are @@ -5199,6 +5589,28 @@ export interface WebWebScrapeSitemapParams { zdr?: 'enabled' | 'disabled'; } +export namespace WebWebScrapeSitemapParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } +} + export declare namespace Web { export { type WebAnswersResponse as WebAnswersResponse, diff --git a/tests/api-resources/ai.test.ts b/tests/api-resources/ai.test.ts index 72464aad..e87f6f3d 100644 --- a/tests/api-resources/ai.test.ts +++ b/tests/api-resources/ai.test.ts @@ -26,7 +26,7 @@ describe('resource ai', () => { url: 'https://example.com', maxAgeMs: 0, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); @@ -49,7 +49,7 @@ describe('resource ai', () => { maxAgeMs: 0, maxProducts: 1, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); }); diff --git a/tests/api-resources/brand.test.ts b/tests/api-resources/brand.test.ts index 5722af22..b92d3c70 100644 --- a/tests/api-resources/brand.test.ts +++ b/tests/api-resources/brand.test.ts @@ -29,7 +29,7 @@ describe('resource brand', () => { maxAgeMs: 0, maxSpeed: true, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); @@ -52,7 +52,7 @@ describe('resource brand', () => { maxAgeMs: 0, tags: ['production', 'team-alpha'], theme: 'light', - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); diff --git a/tests/api-resources/industry.test.ts b/tests/api-resources/industry.test.ts index 6d0a4a3e..e9907673 100644 --- a/tests/api-resources/industry.test.ts +++ b/tests/api-resources/industry.test.ts @@ -27,7 +27,7 @@ describe('resource industry', () => { maxResults: 1, minResults: 1, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); @@ -50,7 +50,7 @@ describe('resource industry', () => { maxResults: 1, minResults: 1, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, type: 'original_sic', }); }); diff --git a/tests/api-resources/utility.test.ts b/tests/api-resources/utility.test.ts index 63476b03..120bfd69 100644 --- a/tests/api-resources/utility.test.ts +++ b/tests/api-resources/utility.test.ts @@ -29,7 +29,7 @@ describe('resource utility', () => { identifier: { domain: 'xxx' }, type: 'brand', tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); }); diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 39da3724..9823adb7 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -29,7 +29,7 @@ describe('resource web', () => { json_format: { pricing_page_url: 'bar', plans: 'bar' }, mode: 'fast', tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); @@ -79,7 +79,7 @@ describe('resource web', () => { settleAnimations: true, stopAfterMs: 10000, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, waitForMs: 0, }); }); @@ -102,7 +102,7 @@ describe('resource web', () => { domain: 'xxx', numCompetitors: 1, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); @@ -128,7 +128,7 @@ describe('resource web', () => { domain: 'xxx', maxAgeMs: 0, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, }, { path: '/_stainless_unknown_path' }, ), @@ -158,7 +158,7 @@ describe('resource web', () => { domain: 'xxx', maxAgeMs: 0, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, }, { path: '/_stainless_unknown_path' }, ), @@ -194,7 +194,7 @@ describe('resource web', () => { page: 'login', scrollOffset: 0, tags: ['production', 'team-alpha'], - timeoutMS: 1, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, viewport: { height: 240, width: 240 }, waitForMs: 0, zdr: 'enabled', @@ -236,14 +236,14 @@ describe('resource web', () => { start: 1, }, shortenBase64Images: true, - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, useMainContentOnly: true, waitForMs: 0, }, numResults: 10, queryFanout: true, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); }); @@ -283,7 +283,7 @@ describe('resource web', () => { shortenBase64Images: true, stopAfterMs: 10000, tags: ['production', 'team-alpha'], - timeoutMS: 1000, + timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, urlRegex: '^https?://[^/]+/blog/', useMainContentOnly: true, waitForMs: 0, @@ -310,7 +310,7 @@ describe('resource web', () => { country: 'de', headers: { foo: 'J!' }, tags: ['production', 'team-alpha'], - timeoutMS: 1, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, zdr: 'enabled', }); }); @@ -346,7 +346,7 @@ describe('resource web', () => { }, settleAnimations: true, tags: ['production', 'team-alpha'], - timeoutMS: 1, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, useMainContentOnly: true, waitForMs: 0, zdr: 'enabled', @@ -380,7 +380,7 @@ describe('resource web', () => { headers: { foo: 'J!' }, maxAgeMs: 0, tags: ['production', 'team-alpha'], - timeoutMS: 1, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, waitForMs: 0, }); }); @@ -420,7 +420,7 @@ describe('resource web', () => { settleAnimations: true, shortenBase64Images: true, tags: ['production', 'team-alpha'], - timeoutMS: 1, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, useMainContentOnly: true, waitForMs: 0, zdr: 'enabled', @@ -449,7 +449,7 @@ describe('resource web', () => { search: 'help center and troubleshooting articles', sitemapUrl: 'https://example.com', tags: ['production', 'team-alpha'], - timeoutMS: 1, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, urlRegex: '^https?://[^/]+/blog/', zdr: 'enabled', }); From 41e8ff12404fb3fe0d6072cced54a008756ae6b4 Mon Sep 17 00:00:00 2001 From: contextualbeer Date: Tue, 15 Sep 2026 11:06:38 +0200 Subject: [PATCH 040/232] release: 2.18.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 18 ++++++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 21 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 9a61761c..7723ed4f 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.17.0" + ".": "2.18.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 32db6779..dbe6e31c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,23 @@ # Changelog +## [2.18.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.17.0...v2.18.0) (2026-09-15) + + +### Features + +* **answers:** add live web research with fast and ultra modes ([#954](https://github.com/context-dot-dev/context-typescript-sdk/issues/954)) ([8d9f488](https://github.com/context-dot-dev/context-typescript-sdk/commit/8d9f4882f87378e63dcfd8737e067c9b17770406)) +* **api-keys:** enforce scoped API key permissions ([#1038](https://github.com/context-dot-dev/context-typescript-sdk/issues/1038)) ([de5e60d](https://github.com/context-dot-dev/context-typescript-sdk/commit/de5e60dcc85e3754302cec35060cffe8c238cd8a)) +* **api:** unify timeout configuration and return partial results ([#1030](https://github.com/context-dot-dev/context-typescript-sdk/issues/1030)) ([b8e4d37](https://github.com/context-dot-dev/context-typescript-sdk/commit/b8e4d371a307f5f7effc7984cc3e6f458d9ab5fa)) +* **monitors:** add page selector filters ([#1037](https://github.com/context-dot-dev/context-typescript-sdk/issues/1037)) ([25fd26d](https://github.com/context-dot-dev/context-typescript-sdk/commit/25fd26d00df62cd2bc4fc04f246940494e07828b)) +* **web:** add raw bytes scraping endpoint ([#1081](https://github.com/context-dot-dev/context-typescript-sdk/issues/1081)) ([dec6eb8](https://github.com/context-dot-dev/context-typescript-sdk/commit/dec6eb854b4c25592a3c6eeb065e195417ab4cb4)) + + +### Bug Fixes + +* **api:** honour maxAgeMs=0 on brand retrieve, styleguide and fonts endpoints ([#998](https://github.com/context-dot-dev/context-typescript-sdk/issues/998)) ([503a20e](https://github.com/context-dot-dev/context-typescript-sdk/commit/503a20ed84b09182432bc164c2d4bfe6ca386505)) +* **security:** consolidate dependency updates and harden public fetches ([#1040](https://github.com/context-dot-dev/context-typescript-sdk/issues/1040)) ([db2c906](https://github.com/context-dot-dev/context-typescript-sdk/commit/db2c9065d92e20c8db5dac07c65e5b1fd289e798)) +* **webhooks:** format Slack webhook notifications ([#1045](https://github.com/context-dot-dev/context-typescript-sdk/issues/1045)) ([9615345](https://github.com/context-dot-dev/context-typescript-sdk/commit/961534544b1fd85fdc351be36d7f8a4ba54b5da7)) + ## [2.17.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.16.0...v2.17.0) (2026-09-11) diff --git a/package.json b/package.json index 21e26d43..708450cb 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.17.0", + "version": "2.18.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index acffe370..4acb506d 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.17.0'; // x-release-please-version +export const VERSION = '2.18.0'; // x-release-please-version From f72717e26dc1d99e59d4c8ec36edc4e2a864c484 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Tue, 15 Sep 2026 11:53:50 +0200 Subject: [PATCH 041/232] ci: repair TypeScript SDK npm publishing --- .github/workflows/publish-npm.yml | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml index 57c09214..616f7d34 100644 --- a/.github/workflows/publish-npm.yml +++ b/.github/workflows/publish-npm.yml @@ -6,7 +6,7 @@ on: workflow_dispatch: inputs: path: - description: The path to run the release in, e.g. '.' or 'packages/mcp-server' + description: "The package path to publish ('.' for the SDK)" required: true release: @@ -32,20 +32,16 @@ jobs: run: | yarn install - - name: Publish to NPM + - name: Build package run: | - if [ -n "$INPUT_PATH" ]; then - PATHS_RELEASED="[\"$INPUT_PATH\"]" - else - PATHS_RELEASED='[\".\", \"packages/mcp-server\"]' + if [ -n "$INPUT_PATH" ] && [ "$INPUT_PATH" != "." ]; then + echo "Only the root SDK package (.) is supported." + exit 1 fi - yarn tsn scripts/publish-packages.ts "{ \"paths_released\": \"$PATHS_RELEASED\" }" + yarn build env: INPUT_PATH: ${{ github.event.inputs.path }} - - name: Upload MCP Server DXT GitHub release asset - run: | - gh release upload ${{ github.event.release.tag_name }} \ - packages/mcp-server/context_dev_api.mcpb - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + - name: Publish to NPM + working-directory: dist + run: npm publish --access public From 2604977688d9d362d485276459ca263b4f8b9f4d Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Tue, 15 Sep 2026 11:54:29 +0200 Subject: [PATCH 042/232] ci: add SDK publishing safeguards --- .github/workflows/publish-npm.yml | 33 ++++++++++++++++++------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml index 616f7d34..3fb3af8c 100644 --- a/.github/workflows/publish-npm.yml +++ b/.github/workflows/publish-npm.yml @@ -5,9 +5,10 @@ name: Publish NPM on: workflow_dispatch: inputs: - path: - description: "The package path to publish ('.' for the SDK)" + tag: + description: 'Release tag to publish, e.g. v2.18.0' required: true + type: string release: types: [published] @@ -15,33 +16,37 @@ on: jobs: publish: name: publish + if: github.repository == 'context-dot-dev/context-typescript-sdk' runs-on: ubuntu-latest permissions: - contents: write + contents: read id-token: write steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + ref: refs/tags/${{ inputs.tag || github.event.release.tag_name }} + persist-credentials: false - name: Set up Node uses: actions/setup-node@3235b876344d2a9aa001b8d1453c930bba69e610 # v3.9.1 with: node-version: '24' + - name: Verify release version + run: test "$RELEASE_TAG" = "v$(node -p 'require("./package.json").version')" + env: + RELEASE_TAG: ${{ inputs.tag || github.event.release.tag_name }} + + - name: Set up npm trusted publishing + run: npm install --global npm@11 + - name: Install dependencies - run: | - yarn install + run: yarn install --frozen-lockfile - name: Build package - run: | - if [ -n "$INPUT_PATH" ] && [ "$INPUT_PATH" != "." ]; then - echo "Only the root SDK package (.) is supported." - exit 1 - fi - yarn build - env: - INPUT_PATH: ${{ github.event.inputs.path }} + run: yarn build - name: Publish to NPM working-directory: dist - run: npm publish --access public + run: npm publish --access public --provenance From 9f55749869ff8149d1458357b11e55976519e590 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 15 Sep 2026 10:32:55 +0000 Subject: [PATCH 043/232] fix(api): guarantee search descriptions and align response types (#1089) Stainless-Generated-From: 75a0b521b119edb233c660e069c47b180c715eae --- src/resources/brand.ts | 120 ++++++++++++++++++++--------------------- src/resources/web.ts | 3 +- 2 files changed, 62 insertions(+), 61 deletions(-) diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 9c544b40..11e94515 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -57,6 +57,11 @@ export class Brand extends APIResource { } export interface BrandRetrieveResponse { + /** + * Detailed brand information + */ + brand: BrandRetrieveResponse.Brand; + /** * Cache outcome for this response. Composite responses are hits only when every * cache-controlled fetch contributing to the output was a hit; age_ms is the @@ -65,20 +70,20 @@ export interface BrandRetrieveResponse { cache_metadata: BrandRetrieveResponse.CacheMetadata; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * HTTP status code */ - request_id: string; + code: number; /** - * Detailed brand information + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. */ - brand?: BrandRetrieveResponse.Brand; + request_id: string; /** - * HTTP status code + * Status of the response, e.g., 'ok' */ - code?: number; + status: string; /** * Credit usage, included whenever a valid API key is provided. @@ -90,32 +95,9 @@ export interface BrandRetrieveResponse { * data completed so far. Unfinished fields are omitted. */ partial?: boolean; - - /** - * Status of the response, e.g., 'ok' - */ - status?: string; } export namespace BrandRetrieveResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - /** * Detailed brand information */ @@ -890,6 +872,24 @@ export namespace BrandRetrieveResponse { } } + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + export interface CacheMetadata { + /** + * Age of the cached data in milliseconds. Zero for miss and zdr responses. + */ + age_ms: number; + + /** + * Whether the response was served from cache, required fresh work, or honored + * zero-data-retention cache bypass. + */ + status: 'hit' | 'miss' | 'zdr'; + } + /** * Credit usage, included whenever a valid API key is provided. */ @@ -907,6 +907,11 @@ export namespace BrandRetrieveResponse { } export interface BrandRetrieveSimplifiedResponse { + /** + * Simplified brand information + */ + brand: BrandRetrieveSimplifiedResponse.Brand; + /** * Cache outcome for this response. Composite responses are hits only when every * cache-controlled fetch contributing to the output was a hit; age_ms is the @@ -915,20 +920,20 @@ export interface BrandRetrieveSimplifiedResponse { cache_metadata: BrandRetrieveSimplifiedResponse.CacheMetadata; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * HTTP status code of the response */ - request_id: string; + code: number; /** - * Simplified brand information + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. */ - brand?: BrandRetrieveSimplifiedResponse.Brand; + request_id: string; /** - * HTTP status code of the response + * Status of the response, e.g., 'ok' */ - code?: number; + status: string; /** * Credit usage, included whenever a valid API key is provided. @@ -940,32 +945,9 @@ export interface BrandRetrieveSimplifiedResponse { * returned. */ partial?: boolean; - - /** - * Status of the response, e.g., 'ok' - */ - status?: string; } export namespace BrandRetrieveSimplifiedResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - /** * Simplified brand information */ @@ -1131,6 +1113,24 @@ export namespace BrandRetrieveSimplifiedResponse { } } + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + export interface CacheMetadata { + /** + * Age of the cached data in milliseconds. Zero for miss and zdr responses. + */ + age_ms: number; + + /** + * Whether the response was served from cache, required fresh work, or honored + * zero-data-retention cache bypass. + */ + status: 'hit' | 'miss' | 'zdr'; + } + /** * Credit usage, included whenever a valid API key is provided. */ diff --git a/src/resources/web.ts b/src/resources/web.ts index eaddc959..c27d2d49 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1439,7 +1439,8 @@ export namespace WebSearchResponse { export interface Result { /** - * Snippet excerpt from the page. + * Snippet excerpt from the page. Empty string when the search provider does not + * supply a snippet. */ description: string; From 75a0b521b119edb233c660e069c47b180c715eae Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 15 Sep 2026 10:32:55 +0000 Subject: [PATCH 044/232] seal --- .github/workflows/publish-npm.yml | 43 +++++------ .release-please-manifest.json | 2 +- CHANGELOG.md | 18 +++++ package.json | 2 +- src/resources/brand.ts | 120 +++++++++++++++--------------- src/resources/web.ts | 3 +- src/version.ts | 2 +- 7 files changed, 105 insertions(+), 85 deletions(-) diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml index 57c09214..3fb3af8c 100644 --- a/.github/workflows/publish-npm.yml +++ b/.github/workflows/publish-npm.yml @@ -5,9 +5,10 @@ name: Publish NPM on: workflow_dispatch: inputs: - path: - description: The path to run the release in, e.g. '.' or 'packages/mcp-server' + tag: + description: 'Release tag to publish, e.g. v2.18.0' required: true + type: string release: types: [published] @@ -15,37 +16,37 @@ on: jobs: publish: name: publish + if: github.repository == 'context-dot-dev/context-typescript-sdk' runs-on: ubuntu-latest permissions: - contents: write + contents: read id-token: write steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + ref: refs/tags/${{ inputs.tag || github.event.release.tag_name }} + persist-credentials: false - name: Set up Node uses: actions/setup-node@3235b876344d2a9aa001b8d1453c930bba69e610 # v3.9.1 with: node-version: '24' + - name: Verify release version + run: test "$RELEASE_TAG" = "v$(node -p 'require("./package.json").version')" + env: + RELEASE_TAG: ${{ inputs.tag || github.event.release.tag_name }} + + - name: Set up npm trusted publishing + run: npm install --global npm@11 + - name: Install dependencies - run: | - yarn install + run: yarn install --frozen-lockfile - - name: Publish to NPM - run: | - if [ -n "$INPUT_PATH" ]; then - PATHS_RELEASED="[\"$INPUT_PATH\"]" - else - PATHS_RELEASED='[\".\", \"packages/mcp-server\"]' - fi - yarn tsn scripts/publish-packages.ts "{ \"paths_released\": \"$PATHS_RELEASED\" }" - env: - INPUT_PATH: ${{ github.event.inputs.path }} + - name: Build package + run: yarn build - - name: Upload MCP Server DXT GitHub release asset - run: | - gh release upload ${{ github.event.release.tag_name }} \ - packages/mcp-server/context_dev_api.mcpb - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + - name: Publish to NPM + working-directory: dist + run: npm publish --access public --provenance diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 9a61761c..7723ed4f 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.17.0" + ".": "2.18.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 32db6779..dbe6e31c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,23 @@ # Changelog +## [2.18.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.17.0...v2.18.0) (2026-09-15) + + +### Features + +* **answers:** add live web research with fast and ultra modes ([#954](https://github.com/context-dot-dev/context-typescript-sdk/issues/954)) ([8d9f488](https://github.com/context-dot-dev/context-typescript-sdk/commit/8d9f4882f87378e63dcfd8737e067c9b17770406)) +* **api-keys:** enforce scoped API key permissions ([#1038](https://github.com/context-dot-dev/context-typescript-sdk/issues/1038)) ([de5e60d](https://github.com/context-dot-dev/context-typescript-sdk/commit/de5e60dcc85e3754302cec35060cffe8c238cd8a)) +* **api:** unify timeout configuration and return partial results ([#1030](https://github.com/context-dot-dev/context-typescript-sdk/issues/1030)) ([b8e4d37](https://github.com/context-dot-dev/context-typescript-sdk/commit/b8e4d371a307f5f7effc7984cc3e6f458d9ab5fa)) +* **monitors:** add page selector filters ([#1037](https://github.com/context-dot-dev/context-typescript-sdk/issues/1037)) ([25fd26d](https://github.com/context-dot-dev/context-typescript-sdk/commit/25fd26d00df62cd2bc4fc04f246940494e07828b)) +* **web:** add raw bytes scraping endpoint ([#1081](https://github.com/context-dot-dev/context-typescript-sdk/issues/1081)) ([dec6eb8](https://github.com/context-dot-dev/context-typescript-sdk/commit/dec6eb854b4c25592a3c6eeb065e195417ab4cb4)) + + +### Bug Fixes + +* **api:** honour maxAgeMs=0 on brand retrieve, styleguide and fonts endpoints ([#998](https://github.com/context-dot-dev/context-typescript-sdk/issues/998)) ([503a20e](https://github.com/context-dot-dev/context-typescript-sdk/commit/503a20ed84b09182432bc164c2d4bfe6ca386505)) +* **security:** consolidate dependency updates and harden public fetches ([#1040](https://github.com/context-dot-dev/context-typescript-sdk/issues/1040)) ([db2c906](https://github.com/context-dot-dev/context-typescript-sdk/commit/db2c9065d92e20c8db5dac07c65e5b1fd289e798)) +* **webhooks:** format Slack webhook notifications ([#1045](https://github.com/context-dot-dev/context-typescript-sdk/issues/1045)) ([9615345](https://github.com/context-dot-dev/context-typescript-sdk/commit/961534544b1fd85fdc351be36d7f8a4ba54b5da7)) + ## [2.17.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.16.0...v2.17.0) (2026-09-11) diff --git a/package.json b/package.json index 21e26d43..708450cb 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.17.0", + "version": "2.18.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 9c544b40..11e94515 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -57,6 +57,11 @@ export class Brand extends APIResource { } export interface BrandRetrieveResponse { + /** + * Detailed brand information + */ + brand: BrandRetrieveResponse.Brand; + /** * Cache outcome for this response. Composite responses are hits only when every * cache-controlled fetch contributing to the output was a hit; age_ms is the @@ -65,20 +70,20 @@ export interface BrandRetrieveResponse { cache_metadata: BrandRetrieveResponse.CacheMetadata; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * HTTP status code */ - request_id: string; + code: number; /** - * Detailed brand information + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. */ - brand?: BrandRetrieveResponse.Brand; + request_id: string; /** - * HTTP status code + * Status of the response, e.g., 'ok' */ - code?: number; + status: string; /** * Credit usage, included whenever a valid API key is provided. @@ -90,32 +95,9 @@ export interface BrandRetrieveResponse { * data completed so far. Unfinished fields are omitted. */ partial?: boolean; - - /** - * Status of the response, e.g., 'ok' - */ - status?: string; } export namespace BrandRetrieveResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - /** * Detailed brand information */ @@ -890,6 +872,24 @@ export namespace BrandRetrieveResponse { } } + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + export interface CacheMetadata { + /** + * Age of the cached data in milliseconds. Zero for miss and zdr responses. + */ + age_ms: number; + + /** + * Whether the response was served from cache, required fresh work, or honored + * zero-data-retention cache bypass. + */ + status: 'hit' | 'miss' | 'zdr'; + } + /** * Credit usage, included whenever a valid API key is provided. */ @@ -907,6 +907,11 @@ export namespace BrandRetrieveResponse { } export interface BrandRetrieveSimplifiedResponse { + /** + * Simplified brand information + */ + brand: BrandRetrieveSimplifiedResponse.Brand; + /** * Cache outcome for this response. Composite responses are hits only when every * cache-controlled fetch contributing to the output was a hit; age_ms is the @@ -915,20 +920,20 @@ export interface BrandRetrieveSimplifiedResponse { cache_metadata: BrandRetrieveSimplifiedResponse.CacheMetadata; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * HTTP status code of the response */ - request_id: string; + code: number; /** - * Simplified brand information + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. */ - brand?: BrandRetrieveSimplifiedResponse.Brand; + request_id: string; /** - * HTTP status code of the response + * Status of the response, e.g., 'ok' */ - code?: number; + status: string; /** * Credit usage, included whenever a valid API key is provided. @@ -940,32 +945,9 @@ export interface BrandRetrieveSimplifiedResponse { * returned. */ partial?: boolean; - - /** - * Status of the response, e.g., 'ok' - */ - status?: string; } export namespace BrandRetrieveSimplifiedResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - /** * Simplified brand information */ @@ -1131,6 +1113,24 @@ export namespace BrandRetrieveSimplifiedResponse { } } + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + export interface CacheMetadata { + /** + * Age of the cached data in milliseconds. Zero for miss and zdr responses. + */ + age_ms: number; + + /** + * Whether the response was served from cache, required fresh work, or honored + * zero-data-retention cache bypass. + */ + status: 'hit' | 'miss' | 'zdr'; + } + /** * Credit usage, included whenever a valid API key is provided. */ diff --git a/src/resources/web.ts b/src/resources/web.ts index eaddc959..c27d2d49 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1439,7 +1439,8 @@ export namespace WebSearchResponse { export interface Result { /** - * Snippet excerpt from the page. + * Snippet excerpt from the page. Empty string when the search provider does not + * supply a snippet. */ description: string; diff --git a/src/version.ts b/src/version.ts index acffe370..4acb506d 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.17.0'; // x-release-please-version +export const VERSION = '2.18.0'; // x-release-please-version From a87a538442d4982b1ccd06937049e6def1545ca6 Mon Sep 17 00:00:00 2001 From: contextualbeer Date: Tue, 15 Sep 2026 12:35:00 +0200 Subject: [PATCH 045/232] release: 2.18.1 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 7723ed4f..4edefb29 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.18.0" + ".": "2.18.1" } diff --git a/CHANGELOG.md b/CHANGELOG.md index dbe6e31c..de7e87a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [2.18.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.18.0...v2.18.1) (2026-09-15) + + +### Bug Fixes + +* **api:** guarantee search descriptions and align response types ([#1089](https://github.com/context-dot-dev/context-typescript-sdk/issues/1089)) ([9f55749](https://github.com/context-dot-dev/context-typescript-sdk/commit/9f55749869ff8149d1458357b11e55976519e590)) + ## [2.18.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.17.0...v2.18.0) (2026-09-15) diff --git a/package.json b/package.json index 708450cb..f1cfe3c3 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.18.0", + "version": "2.18.1", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 4acb506d..3c2f391b 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.18.0'; // x-release-please-version +export const VERSION = '2.18.1'; // x-release-please-version From f4593e59b48efeb3c96c71f58fe148f6978261f4 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 15 Sep 2026 12:29:31 +0000 Subject: [PATCH 046/232] seal --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 7723ed4f..4edefb29 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.18.0" + ".": "2.18.1" } diff --git a/CHANGELOG.md b/CHANGELOG.md index dbe6e31c..de7e87a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [2.18.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.18.0...v2.18.1) (2026-09-15) + + +### Bug Fixes + +* **api:** guarantee search descriptions and align response types ([#1089](https://github.com/context-dot-dev/context-typescript-sdk/issues/1089)) ([9f55749](https://github.com/context-dot-dev/context-typescript-sdk/commit/9f55749869ff8149d1458357b11e55976519e590)) + ## [2.18.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.17.0...v2.18.0) (2026-09-15) diff --git a/package.json b/package.json index 708450cb..f1cfe3c3 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.18.0", + "version": "2.18.1", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 4acb506d..3c2f391b 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.18.0'; // x-release-please-version +export const VERSION = '2.18.1'; // x-release-please-version From 2baeba3bf88170a1e6c6c877d2a4758392202f01 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 16 Sep 2026 17:41:40 +0000 Subject: [PATCH 047/232] fix(api): lower partial scrape timeout minimum to five seconds (#1118) Stainless-Generated-From: 24c347e98c4c6c182248d72a33048b744caa57d9 --- src/resources/web.ts | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index c27d2d49..0936ab72 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -3009,7 +3009,7 @@ export namespace WebExtractFontsParams { * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are * not cached as complete results. "return-partial" requires milliseconds of at - * least 15000. + * least 5000. */ behavior?: 'fail' | 'return-partial'; } @@ -3076,7 +3076,7 @@ export namespace WebExtractStyleguideParams { * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are * not cached as complete results. "return-partial" requires milliseconds of at - * least 15000. + * least 5000. */ behavior?: 'fail' | 'return-partial'; } @@ -3415,7 +3415,7 @@ export namespace WebScreenshotParams { * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are * not cached as complete results. "return-partial" requires milliseconds of at - * least 15000. + * least 5000. */ behavior?: 'fail' | 'return-partial'; } @@ -3831,7 +3831,7 @@ export namespace WebSearchParams { * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are * not cached as complete results. "return-partial" requires milliseconds of at - * least 15000. + * least 5000. */ behavior?: 'fail' | 'return-partial'; } @@ -4920,7 +4920,7 @@ export namespace WebWebScrapeHTMLParams { * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are * not cached as complete results. "return-partial" requires milliseconds of at - * least 15000. + * least 5000. */ behavior?: 'fail' | 'return-partial'; } @@ -5084,7 +5084,7 @@ export namespace WebWebScrapeImagesParams { * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are * not cached as complete results. "return-partial" requires milliseconds of at - * least 15000. + * least 5000. */ behavior?: 'fail' | 'return-partial'; } @@ -5518,7 +5518,7 @@ export namespace WebWebScrapeMdParams { * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are * not cached as complete results. "return-partial" requires milliseconds of at - * least 15000. + * least 5000. */ behavior?: 'fail' | 'return-partial'; } From d7c05648fa40edefc54418d89d1fe5954bd420b5 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 17 Sep 2026 06:32:29 +0000 Subject: [PATCH 048/232] seal --- src/resources/web.ts | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index c27d2d49..0936ab72 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -3009,7 +3009,7 @@ export namespace WebExtractFontsParams { * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are * not cached as complete results. "return-partial" requires milliseconds of at - * least 15000. + * least 5000. */ behavior?: 'fail' | 'return-partial'; } @@ -3076,7 +3076,7 @@ export namespace WebExtractStyleguideParams { * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are * not cached as complete results. "return-partial" requires milliseconds of at - * least 15000. + * least 5000. */ behavior?: 'fail' | 'return-partial'; } @@ -3415,7 +3415,7 @@ export namespace WebScreenshotParams { * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are * not cached as complete results. "return-partial" requires milliseconds of at - * least 15000. + * least 5000. */ behavior?: 'fail' | 'return-partial'; } @@ -3831,7 +3831,7 @@ export namespace WebSearchParams { * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are * not cached as complete results. "return-partial" requires milliseconds of at - * least 15000. + * least 5000. */ behavior?: 'fail' | 'return-partial'; } @@ -4920,7 +4920,7 @@ export namespace WebWebScrapeHTMLParams { * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are * not cached as complete results. "return-partial" requires milliseconds of at - * least 15000. + * least 5000. */ behavior?: 'fail' | 'return-partial'; } @@ -5084,7 +5084,7 @@ export namespace WebWebScrapeImagesParams { * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are * not cached as complete results. "return-partial" requires milliseconds of at - * least 15000. + * least 5000. */ behavior?: 'fail' | 'return-partial'; } @@ -5518,7 +5518,7 @@ export namespace WebWebScrapeMdParams { * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are * not cached as complete results. "return-partial" requires milliseconds of at - * least 15000. + * least 5000. */ behavior?: 'fail' | 'return-partial'; } From 9a80da2aed02602d5ef7ab2bff03eff440753680 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 18 Sep 2026 04:07:23 +0000 Subject: [PATCH 049/232] feat(products): extract ProductGroup variants with images (#1124) Stainless-Generated-From: 449b3ce250a415c0c3fb2e279bfa11f44e54ea68 --- src/resources/ai.ts | 58 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/src/resources/ai.ts b/src/resources/ai.ts index 14c0b1b5..221a4d38 100644 --- a/src/resources/ai.ts +++ b/src/resources/ai.ts @@ -214,6 +214,35 @@ export namespace AIExtractProductResponse { * URL to the product page */ url?: string | null; + + /** + * Product variations, such as different colors or sizes, with their attributes and + * images. Empty if none are found. May not include every variation offered by the + * store. + */ + variants?: Array; + } + + export namespace Product { + export interface Variant { + /** + * Explicit variant attributes such as color, size, material, pattern and + * properties declared by page. + */ + attributes: { [key: string]: string }; + + /** + * Original source image URLs explicitly attached to this variant. + */ + images: Array; + + sku: string | null; + + /** + * Variant or offer URL when provided by the source. May be shared by variants. + */ + url: string | null; + } } } @@ -376,6 +405,35 @@ export namespace AIExtractProductsResponse { * URL to the product page */ url?: string | null; + + /** + * Product variations, such as different colors or sizes, with their attributes and + * images. Empty if none are found. May not include every variation offered by the + * store. + */ + variants?: Array; + } + + export namespace Product { + export interface Variant { + /** + * Explicit variant attributes such as color, size, material, pattern and + * properties declared by page. + */ + attributes: { [key: string]: string }; + + /** + * Original source image URLs explicitly attached to this variant. + */ + images: Array; + + sku: string | null; + + /** + * Variant or offer URL when provided by the source. May be shared by variants. + */ + url: string | null; + } } } From c5235fc82b2d2abff938d25175aa6d1152d0f867 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 18 Sep 2026 05:19:21 +0000 Subject: [PATCH 050/232] feat(scrape): add CSS extraction rules to HTML scraping (#1146) Stainless-Generated-From: e183d7360dba568f99f553bbb2af7bd984682d69 --- src/resources/web.ts | 53 +++++++++++++++++++++++++++++---- tests/api-resources/web.test.ts | 1 + 2 files changed, 48 insertions(+), 6 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 0936ab72..e61c7f10 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -168,12 +168,16 @@ export class Web extends APIResource { } /** - * Scrapes the given URL and returns the raw HTML content of the page. The base - * request costs 1 credit; requests with browser actions cost 2 credits. A request - * that hits its timeoutOpts.milliseconds deadline fails with 408 and is not - * billed, unless timeoutOpts.behavior=return-partial is set — then the page as - * rendered so far is returned with `finalDOMState: "still-loading"` and billed at - * the base cost of 1 credit. + * Scrapes the given URL and returns the HTML content of the page. Optional + * extractRules return deterministic structured data in extracted using CSS + * selectors, attributes, lists, and nested rules, without an LLM or additional + * credits. Rules run on the returned HTML after selector and main-content + * filtering. Send extractRules as a JSON-encoded query parameter. The base request + * costs 1 credit; requests with browser actions cost 2 credits. A request that + * hits its timeoutOpts.milliseconds deadline fails with 408 and is not billed, + * unless timeoutOpts.behavior=return-partial is set — then the page as rendered so + * far is returned with `finalDOMState: "still-loading"` and billed at the base + * cost of 1 credit. * * @example * ```ts @@ -1917,6 +1921,14 @@ export interface WebWebScrapeHTMLResponse { */ actionsHtmlStale?: boolean; + /** + * Present only when extractRules is supplied. Keys match the requested fields. + * Values are normalized text, raw attribute strings, outer HTML, nested objects, + * or lists. Missing items are null; lists with no matches are empty. Rules run on + * the returned HTML after filtering. + */ + extracted?: { [key: string]: string | unknown | Array | null }; + /** * Credit usage, included whenever a valid API key is provided. */ @@ -4749,6 +4761,17 @@ export interface WebWebScrapeHTMLParams { */ excludeSelectors?: Array | null; + /** + * Optional CSS extraction rules applied to the returned HTML after selector and + * main-content filtering. Use selector strings ("h1", "a@href") or objects with + * selector, type (item or list), and output (text, html, @attribute, or nested + * rules). Text whitespace is normalized; html includes the matched element; + * attributes are returned as written. Missing items are null and missing lists are + * empty. CSS only; XPath is not supported. Maximum: 100 fields across 5 levels. + * Send a JSON-encoded string in the extractRules query parameter. + */ + extractRules?: { [key: string]: string | WebWebScrapeHTMLParams.UnionMember1 }; + /** * Optional outbound HTTP headers forwarded only to the target URL, sent as * deep-object query params such as headers[X-Custom]=value. When provided, caching @@ -4873,6 +4896,24 @@ export namespace WebWebScrapeHTMLParams { maxScrolls?: number; } + export interface UnionMember1 { + selector: string; + + output?: 'text' | 'html' | string | { [key: string]: string | UnionMember1.UnionMember1 }; + + type?: 'item' | 'list'; + } + + export namespace UnionMember1 { + export interface UnionMember1 { + selector: string; + + output?: 'text' | 'html' | string | unknown; + + type?: 'item' | 'list'; + } + } + /** * PDF parsing controls. Use start/end to limit text extraction and embedded-image * detection/OCR to an inclusive 1-based page range. diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 9823adb7..702808f3 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -334,6 +334,7 @@ describe('resource web', () => { actions: [{ do: 'wait', timeMs: 0 }], country: 'de', excludeSelectors: ['x'], + extractRules: { foo: 'x' }, headers: { foo: 'J!' }, includeFrames: true, includeSelectors: ['x'], From 14fabea8e3536ee170db274fdd08395bdfaad25a Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 18 Sep 2026 05:30:10 +0000 Subject: [PATCH 051/232] seal --- src/resources/ai.ts | 67 +++++++++++++ src/resources/industry.ts | 18 ++++ src/resources/parse.ts | 8 +- src/resources/people.ts | 9 ++ src/resources/web.ts | 144 +++++++++++++++++++++++---- tests/api-resources/ai.test.ts | 1 + tests/api-resources/industry.test.ts | 2 + tests/api-resources/web.test.ts | 7 ++ 8 files changed, 230 insertions(+), 26 deletions(-) diff --git a/src/resources/ai.ts b/src/resources/ai.ts index 14c0b1b5..079505f4 100644 --- a/src/resources/ai.ts +++ b/src/resources/ai.ts @@ -214,6 +214,35 @@ export namespace AIExtractProductResponse { * URL to the product page */ url?: string | null; + + /** + * Product variations, such as different colors or sizes, with their attributes and + * images. Empty if none are found. May not include every variation offered by the + * store. + */ + variants?: Array; + } + + export namespace Product { + export interface Variant { + /** + * Explicit variant attributes such as color, size, material, pattern and + * properties declared by page. + */ + attributes: { [key: string]: string }; + + /** + * Original source image URLs explicitly attached to this variant. + */ + images: Array; + + sku: string | null; + + /** + * Variant or offer URL when provided by the source. May be shared by variants. + */ + url: string | null; + } } } @@ -376,6 +405,35 @@ export namespace AIExtractProductsResponse { * URL to the product page */ url?: string | null; + + /** + * Product variations, such as different colors or sizes, with their attributes and + * images. Empty if none are found. May not include every variation offered by the + * store. + */ + variants?: Array; + } + + export namespace Product { + export interface Variant { + /** + * Explicit variant attributes such as color, size, material, pattern and + * properties declared by page. + */ + attributes: { [key: string]: string }; + + /** + * Original source image URLs explicitly attached to this variant. + */ + images: Array; + + sku: string | null; + + /** + * Variant or offer URL when provided by the source. May be shared by variants. + */ + url: string | null; + } } } @@ -403,6 +461,15 @@ export interface AIExtractProductParams { * timeoutOpts object. */ timeoutOpts?: AIExtractProductParams.TimeoutOpts; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace AIExtractProductParams { diff --git a/src/resources/industry.ts b/src/resources/industry.ts index 606460d7..3beac749 100644 --- a/src/resources/industry.ts +++ b/src/resources/industry.ts @@ -230,6 +230,15 @@ export interface IndustryRetrieveNaicsParams { * timeoutOpts object. */ timeoutOpts?: IndustryRetrieveNaicsParams.TimeoutOpts; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace IndustryRetrieveNaicsParams { @@ -291,6 +300,15 @@ export interface IndustryRetrieveSicParams { * published by the SEC. Defaults to `original_sic`. */ type?: 'original_sic' | 'latest_sec'; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace IndustryRetrieveSicParams { diff --git a/src/resources/parse.ts b/src/resources/parse.ts index 3448644e..cf7f74e7 100644 --- a/src/resources/parse.ts +++ b/src/resources/parse.ts @@ -259,10 +259,10 @@ export interface ParseHandleParams { /** * Query param: Set to enabled to bypass shared caches and omit request and - * response content from retained usage logs. Requires zero data retention to be - * enabled for your organization (contact support@context.dev), otherwise the - * request fails with ZDR_NOT_ENABLED. Successful ZDR responses include - * X-Context-ZDR: true. + * response content from retained usage logs. Asset uploads are skipped, so hosted + * image URLs are omitted. Requires zero data retention to be enabled for your + * organization (contact support@context.dev), otherwise the request fails with + * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. */ zdr?: 'enabled' | 'disabled'; } diff --git a/src/resources/people.ts b/src/resources/people.ts index 3c8bec28..9ebccb35 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -304,6 +304,15 @@ export interface PersonEnrichParams { * timeoutOpts object. */ timeoutOpts?: PersonEnrichParams.TimeoutOpts; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace PersonEnrichParams { diff --git a/src/resources/web.ts b/src/resources/web.ts index 0936ab72..d33aa9d7 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -168,12 +168,16 @@ export class Web extends APIResource { } /** - * Scrapes the given URL and returns the raw HTML content of the page. The base - * request costs 1 credit; requests with browser actions cost 2 credits. A request - * that hits its timeoutOpts.milliseconds deadline fails with 408 and is not - * billed, unless timeoutOpts.behavior=return-partial is set — then the page as - * rendered so far is returned with `finalDOMState: "still-loading"` and billed at - * the base cost of 1 credit. + * Scrapes the given URL and returns the HTML content of the page. Optional + * extractRules return deterministic structured data in extracted using CSS + * selectors, attributes, lists, and nested rules, without an LLM or additional + * credits. Rules run on the returned HTML after selector and main-content + * filtering. Send extractRules as a JSON-encoded query parameter. The base request + * costs 1 credit; requests with browser actions cost 2 credits. A request that + * hits its timeoutOpts.milliseconds deadline fails with 408 and is not billed, + * unless timeoutOpts.behavior=return-partial is set — then the page as rendered so + * far is returned with `finalDOMState: "still-loading"` and billed at the base + * cost of 1 credit. * * @example * ```ts @@ -1917,6 +1921,14 @@ export interface WebWebScrapeHTMLResponse { */ actionsHtmlStale?: boolean; + /** + * Present only when extractRules is supplied. Keys match the requested fields. + * Values are normalized text, raw attribute strings, outer HTML, nested objects, + * or lists. Missing items are null; lists with no matches are empty. Rules run on + * the returned HTML after filtering. + */ + extracted?: { [key: string]: string | unknown | Array | null }; + /** * Credit usage, included whenever a valid API key is provided. */ @@ -2689,6 +2701,15 @@ export interface WebAnswersParams { * timeoutOpts object. */ timeoutOpts?: WebAnswersParams.TimeoutOpts; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace WebAnswersParams { @@ -2817,6 +2838,15 @@ export interface WebExtractParams { * crawled page. */ waitForMs?: number; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace WebExtractParams { @@ -2931,6 +2961,15 @@ export interface WebExtractCompetitorsParams { * timeoutOpts object. */ timeoutOpts?: WebExtractCompetitorsParams.TimeoutOpts; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace WebExtractCompetitorsParams { @@ -3057,6 +3096,15 @@ export interface WebExtractStyleguideParams { * timeoutOpts object. */ timeoutOpts?: WebExtractStyleguideParams.TimeoutOpts; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace WebExtractStyleguideParams { @@ -3391,9 +3439,10 @@ export interface WebScreenshotParams { /** * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ zdr?: 'enabled' | 'disabled'; } @@ -3731,6 +3780,15 @@ export interface WebSearchParams { * timeoutOpts object. */ timeoutOpts?: WebSearchParams.TimeoutOpts; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace WebSearchParams { @@ -4488,9 +4546,10 @@ export interface WebWebScrapeBytesParams { /** * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ zdr?: 'enabled' | 'disabled'; } @@ -4749,6 +4808,17 @@ export interface WebWebScrapeHTMLParams { */ excludeSelectors?: Array | null; + /** + * Optional CSS extraction rules applied to the returned HTML after selector and + * main-content filtering. Use selector strings ("h1", "a@href") or objects with + * selector, type (item or list), and output (text, html, @attribute, or nested + * rules). Text whitespace is normalized; html includes the matched element; + * attributes are returned as written. Missing items are null and missing lists are + * empty. CSS only; XPath is not supported. Maximum: 100 fields across 5 levels. + * Send a JSON-encoded string in the extractRules query parameter. + */ + extractRules?: { [key: string]: string | WebWebScrapeHTMLParams.UnionMember1 }; + /** * Optional outbound HTTP headers forwarded only to the target URL, sent as * deep-object query params such as headers[X-Custom]=value. When provided, caching @@ -4817,9 +4887,10 @@ export interface WebWebScrapeHTMLParams { /** * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ zdr?: 'enabled' | 'disabled'; } @@ -4873,6 +4944,24 @@ export namespace WebWebScrapeHTMLParams { maxScrolls?: number; } + export interface UnionMember1 { + selector: string; + + output?: 'text' | 'html' | string | { [key: string]: string | UnionMember1.UnionMember1 }; + + type?: 'item' | 'list'; + } + + export namespace UnionMember1 { + export interface UnionMember1 { + selector: string; + + output?: 'text' | 'html' | string | unknown; + + type?: 'item' | 'list'; + } + } + /** * PDF parsing controls. Use start/end to limit text extraction and embedded-image * detection/OCR to an inclusive 1-based page range. @@ -4990,6 +5079,15 @@ export interface WebWebScrapeImagesParams { * shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace WebWebScrapeImagesParams { @@ -5053,7 +5151,7 @@ export namespace WebWebScrapeImagesParams { /** * Host materializable images on the Brand.dev CDN and return their URL and MIME - * type. + * type. Ignored when zero data retention is enabled. */ hostedUrl?: boolean; @@ -5415,9 +5513,10 @@ export interface WebWebScrapeMdParams { /** * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ zdr?: 'enabled' | 'disabled'; } @@ -5583,9 +5682,10 @@ export interface WebWebScrapeSitemapParams { /** * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ zdr?: 'enabled' | 'disabled'; } diff --git a/tests/api-resources/ai.test.ts b/tests/api-resources/ai.test.ts index e87f6f3d..dc2492b4 100644 --- a/tests/api-resources/ai.test.ts +++ b/tests/api-resources/ai.test.ts @@ -27,6 +27,7 @@ describe('resource ai', () => { maxAgeMs: 0, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, + zdr: 'enabled', }); }); diff --git a/tests/api-resources/industry.test.ts b/tests/api-resources/industry.test.ts index e9907673..ed136672 100644 --- a/tests/api-resources/industry.test.ts +++ b/tests/api-resources/industry.test.ts @@ -28,6 +28,7 @@ describe('resource industry', () => { minResults: 1, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, + zdr: 'enabled', }); }); @@ -52,6 +53,7 @@ describe('resource industry', () => { tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, type: 'original_sic', + zdr: 'enabled', }); }); }); diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 9823adb7..8a12bf3d 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -30,6 +30,7 @@ describe('resource web', () => { mode: 'fast', tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, + zdr: 'enabled', }); }); @@ -81,6 +82,7 @@ describe('resource web', () => { tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, waitForMs: 0, + zdr: 'enabled', }); }); @@ -103,6 +105,7 @@ describe('resource web', () => { numCompetitors: 1, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, + zdr: 'enabled', }); }); @@ -159,6 +162,7 @@ describe('resource web', () => { maxAgeMs: 0, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1, behavior: 'fail' }, + zdr: 'enabled', }, { path: '/_stainless_unknown_path' }, ), @@ -244,6 +248,7 @@ describe('resource web', () => { queryFanout: true, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, + zdr: 'enabled', }); }); @@ -334,6 +339,7 @@ describe('resource web', () => { actions: [{ do: 'wait', timeMs: 0 }], country: 'de', excludeSelectors: ['x'], + extractRules: { foo: 'x' }, headers: { foo: 'J!' }, includeFrames: true, includeSelectors: ['x'], @@ -382,6 +388,7 @@ describe('resource web', () => { tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1, behavior: 'fail' }, waitForMs: 0, + zdr: 'enabled', }); }); From 9147c496af2bc72c4be185abe6dc01c91ca4fdf3 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 18 Sep 2026 05:30:10 +0000 Subject: [PATCH 052/232] feat(api): enable ZDR on remaining AI endpoints via OpenAI (#1099) Stainless-Generated-From: 14fabea8e3536ee170db274fdd08395bdfaad25a --- src/resources/ai.ts | 9 +++ src/resources/industry.ts | 18 ++++++ src/resources/parse.ts | 8 +-- src/resources/people.ts | 9 +++ src/resources/web.ts | 91 +++++++++++++++++++++++----- tests/api-resources/ai.test.ts | 1 + tests/api-resources/industry.test.ts | 2 + tests/api-resources/web.test.ts | 6 ++ 8 files changed, 124 insertions(+), 20 deletions(-) diff --git a/src/resources/ai.ts b/src/resources/ai.ts index 221a4d38..079505f4 100644 --- a/src/resources/ai.ts +++ b/src/resources/ai.ts @@ -461,6 +461,15 @@ export interface AIExtractProductParams { * timeoutOpts object. */ timeoutOpts?: AIExtractProductParams.TimeoutOpts; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace AIExtractProductParams { diff --git a/src/resources/industry.ts b/src/resources/industry.ts index 606460d7..3beac749 100644 --- a/src/resources/industry.ts +++ b/src/resources/industry.ts @@ -230,6 +230,15 @@ export interface IndustryRetrieveNaicsParams { * timeoutOpts object. */ timeoutOpts?: IndustryRetrieveNaicsParams.TimeoutOpts; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace IndustryRetrieveNaicsParams { @@ -291,6 +300,15 @@ export interface IndustryRetrieveSicParams { * published by the SEC. Defaults to `original_sic`. */ type?: 'original_sic' | 'latest_sec'; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace IndustryRetrieveSicParams { diff --git a/src/resources/parse.ts b/src/resources/parse.ts index 3448644e..cf7f74e7 100644 --- a/src/resources/parse.ts +++ b/src/resources/parse.ts @@ -259,10 +259,10 @@ export interface ParseHandleParams { /** * Query param: Set to enabled to bypass shared caches and omit request and - * response content from retained usage logs. Requires zero data retention to be - * enabled for your organization (contact support@context.dev), otherwise the - * request fails with ZDR_NOT_ENABLED. Successful ZDR responses include - * X-Context-ZDR: true. + * response content from retained usage logs. Asset uploads are skipped, so hosted + * image URLs are omitted. Requires zero data retention to be enabled for your + * organization (contact support@context.dev), otherwise the request fails with + * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. */ zdr?: 'enabled' | 'disabled'; } diff --git a/src/resources/people.ts b/src/resources/people.ts index 3c8bec28..9ebccb35 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -304,6 +304,15 @@ export interface PersonEnrichParams { * timeoutOpts object. */ timeoutOpts?: PersonEnrichParams.TimeoutOpts; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace PersonEnrichParams { diff --git a/src/resources/web.ts b/src/resources/web.ts index e61c7f10..d33aa9d7 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2701,6 +2701,15 @@ export interface WebAnswersParams { * timeoutOpts object. */ timeoutOpts?: WebAnswersParams.TimeoutOpts; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace WebAnswersParams { @@ -2829,6 +2838,15 @@ export interface WebExtractParams { * crawled page. */ waitForMs?: number; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace WebExtractParams { @@ -2943,6 +2961,15 @@ export interface WebExtractCompetitorsParams { * timeoutOpts object. */ timeoutOpts?: WebExtractCompetitorsParams.TimeoutOpts; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace WebExtractCompetitorsParams { @@ -3069,6 +3096,15 @@ export interface WebExtractStyleguideParams { * timeoutOpts object. */ timeoutOpts?: WebExtractStyleguideParams.TimeoutOpts; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace WebExtractStyleguideParams { @@ -3403,9 +3439,10 @@ export interface WebScreenshotParams { /** * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ zdr?: 'enabled' | 'disabled'; } @@ -3743,6 +3780,15 @@ export interface WebSearchParams { * timeoutOpts object. */ timeoutOpts?: WebSearchParams.TimeoutOpts; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace WebSearchParams { @@ -4500,9 +4546,10 @@ export interface WebWebScrapeBytesParams { /** * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ zdr?: 'enabled' | 'disabled'; } @@ -4840,9 +4887,10 @@ export interface WebWebScrapeHTMLParams { /** * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ zdr?: 'enabled' | 'disabled'; } @@ -5031,6 +5079,15 @@ export interface WebWebScrapeImagesParams { * shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; } export namespace WebWebScrapeImagesParams { @@ -5094,7 +5151,7 @@ export namespace WebWebScrapeImagesParams { /** * Host materializable images on the Brand.dev CDN and return their URL and MIME - * type. + * type. Ignored when zero data retention is enabled. */ hostedUrl?: boolean; @@ -5456,9 +5513,10 @@ export interface WebWebScrapeMdParams { /** * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ zdr?: 'enabled' | 'disabled'; } @@ -5624,9 +5682,10 @@ export interface WebWebScrapeSitemapParams { /** * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ zdr?: 'enabled' | 'disabled'; } diff --git a/tests/api-resources/ai.test.ts b/tests/api-resources/ai.test.ts index e87f6f3d..dc2492b4 100644 --- a/tests/api-resources/ai.test.ts +++ b/tests/api-resources/ai.test.ts @@ -27,6 +27,7 @@ describe('resource ai', () => { maxAgeMs: 0, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, + zdr: 'enabled', }); }); diff --git a/tests/api-resources/industry.test.ts b/tests/api-resources/industry.test.ts index e9907673..ed136672 100644 --- a/tests/api-resources/industry.test.ts +++ b/tests/api-resources/industry.test.ts @@ -28,6 +28,7 @@ describe('resource industry', () => { minResults: 1, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, + zdr: 'enabled', }); }); @@ -52,6 +53,7 @@ describe('resource industry', () => { tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, type: 'original_sic', + zdr: 'enabled', }); }); }); diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 702808f3..8a12bf3d 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -30,6 +30,7 @@ describe('resource web', () => { mode: 'fast', tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, + zdr: 'enabled', }); }); @@ -81,6 +82,7 @@ describe('resource web', () => { tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, waitForMs: 0, + zdr: 'enabled', }); }); @@ -103,6 +105,7 @@ describe('resource web', () => { numCompetitors: 1, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, + zdr: 'enabled', }); }); @@ -159,6 +162,7 @@ describe('resource web', () => { maxAgeMs: 0, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1, behavior: 'fail' }, + zdr: 'enabled', }, { path: '/_stainless_unknown_path' }, ), @@ -244,6 +248,7 @@ describe('resource web', () => { queryFanout: true, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, + zdr: 'enabled', }); }); @@ -383,6 +388,7 @@ describe('resource web', () => { tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1, behavior: 'fail' }, waitForMs: 0, + zdr: 'enabled', }); }); From 672cbbb426eb41aee95ccc1dfb46f70a73defd8a Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 18 Sep 2026 06:41:35 +0000 Subject: [PATCH 053/232] seal --- .stats.yml | 2 +- api.md | 2 + src/client.ts | 4 + src/resources/index.ts | 2 + src/resources/web.ts | 443 ++++++++++++++++++++++++++++++++ tests/api-resources/web.test.ts | 31 +++ 6 files changed, 483 insertions(+), 1 deletion(-) diff --git a/.stats.yml b/.stats.yml index 85f79b6a..4e6a016a 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 49 +configured_endpoints: 50 diff --git a/api.md b/api.md index 285cb482..bce5b1ab 100644 --- a/api.md +++ b/api.md @@ -24,6 +24,7 @@ Types: - WebWebScrapeHTMLResponse - WebWebScrapeImagesResponse - WebWebScrapeMdResponse +- WebWebScrapeScreenshotResponse - WebWebScrapeSitemapResponse Methods: @@ -40,6 +41,7 @@ Methods: - client.web.webScrapeHTML({ ...params }) -> WebWebScrapeHTMLResponse - client.web.webScrapeImages({ ...params }) -> WebWebScrapeImagesResponse - client.web.webScrapeMd({ ...params }) -> WebWebScrapeMdResponse +- client.web.webScrapeScreenshot({ ...params }) -> WebWebScrapeScreenshotResponse - client.web.webScrapeSitemap({ ...params }) -> WebWebScrapeSitemapResponse # AI diff --git a/src/client.ts b/src/client.ts index 35611ddf..9b06ee2c 100644 --- a/src/client.ts +++ b/src/client.ts @@ -112,6 +112,8 @@ import { WebWebScrapeImagesResponse, WebWebScrapeMdParams, WebWebScrapeMdResponse, + WebWebScrapeScreenshotParams, + WebWebScrapeScreenshotResponse, WebWebScrapeSitemapParams, WebWebScrapeSitemapResponse, } from './resources/web'; @@ -895,6 +897,7 @@ export declare namespace ContextDev { type WebWebScrapeHTMLResponse as WebWebScrapeHTMLResponse, type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, type WebWebScrapeMdResponse as WebWebScrapeMdResponse, + type WebWebScrapeScreenshotResponse as WebWebScrapeScreenshotResponse, type WebWebScrapeSitemapResponse as WebWebScrapeSitemapResponse, type WebAnswersParams as WebAnswersParams, type WebExtractParams as WebExtractParams, @@ -908,6 +911,7 @@ export declare namespace ContextDev { type WebWebScrapeHTMLParams as WebWebScrapeHTMLParams, type WebWebScrapeImagesParams as WebWebScrapeImagesParams, type WebWebScrapeMdParams as WebWebScrapeMdParams, + type WebWebScrapeScreenshotParams as WebWebScrapeScreenshotParams, type WebWebScrapeSitemapParams as WebWebScrapeSitemapParams, }; diff --git a/src/resources/index.ts b/src/resources/index.ts index 47b621a2..abb56d4c 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -83,6 +83,7 @@ export { type WebWebScrapeHTMLResponse, type WebWebScrapeImagesResponse, type WebWebScrapeMdResponse, + type WebWebScrapeScreenshotResponse, type WebWebScrapeSitemapResponse, type WebAnswersParams, type WebExtractParams, @@ -96,6 +97,7 @@ export { type WebWebScrapeHTMLParams, type WebWebScrapeImagesParams, type WebWebScrapeMdParams, + type WebWebScrapeScreenshotParams, type WebWebScrapeSitemapParams, } from './web'; export { Webhooks, type RetryConfig } from './webhooks/webhooks'; diff --git a/src/resources/web.ts b/src/resources/web.ts index d33aa9d7..951dd672 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -256,6 +256,28 @@ export class Web extends APIResource { return this._client.get('/web/scrape/markdown', { query, ...options }); } + /** + * Capture the given HTTP or HTTPS URL with configurable viewport, full-page + * capture, wait time, popup handling, theme, scroll offset, cache age, country, + * and request timeout. Defaults to a 1920x1080 viewport, a 3-second wait, and a + * cache age of 1 day. With timeoutOpts.behavior=return-partial, a screenshot of + * the page rendered so far may be returned; inspect finalDOMState to identify an + * incomplete render. Successful requests cost 1 credit; errors are not billed. + * + * @example + * ```ts + * const response = await client.web.webScrapeScreenshot({ + * url: 'https://example.com', + * }); + * ``` + */ + webScrapeScreenshot( + query: WebWebScrapeScreenshotParams, + options?: RequestOptions, + ): APIPromise { + return this._client.get('/web/scrape/screenshot', { query, ...options }); + } + /** * Crawl an entire website's sitemap and return all discovered page URLs. Set * `includeSubdomains=true` to also discover public pages and sitemaps on child @@ -2584,6 +2606,91 @@ export namespace WebWebScrapeMdResponse { } } +export interface WebWebScrapeScreenshotResponse { + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + cache_metadata: WebWebScrapeScreenshotResponse.CacheMetadata; + + /** + * Height of the returned image in pixels. + */ + height: number; + + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + + /** + * Public image URL for standard requests, or an in-memory data URL when ZDR is + * enabled. + */ + screenshot: string; + + /** + * The requested page URL. + */ + url: string; + + /** + * Width of the returned image in pixels. + */ + width: number; + + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState?: 'loaded' | 'still-loading'; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: WebWebScrapeScreenshotResponse.KeyMetadata; +} + +export namespace WebWebScrapeScreenshotResponse { + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + export interface CacheMetadata { + /** + * Age of the cached data in milliseconds. Zero for miss and zdr responses. + */ + age_ms: number; + + /** + * Whether the response was served from cache, required fresh work, or honored + * zero-data-retention cache bypass. + */ + status: 'hit' | 'miss' | 'zdr'; + } + + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + export interface WebWebScrapeSitemapResponse { /** * The normalized domain that was crawled @@ -5623,6 +5730,340 @@ export namespace WebWebScrapeMdParams { } } +export interface WebWebScrapeScreenshotParams { + url: string; + + /** + * Optional parameter for comprehensive popup cleanup. If 'true', the browser + * dismisses detected cookie/consent UI and clears other detected obstructive + * popups and overlays before capture. If 'false' or not provided, this parameter + * requests no cleanup; handleCookiePopup can still request cookie/consent handling + * independently. + */ + clearPopups?: boolean; + + /** + * Optional parameter to choose the site's visual theme in the screenshot. Use + * 'light' or 'dark' when the site offers both appearances. + */ + colorScheme?: 'light' | 'dark'; + + /** + * Fetch the target page through a residential proxy in this country (ISO 3166-1 + * alpha-2). + */ + country?: + | 'ad' + | 'ae' + | 'af' + | 'ag' + | 'ai' + | 'al' + | 'am' + | 'ao' + | 'ar' + | 'at' + | 'au' + | 'aw' + | 'az' + | 'ba' + | 'bb' + | 'bd' + | 'be' + | 'bf' + | 'bg' + | 'bh' + | 'bi' + | 'bj' + | 'bm' + | 'bn' + | 'bo' + | 'bq' + | 'br' + | 'bs' + | 'bw' + | 'by' + | 'bz' + | 'ca' + | 'cd' + | 'cf' + | 'cg' + | 'ch' + | 'ci' + | 'cl' + | 'cm' + | 'cn' + | 'co' + | 'cr' + | 'cv' + | 'cw' + | 'cy' + | 'cz' + | 'de' + | 'dj' + | 'dk' + | 'dm' + | 'do' + | 'dz' + | 'ec' + | 'ee' + | 'eg' + | 'es' + | 'et' + | 'fi' + | 'fj' + | 'fr' + | 'ga' + | 'gb' + | 'gd' + | 'ge' + | 'gf' + | 'gg' + | 'gh' + | 'gm' + | 'gn' + | 'gp' + | 'gq' + | 'gr' + | 'gt' + | 'gu' + | 'gw' + | 'gy' + | 'hk' + | 'hn' + | 'hr' + | 'ht' + | 'hu' + | 'id' + | 'ie' + | 'il' + | 'im' + | 'in' + | 'iq' + | 'ir' + | 'is' + | 'it' + | 'je' + | 'jm' + | 'jo' + | 'jp' + | 'ke' + | 'kg' + | 'kh' + | 'kn' + | 'kr' + | 'kw' + | 'ky' + | 'kz' + | 'la' + | 'lb' + | 'lc' + | 'lk' + | 'lr' + | 'ls' + | 'lt' + | 'lu' + | 'lv' + | 'ly' + | 'ma' + | 'mc' + | 'md' + | 'me' + | 'mf' + | 'mg' + | 'mk' + | 'ml' + | 'mm' + | 'mn' + | 'mo' + | 'mq' + | 'mr' + | 'mt' + | 'mu' + | 'mv' + | 'mw' + | 'mx' + | 'my' + | 'mz' + | 'na' + | 'nc' + | 'ne' + | 'ng' + | 'ni' + | 'nl' + | 'no' + | 'np' + | 'nz' + | 'om' + | 'pa' + | 'pe' + | 'pf' + | 'pg' + | 'ph' + | 'pk' + | 'pl' + | 'pr' + | 'ps' + | 'pt' + | 'py' + | 'qa' + | 're' + | 'ro' + | 'rs' + | 'ru' + | 'rw' + | 'sa' + | 'sc' + | 'sd' + | 'se' + | 'sg' + | 'si' + | 'sk' + | 'sl' + | 'sm' + | 'sn' + | 'so' + | 'sr' + | 'ss' + | 'st' + | 'sv' + | 'sx' + | 'sy' + | 'sz' + | 'tc' + | 'td' + | 'tg' + | 'th' + | 'tj' + | 'tl' + | 'tm' + | 'tn' + | 'tr' + | 'tt' + | 'tw' + | 'tz' + | 'ua' + | 'ug' + | 'us' + | 'uy' + | 'uz' + | 'vc' + | 've' + | 'vg' + | 'vi' + | 'vn' + | 'ye' + | 'yt' + | 'za' + | 'zm' + | 'zw'; + + /** + * Optional parameter to determine screenshot type. If 'true', takes a full page + * screenshot capturing all content. If 'false' or not provided, takes a viewport + * screenshot (standard browser view). + */ + fullScreenshot?: 'true' | 'false'; + + /** + * Optional parameter to control cookie/consent popup handling. If 'true', we + * dismiss cookie banner before capture. If 'false' or not provided, captures the + * page without that step. + */ + handleCookiePopup?: boolean; + + /** + * Return a cached screenshot if a prior screenshot for the same parameters exists + * and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when + * omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh. + */ + maxAgeMs?: number | null; + + /** + * Optional vertical scroll offset in pixels for capturing a long page in + * viewport-sized chunks. When provided, the full page is captured once and the + * returned image is the viewport-sized slice that begins at this Y offset (e.g. + * request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page + * top to bottom). The final slice may be shorter than the viewport height. Takes + * precedence over fullScreenshot. Max: 100000. + */ + scrollOffset?: number | null; + + /** + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. + */ + tags?: Array; + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: WebWebScrapeScreenshotParams.TimeoutOpts; + + /** + * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. + */ + viewport?: WebWebScrapeScreenshotParams.Viewport; + + /** + * Optional browser wait time in milliseconds after initial page load before taking + * the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when + * omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at + * least waitForMs + 10000 ms; a shorter deadline is rejected with 400 + * TIMEOUT_TOO_SHORT_FOR_WAIT. + */ + waitForMs?: number | null; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; +} + +export namespace WebWebScrapeScreenshotParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 5000. + */ + behavior?: 'fail' | 'return-partial'; + } + + /** + * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. + */ + export interface Viewport { + /** + * Viewport height in pixels. + */ + height?: number; + + /** + * Viewport width in pixels. + */ + width?: number; + } +} + export interface WebWebScrapeSitemapParams { /** * Domain to build a sitemap for @@ -5726,6 +6167,7 @@ export declare namespace Web { type WebWebScrapeHTMLResponse as WebWebScrapeHTMLResponse, type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, type WebWebScrapeMdResponse as WebWebScrapeMdResponse, + type WebWebScrapeScreenshotResponse as WebWebScrapeScreenshotResponse, type WebWebScrapeSitemapResponse as WebWebScrapeSitemapResponse, type WebAnswersParams as WebAnswersParams, type WebExtractParams as WebExtractParams, @@ -5739,6 +6181,7 @@ export declare namespace Web { type WebWebScrapeHTMLParams as WebWebScrapeHTMLParams, type WebWebScrapeImagesParams as WebWebScrapeImagesParams, type WebWebScrapeMdParams as WebWebScrapeMdParams, + type WebWebScrapeScreenshotParams as WebWebScrapeScreenshotParams, type WebWebScrapeSitemapParams as WebWebScrapeSitemapParams, }; } diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 8a12bf3d..fb6345a3 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -434,6 +434,37 @@ describe('resource web', () => { }); }); + // Mock server tests are disabled + test.skip('webScrapeScreenshot: only required params', async () => { + const responsePromise = client.web.webScrapeScreenshot({ url: 'https://example.com' }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('webScrapeScreenshot: required and optional params', async () => { + const response = await client.web.webScrapeScreenshot({ + url: 'https://example.com', + clearPopups: true, + colorScheme: 'light', + country: 'de', + fullScreenshot: 'true', + handleCookiePopup: true, + maxAgeMs: 0, + scrollOffset: 0, + tags: ['production', 'team-alpha'], + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, + viewport: { height: 240, width: 240 }, + waitForMs: 0, + zdr: 'enabled', + }); + }); + // Mock server tests are disabled test.skip('webScrapeSitemap: only required params', async () => { const responsePromise = client.web.webScrapeSitemap({ domain: 'xxx' }); From 6c7cd7998646feca5d8bdecee63e35c9383de7d8 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 18 Sep 2026 06:41:36 +0000 Subject: [PATCH 054/232] feat(web): add URL-based scrape screenshot endpoint (#1150) Stainless-Generated-From: 672cbbb426eb41aee95ccc1dfb46f70a73defd8a --- .stats.yml | 2 +- api.md | 2 + src/client.ts | 4 + src/resources/index.ts | 2 + src/resources/web.ts | 443 ++++++++++++++++++++++++++++++++ tests/api-resources/web.test.ts | 31 +++ 6 files changed, 483 insertions(+), 1 deletion(-) diff --git a/.stats.yml b/.stats.yml index 85f79b6a..4e6a016a 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 49 +configured_endpoints: 50 diff --git a/api.md b/api.md index 285cb482..bce5b1ab 100644 --- a/api.md +++ b/api.md @@ -24,6 +24,7 @@ Types: - WebWebScrapeHTMLResponse - WebWebScrapeImagesResponse - WebWebScrapeMdResponse +- WebWebScrapeScreenshotResponse - WebWebScrapeSitemapResponse Methods: @@ -40,6 +41,7 @@ Methods: - client.web.webScrapeHTML({ ...params }) -> WebWebScrapeHTMLResponse - client.web.webScrapeImages({ ...params }) -> WebWebScrapeImagesResponse - client.web.webScrapeMd({ ...params }) -> WebWebScrapeMdResponse +- client.web.webScrapeScreenshot({ ...params }) -> WebWebScrapeScreenshotResponse - client.web.webScrapeSitemap({ ...params }) -> WebWebScrapeSitemapResponse # AI diff --git a/src/client.ts b/src/client.ts index 35611ddf..9b06ee2c 100644 --- a/src/client.ts +++ b/src/client.ts @@ -112,6 +112,8 @@ import { WebWebScrapeImagesResponse, WebWebScrapeMdParams, WebWebScrapeMdResponse, + WebWebScrapeScreenshotParams, + WebWebScrapeScreenshotResponse, WebWebScrapeSitemapParams, WebWebScrapeSitemapResponse, } from './resources/web'; @@ -895,6 +897,7 @@ export declare namespace ContextDev { type WebWebScrapeHTMLResponse as WebWebScrapeHTMLResponse, type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, type WebWebScrapeMdResponse as WebWebScrapeMdResponse, + type WebWebScrapeScreenshotResponse as WebWebScrapeScreenshotResponse, type WebWebScrapeSitemapResponse as WebWebScrapeSitemapResponse, type WebAnswersParams as WebAnswersParams, type WebExtractParams as WebExtractParams, @@ -908,6 +911,7 @@ export declare namespace ContextDev { type WebWebScrapeHTMLParams as WebWebScrapeHTMLParams, type WebWebScrapeImagesParams as WebWebScrapeImagesParams, type WebWebScrapeMdParams as WebWebScrapeMdParams, + type WebWebScrapeScreenshotParams as WebWebScrapeScreenshotParams, type WebWebScrapeSitemapParams as WebWebScrapeSitemapParams, }; diff --git a/src/resources/index.ts b/src/resources/index.ts index 47b621a2..abb56d4c 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -83,6 +83,7 @@ export { type WebWebScrapeHTMLResponse, type WebWebScrapeImagesResponse, type WebWebScrapeMdResponse, + type WebWebScrapeScreenshotResponse, type WebWebScrapeSitemapResponse, type WebAnswersParams, type WebExtractParams, @@ -96,6 +97,7 @@ export { type WebWebScrapeHTMLParams, type WebWebScrapeImagesParams, type WebWebScrapeMdParams, + type WebWebScrapeScreenshotParams, type WebWebScrapeSitemapParams, } from './web'; export { Webhooks, type RetryConfig } from './webhooks/webhooks'; diff --git a/src/resources/web.ts b/src/resources/web.ts index d33aa9d7..951dd672 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -256,6 +256,28 @@ export class Web extends APIResource { return this._client.get('/web/scrape/markdown', { query, ...options }); } + /** + * Capture the given HTTP or HTTPS URL with configurable viewport, full-page + * capture, wait time, popup handling, theme, scroll offset, cache age, country, + * and request timeout. Defaults to a 1920x1080 viewport, a 3-second wait, and a + * cache age of 1 day. With timeoutOpts.behavior=return-partial, a screenshot of + * the page rendered so far may be returned; inspect finalDOMState to identify an + * incomplete render. Successful requests cost 1 credit; errors are not billed. + * + * @example + * ```ts + * const response = await client.web.webScrapeScreenshot({ + * url: 'https://example.com', + * }); + * ``` + */ + webScrapeScreenshot( + query: WebWebScrapeScreenshotParams, + options?: RequestOptions, + ): APIPromise { + return this._client.get('/web/scrape/screenshot', { query, ...options }); + } + /** * Crawl an entire website's sitemap and return all discovered page URLs. Set * `includeSubdomains=true` to also discover public pages and sitemaps on child @@ -2584,6 +2606,91 @@ export namespace WebWebScrapeMdResponse { } } +export interface WebWebScrapeScreenshotResponse { + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + cache_metadata: WebWebScrapeScreenshotResponse.CacheMetadata; + + /** + * Height of the returned image in pixels. + */ + height: number; + + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + + /** + * Public image URL for standard requests, or an in-memory data URL when ZDR is + * enabled. + */ + screenshot: string; + + /** + * The requested page URL. + */ + url: string; + + /** + * Width of the returned image in pixels. + */ + width: number; + + /** + * How complete the returned content is. `loaded` means the page finished the waits + * the request asked for. `still-loading` only occurs with + * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was + * reached first, so the content reflects the DOM at that moment and late-rendering + * parts may be missing. Partial results are billed at the base request cost. + */ + finalDOMState?: 'loaded' | 'still-loading'; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: WebWebScrapeScreenshotResponse.KeyMetadata; +} + +export namespace WebWebScrapeScreenshotResponse { + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + export interface CacheMetadata { + /** + * Age of the cached data in milliseconds. Zero for miss and zdr responses. + */ + age_ms: number; + + /** + * Whether the response was served from cache, required fresh work, or honored + * zero-data-retention cache bypass. + */ + status: 'hit' | 'miss' | 'zdr'; + } + + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + export interface WebWebScrapeSitemapResponse { /** * The normalized domain that was crawled @@ -5623,6 +5730,340 @@ export namespace WebWebScrapeMdParams { } } +export interface WebWebScrapeScreenshotParams { + url: string; + + /** + * Optional parameter for comprehensive popup cleanup. If 'true', the browser + * dismisses detected cookie/consent UI and clears other detected obstructive + * popups and overlays before capture. If 'false' or not provided, this parameter + * requests no cleanup; handleCookiePopup can still request cookie/consent handling + * independently. + */ + clearPopups?: boolean; + + /** + * Optional parameter to choose the site's visual theme in the screenshot. Use + * 'light' or 'dark' when the site offers both appearances. + */ + colorScheme?: 'light' | 'dark'; + + /** + * Fetch the target page through a residential proxy in this country (ISO 3166-1 + * alpha-2). + */ + country?: + | 'ad' + | 'ae' + | 'af' + | 'ag' + | 'ai' + | 'al' + | 'am' + | 'ao' + | 'ar' + | 'at' + | 'au' + | 'aw' + | 'az' + | 'ba' + | 'bb' + | 'bd' + | 'be' + | 'bf' + | 'bg' + | 'bh' + | 'bi' + | 'bj' + | 'bm' + | 'bn' + | 'bo' + | 'bq' + | 'br' + | 'bs' + | 'bw' + | 'by' + | 'bz' + | 'ca' + | 'cd' + | 'cf' + | 'cg' + | 'ch' + | 'ci' + | 'cl' + | 'cm' + | 'cn' + | 'co' + | 'cr' + | 'cv' + | 'cw' + | 'cy' + | 'cz' + | 'de' + | 'dj' + | 'dk' + | 'dm' + | 'do' + | 'dz' + | 'ec' + | 'ee' + | 'eg' + | 'es' + | 'et' + | 'fi' + | 'fj' + | 'fr' + | 'ga' + | 'gb' + | 'gd' + | 'ge' + | 'gf' + | 'gg' + | 'gh' + | 'gm' + | 'gn' + | 'gp' + | 'gq' + | 'gr' + | 'gt' + | 'gu' + | 'gw' + | 'gy' + | 'hk' + | 'hn' + | 'hr' + | 'ht' + | 'hu' + | 'id' + | 'ie' + | 'il' + | 'im' + | 'in' + | 'iq' + | 'ir' + | 'is' + | 'it' + | 'je' + | 'jm' + | 'jo' + | 'jp' + | 'ke' + | 'kg' + | 'kh' + | 'kn' + | 'kr' + | 'kw' + | 'ky' + | 'kz' + | 'la' + | 'lb' + | 'lc' + | 'lk' + | 'lr' + | 'ls' + | 'lt' + | 'lu' + | 'lv' + | 'ly' + | 'ma' + | 'mc' + | 'md' + | 'me' + | 'mf' + | 'mg' + | 'mk' + | 'ml' + | 'mm' + | 'mn' + | 'mo' + | 'mq' + | 'mr' + | 'mt' + | 'mu' + | 'mv' + | 'mw' + | 'mx' + | 'my' + | 'mz' + | 'na' + | 'nc' + | 'ne' + | 'ng' + | 'ni' + | 'nl' + | 'no' + | 'np' + | 'nz' + | 'om' + | 'pa' + | 'pe' + | 'pf' + | 'pg' + | 'ph' + | 'pk' + | 'pl' + | 'pr' + | 'ps' + | 'pt' + | 'py' + | 'qa' + | 're' + | 'ro' + | 'rs' + | 'ru' + | 'rw' + | 'sa' + | 'sc' + | 'sd' + | 'se' + | 'sg' + | 'si' + | 'sk' + | 'sl' + | 'sm' + | 'sn' + | 'so' + | 'sr' + | 'ss' + | 'st' + | 'sv' + | 'sx' + | 'sy' + | 'sz' + | 'tc' + | 'td' + | 'tg' + | 'th' + | 'tj' + | 'tl' + | 'tm' + | 'tn' + | 'tr' + | 'tt' + | 'tw' + | 'tz' + | 'ua' + | 'ug' + | 'us' + | 'uy' + | 'uz' + | 'vc' + | 've' + | 'vg' + | 'vi' + | 'vn' + | 'ye' + | 'yt' + | 'za' + | 'zm' + | 'zw'; + + /** + * Optional parameter to determine screenshot type. If 'true', takes a full page + * screenshot capturing all content. If 'false' or not provided, takes a viewport + * screenshot (standard browser view). + */ + fullScreenshot?: 'true' | 'false'; + + /** + * Optional parameter to control cookie/consent popup handling. If 'true', we + * dismiss cookie banner before capture. If 'false' or not provided, captures the + * page without that step. + */ + handleCookiePopup?: boolean; + + /** + * Return a cached screenshot if a prior screenshot for the same parameters exists + * and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when + * omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh. + */ + maxAgeMs?: number | null; + + /** + * Optional vertical scroll offset in pixels for capturing a long page in + * viewport-sized chunks. When provided, the full page is captured once and the + * returned image is the viewport-sized slice that begins at this Y offset (e.g. + * request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page + * top to bottom). The final slice may be shorter than the viewport height. Takes + * precedence over fullScreenshot. Max: 100000. + */ + scrollOffset?: number | null; + + /** + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. + */ + tags?: Array; + + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: WebWebScrapeScreenshotParams.TimeoutOpts; + + /** + * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. + */ + viewport?: WebWebScrapeScreenshotParams.Viewport; + + /** + * Optional browser wait time in milliseconds after initial page load before taking + * the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when + * omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at + * least waitForMs + 10000 ms; a shorter deadline is rejected with 400 + * TIMEOUT_TOO_SHORT_FOR_WAIT. + */ + waitForMs?: number | null; + + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; +} + +export namespace WebWebScrapeScreenshotParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 5000. + */ + behavior?: 'fail' | 'return-partial'; + } + + /** + * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. + */ + export interface Viewport { + /** + * Viewport height in pixels. + */ + height?: number; + + /** + * Viewport width in pixels. + */ + width?: number; + } +} + export interface WebWebScrapeSitemapParams { /** * Domain to build a sitemap for @@ -5726,6 +6167,7 @@ export declare namespace Web { type WebWebScrapeHTMLResponse as WebWebScrapeHTMLResponse, type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, type WebWebScrapeMdResponse as WebWebScrapeMdResponse, + type WebWebScrapeScreenshotResponse as WebWebScrapeScreenshotResponse, type WebWebScrapeSitemapResponse as WebWebScrapeSitemapResponse, type WebAnswersParams as WebAnswersParams, type WebExtractParams as WebExtractParams, @@ -5739,6 +6181,7 @@ export declare namespace Web { type WebWebScrapeHTMLParams as WebWebScrapeHTMLParams, type WebWebScrapeImagesParams as WebWebScrapeImagesParams, type WebWebScrapeMdParams as WebWebScrapeMdParams, + type WebWebScrapeScreenshotParams as WebWebScrapeScreenshotParams, type WebWebScrapeSitemapParams as WebWebScrapeSitemapParams, }; } diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 8a12bf3d..fb6345a3 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -434,6 +434,37 @@ describe('resource web', () => { }); }); + // Mock server tests are disabled + test.skip('webScrapeScreenshot: only required params', async () => { + const responsePromise = client.web.webScrapeScreenshot({ url: 'https://example.com' }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('webScrapeScreenshot: required and optional params', async () => { + const response = await client.web.webScrapeScreenshot({ + url: 'https://example.com', + clearPopups: true, + colorScheme: 'light', + country: 'de', + fullScreenshot: 'true', + handleCookiePopup: true, + maxAgeMs: 0, + scrollOffset: 0, + tags: ['production', 'team-alpha'], + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, + viewport: { height: 240, width: 240 }, + waitForMs: 0, + zdr: 'enabled', + }); + }); + // Mock server tests are disabled test.skip('webScrapeSitemap: only required params', async () => { const responsePromise = client.web.webScrapeSitemap({ domain: 'xxx' }); From 13b190b1f8fc7a69601f197aa203f75a079519d3 Mon Sep 17 00:00:00 2001 From: contextualbeer Date: Fri, 18 Sep 2026 08:42:54 +0200 Subject: [PATCH 055/232] release: 2.19.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 15 +++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 18 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 4edefb29..89652a35 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.18.1" + ".": "2.19.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index de7e87a9..b4aea89b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,20 @@ # Changelog +## [2.19.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.18.1...v2.19.0) (2026-09-18) + + +### Features + +* **api:** enable ZDR on remaining AI endpoints via OpenAI ([#1099](https://github.com/context-dot-dev/context-typescript-sdk/issues/1099)) ([9147c49](https://github.com/context-dot-dev/context-typescript-sdk/commit/9147c496af2bc72c4be185abe6dc01c91ca4fdf3)) +* **products:** extract ProductGroup variants with images ([#1124](https://github.com/context-dot-dev/context-typescript-sdk/issues/1124)) ([9a80da2](https://github.com/context-dot-dev/context-typescript-sdk/commit/9a80da2aed02602d5ef7ab2bff03eff440753680)) +* **scrape:** add CSS extraction rules to HTML scraping ([#1146](https://github.com/context-dot-dev/context-typescript-sdk/issues/1146)) ([c5235fc](https://github.com/context-dot-dev/context-typescript-sdk/commit/c5235fc82b2d2abff938d25175aa6d1152d0f867)) +* **web:** add URL-based scrape screenshot endpoint ([#1150](https://github.com/context-dot-dev/context-typescript-sdk/issues/1150)) ([6c7cd79](https://github.com/context-dot-dev/context-typescript-sdk/commit/6c7cd7998646feca5d8bdecee63e35c9383de7d8)) + + +### Bug Fixes + +* **api:** lower partial scrape timeout minimum to five seconds ([#1118](https://github.com/context-dot-dev/context-typescript-sdk/issues/1118)) ([2baeba3](https://github.com/context-dot-dev/context-typescript-sdk/commit/2baeba3bf88170a1e6c6c877d2a4758392202f01)) + ## [2.18.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.18.0...v2.18.1) (2026-09-15) diff --git a/package.json b/package.json index f1cfe3c3..062de50a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.18.1", + "version": "2.19.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 3c2f391b..3f68f782 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.18.1'; // x-release-please-version +export const VERSION = '2.19.0'; // x-release-please-version From b0a4aa52533b83f905218d84976494c1dd931d1e Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 18 Sep 2026 08:01:47 +0000 Subject: [PATCH 056/232] feat(billing): charge for 404s and skip fraud accounting (#1152) Stainless-Generated-From: 386d27a8d250e8213bf7074e4a30942d53111e74 --- src/resources/web.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 951dd672..b6aa5784 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -238,7 +238,7 @@ export class Web extends APIResource { * | 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing. A partial result (`finalDOMState: "still-loading"`, only with timeoutOpts.behavior=return-partial) is billed at the base 1 credit with no OCR or actions surcharge | * | 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds | * | 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code | - * | 404 | No | Target page returned or fingerprinted as not found | + * | 404 | Yes — 1 credit, or 2 credits with actions | Target page returned or fingerprinted as not found | * | 408 | No | Request timed out. With timeoutOpts.behavior=return-partial this only happens when nothing usable had rendered by the deadline | * | 413 | No | Target content exceeds the maximum supported size (20 MB) | * | 415 | No | Unsupported content type | From 386d27a8d250e8213bf7074e4a30942d53111e74 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 18 Sep 2026 08:01:47 +0000 Subject: [PATCH 057/232] seal --- .release-please-manifest.json | 2 +- CHANGELOG.md | 15 +++++++++++++++ package.json | 2 +- src/resources/web.ts | 2 +- src/version.ts | 2 +- 5 files changed, 19 insertions(+), 4 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 4edefb29..89652a35 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.18.1" + ".": "2.19.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index de7e87a9..b4aea89b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,20 @@ # Changelog +## [2.19.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.18.1...v2.19.0) (2026-09-18) + + +### Features + +* **api:** enable ZDR on remaining AI endpoints via OpenAI ([#1099](https://github.com/context-dot-dev/context-typescript-sdk/issues/1099)) ([9147c49](https://github.com/context-dot-dev/context-typescript-sdk/commit/9147c496af2bc72c4be185abe6dc01c91ca4fdf3)) +* **products:** extract ProductGroup variants with images ([#1124](https://github.com/context-dot-dev/context-typescript-sdk/issues/1124)) ([9a80da2](https://github.com/context-dot-dev/context-typescript-sdk/commit/9a80da2aed02602d5ef7ab2bff03eff440753680)) +* **scrape:** add CSS extraction rules to HTML scraping ([#1146](https://github.com/context-dot-dev/context-typescript-sdk/issues/1146)) ([c5235fc](https://github.com/context-dot-dev/context-typescript-sdk/commit/c5235fc82b2d2abff938d25175aa6d1152d0f867)) +* **web:** add URL-based scrape screenshot endpoint ([#1150](https://github.com/context-dot-dev/context-typescript-sdk/issues/1150)) ([6c7cd79](https://github.com/context-dot-dev/context-typescript-sdk/commit/6c7cd7998646feca5d8bdecee63e35c9383de7d8)) + + +### Bug Fixes + +* **api:** lower partial scrape timeout minimum to five seconds ([#1118](https://github.com/context-dot-dev/context-typescript-sdk/issues/1118)) ([2baeba3](https://github.com/context-dot-dev/context-typescript-sdk/commit/2baeba3bf88170a1e6c6c877d2a4758392202f01)) + ## [2.18.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.18.0...v2.18.1) (2026-09-15) diff --git a/package.json b/package.json index f1cfe3c3..062de50a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.18.1", + "version": "2.19.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/resources/web.ts b/src/resources/web.ts index 951dd672..b6aa5784 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -238,7 +238,7 @@ export class Web extends APIResource { * | 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing. A partial result (`finalDOMState: "still-loading"`, only with timeoutOpts.behavior=return-partial) is billed at the base 1 credit with no OCR or actions surcharge | * | 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds | * | 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code | - * | 404 | No | Target page returned or fingerprinted as not found | + * | 404 | Yes — 1 credit, or 2 credits with actions | Target page returned or fingerprinted as not found | * | 408 | No | Request timed out. With timeoutOpts.behavior=return-partial this only happens when nothing usable had rendered by the deadline | * | 413 | No | Target content exceeds the maximum supported size (20 MB) | * | 415 | No | Unsupported content type | diff --git a/src/version.ts b/src/version.ts index 3c2f391b..3f68f782 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.18.1'; // x-release-please-version +export const VERSION = '2.19.0'; // x-release-please-version From 47c18a0b11c00a6f697abb99a2e79795736d3143 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 21 Sep 2026 03:24:10 +0000 Subject: [PATCH 058/232] feat(scrape): support waitForMs for byte downloads (#1170) Stainless-Generated-From: 2809c973408388b20acc58cc939676175f7932da --- src/resources/web.ts | 20 ++++++++++++++++---- tests/api-resources/web.test.ts | 1 + 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index b6aa5784..8cef1df5 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -142,10 +142,12 @@ export class Web extends APIResource { } /** - * Downloads a resource and returns its bytes as base64. Supports images, PDFs, - * HTML pages, and any other content type without image conversion, text - * extraction, or character-encoding changes. HTTP compression is decoded before - * base64 encoding. HTML is the original HTTP response; JavaScript is not rendered. + * Downloads a resource and returns its bytes as base64. Without waitForMs, returns + * the original HTTP response without image conversion, text extraction, or + * character-encoding changes. HTTP compression is decoded before base64 encoding. + * Supply waitForMs to render HTML with JavaScript in the browser and return the + * resulting HTML as UTF-8 bytes after the wait. Non-HTML resources, including + * images and PDFs, keep their original bytes and do not incur a browser wait. * Follows public redirects and retries failed downloads through ISP and * residential proxies, with a direct fallback. When country is specified, only a * residential proxy in that country is used. Supply headers such as Referer for @@ -4651,6 +4653,16 @@ export interface WebWebScrapeBytesParams { */ timeoutOpts?: WebWebScrapeBytesParams.TimeoutOpts; + /** + * Optional browser wait time after initial page load, in milliseconds (0–30000; 0 + * uses 500). When supplied, HTML is rendered with JavaScript and returned as UTF-8 + * bytes. Other resources keep their original bytes without a browser wait. Omit to + * download the original HTTP response. When combined with timeoutOpts, + * timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter + * deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. + */ + waitForMs?: number | null; + /** * Set to enabled to bypass shared caches and omit request and response content * from retained usage logs. Asset uploads are skipped, so hosted image URLs are diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index fb6345a3..b8f9a2a3 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -316,6 +316,7 @@ describe('resource web', () => { headers: { foo: 'J!' }, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1, behavior: 'fail' }, + waitForMs: 0, zdr: 'enabled', }); }); From bacbc64bb21b56f6c87926729af62731e1cd3e84 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 21 Sep 2026 03:34:15 +0000 Subject: [PATCH 059/232] feat(scrape): support custom screenshot headers (#1169) Stainless-Generated-From: 11a4d3dab158e107decc0d42ec7537dc28d2409c --- src/resources/web.ts | 30 ++++++++++++++++++++++++++---- tests/api-resources/web.test.ts | 2 ++ 2 files changed, 28 insertions(+), 4 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 8cef1df5..8331c106 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1356,8 +1356,8 @@ export interface WebScreenshotResponse { key_metadata?: WebScreenshotResponse.KeyMetadata; /** - * Public image URL for standard requests, or an in-memory data URL when ZDR is - * enabled. + * Public image URL for standard requests, or an in-memory data URL when ZDR or + * non-empty custom headers are supplied. */ screenshot?: string; @@ -2628,8 +2628,8 @@ export interface WebWebScrapeScreenshotResponse { request_id: string; /** - * Public image URL for standard requests, or an in-memory data URL when ZDR is - * enabled. + * Public image URL for standard requests, or an in-memory data URL when ZDR or + * non-empty custom headers are supplied. */ screenshot: string; @@ -3493,6 +3493,17 @@ export interface WebScreenshotParams { */ handleCookiePopup?: boolean; + /** + * Optional outbound HTTP headers, using the same JSON object or deep-object query + * format as other scrape endpoints (for example headers[Authorization]=Bearer + * token). Headers are scoped to the target origin during capture. For domain/page + * requests, discovery receives no custom headers and only pages on the resolved + * origin are eligible. Non-empty headers bypass screenshot caching and return an + * in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted + * headers. + */ + headers?: { [key: string]: string }; + /** * Return a cached screenshot if a prior screenshot for the same parameters exists * and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when @@ -5984,6 +5995,17 @@ export interface WebWebScrapeScreenshotParams { */ handleCookiePopup?: boolean; + /** + * Optional outbound HTTP headers, using the same JSON object or deep-object query + * format as other scrape endpoints (for example headers[Authorization]=Bearer + * token). Headers are scoped to the target origin during capture. For domain/page + * requests, discovery receives no custom headers and only pages on the resolved + * origin are eligible. Non-empty headers bypass screenshot caching and return an + * in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted + * headers. + */ + headers?: { [key: string]: string }; + /** * Return a cached screenshot if a prior screenshot for the same parameters exists * and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index b8f9a2a3..ba707dba 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -194,6 +194,7 @@ describe('resource web', () => { domain: 'xxx', fullScreenshot: 'true', handleCookiePopup: true, + headers: { foo: 'J!' }, maxAgeMs: 0, page: 'login', scrollOffset: 0, @@ -456,6 +457,7 @@ describe('resource web', () => { country: 'de', fullScreenshot: 'true', handleCookiePopup: true, + headers: { foo: 'J!' }, maxAgeMs: 0, scrollOffset: 0, tags: ['production', 'team-alpha'], From 477940dccfff3cf4b2265d56dc7b15c95d232c1a Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 21 Sep 2026 03:42:43 +0000 Subject: [PATCH 060/232] feat(scrape): add cache age support to byte downloads (#1171) feat(scrape): support country for image scraping (#1172) Stainless-Generated-From: c91a6ed66d513d27f20588c29eaa9e726f91bbae --- src/resources/web.ts | 256 +++++++++++++++++++++++++++++++- tests/api-resources/web.test.ts | 2 + 2 files changed, 254 insertions(+), 4 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 8331c106..b88a2c38 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -151,9 +151,14 @@ export class Web extends APIResource { * Follows public redirects and retries failed downloads through ISP and * residential proxies, with a direct fallback. When country is specified, only a * residential proxy in that country is used. Supply headers such as Referer for - * images that require a referring page. Downloads are not cached. Maximum decoded - * resource size: 20 MiB (20971520 bytes), before base64 encoding. Successful - * requests cost 1 credit; errors are not billed. + * images that require a referring page. Cached results are reused according to + * maxAgeMs (default: 1 day; maximum: 30 days). Set maxAgeMs=0 to fetch fresh and + * refresh the cache. Cache identity includes the exact URL, country, waitForMs, + * and normalized outbound headers. Credential-bearing headers and zero data + * retention bypass cache reads and writes. cache_metadata reports hit, miss, or + * zdr and the cached result age in milliseconds. Maximum decoded resource size: 20 + * MiB (20971520 bytes), before base64 encoding. Successful requests cost 1 credit; + * errors are not billed. * * @example * ```ts @@ -1808,6 +1813,13 @@ export interface WebWebScrapeBytesResponse { */ bytes: string; + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + cache_metadata: WebWebScrapeBytesResponse.CacheMetadata; + /** * Number of decoded resource bytes, before base64 encoding. */ @@ -1851,6 +1863,24 @@ export interface WebWebScrapeBytesResponse { } export namespace WebWebScrapeBytesResponse { + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + export interface CacheMetadata { + /** + * Age of the cached data in milliseconds. Zero for miss and zdr responses. + */ + age_ms: number; + + /** + * Whether the response was served from cache, required fresh work, or honored + * zero-data-retention cache bypass. + */ + status: 'hit' | 'miss' | 'zdr'; + } + /** * Credit usage, included whenever a valid API key is provided. */ @@ -4647,10 +4677,18 @@ export interface WebWebScrapeBytesParams { * as a JSON object or deep-object query params such as * headers[Referer]=https://example.com/. Host, Content-Length, and hop-by-hop * transport headers are rejected. Authorization and cookies are removed when a - * redirect changes origin. + * redirect changes origin. Credential-bearing headers bypass cache reads and + * writes; other headers are included in the cache key. */ headers?: { [key: string]: string }; + /** + * Return a cached result if a prior scrape for the same parameters exists and is + * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when + * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + */ + maxAgeMs?: number | null; + /** * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 * characters. @@ -5162,6 +5200,216 @@ export interface WebWebScrapeImagesParams { | WebWebScrapeImagesParams.WebScrapeScrollAction > | null; + /** + * Fetch the target page through a residential proxy in this country (ISO 3166-1 + * alpha-2). + */ + country?: + | 'ad' + | 'ae' + | 'af' + | 'ag' + | 'ai' + | 'al' + | 'am' + | 'ao' + | 'ar' + | 'at' + | 'au' + | 'aw' + | 'az' + | 'ba' + | 'bb' + | 'bd' + | 'be' + | 'bf' + | 'bg' + | 'bh' + | 'bi' + | 'bj' + | 'bm' + | 'bn' + | 'bo' + | 'bq' + | 'br' + | 'bs' + | 'bw' + | 'by' + | 'bz' + | 'ca' + | 'cd' + | 'cf' + | 'cg' + | 'ch' + | 'ci' + | 'cl' + | 'cm' + | 'cn' + | 'co' + | 'cr' + | 'cv' + | 'cw' + | 'cy' + | 'cz' + | 'de' + | 'dj' + | 'dk' + | 'dm' + | 'do' + | 'dz' + | 'ec' + | 'ee' + | 'eg' + | 'es' + | 'et' + | 'fi' + | 'fj' + | 'fr' + | 'ga' + | 'gb' + | 'gd' + | 'ge' + | 'gf' + | 'gg' + | 'gh' + | 'gm' + | 'gn' + | 'gp' + | 'gq' + | 'gr' + | 'gt' + | 'gu' + | 'gw' + | 'gy' + | 'hk' + | 'hn' + | 'hr' + | 'ht' + | 'hu' + | 'id' + | 'ie' + | 'il' + | 'im' + | 'in' + | 'iq' + | 'ir' + | 'is' + | 'it' + | 'je' + | 'jm' + | 'jo' + | 'jp' + | 'ke' + | 'kg' + | 'kh' + | 'kn' + | 'kr' + | 'kw' + | 'ky' + | 'kz' + | 'la' + | 'lb' + | 'lc' + | 'lk' + | 'lr' + | 'ls' + | 'lt' + | 'lu' + | 'lv' + | 'ly' + | 'ma' + | 'mc' + | 'md' + | 'me' + | 'mf' + | 'mg' + | 'mk' + | 'ml' + | 'mm' + | 'mn' + | 'mo' + | 'mq' + | 'mr' + | 'mt' + | 'mu' + | 'mv' + | 'mw' + | 'mx' + | 'my' + | 'mz' + | 'na' + | 'nc' + | 'ne' + | 'ng' + | 'ni' + | 'nl' + | 'no' + | 'np' + | 'nz' + | 'om' + | 'pa' + | 'pe' + | 'pf' + | 'pg' + | 'ph' + | 'pk' + | 'pl' + | 'pr' + | 'ps' + | 'pt' + | 'py' + | 'qa' + | 're' + | 'ro' + | 'rs' + | 'ru' + | 'rw' + | 'sa' + | 'sc' + | 'sd' + | 'se' + | 'sg' + | 'si' + | 'sk' + | 'sl' + | 'sm' + | 'sn' + | 'so' + | 'sr' + | 'ss' + | 'st' + | 'sv' + | 'sx' + | 'sy' + | 'sz' + | 'tc' + | 'td' + | 'tg' + | 'th' + | 'tj' + | 'tl' + | 'tm' + | 'tn' + | 'tr' + | 'tt' + | 'tw' + | 'tz' + | 'ua' + | 'ug' + | 'us' + | 'uy' + | 'uz' + | 'vc' + | 've' + | 'vg' + | 'vi' + | 'vn' + | 'ye' + | 'yt' + | 'za' + | 'zm' + | 'zw'; + /** * When true, visually duplicate images are removed: every image is loaded and * perceptually hashed, and only the highest-resolution copy of each duplicate diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index ba707dba..a30a369f 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -315,6 +315,7 @@ describe('resource web', () => { url: 'https://example.com', country: 'de', headers: { foo: 'J!' }, + maxAgeMs: 0, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1, behavior: 'fail' }, waitForMs: 0, @@ -378,6 +379,7 @@ describe('resource web', () => { const response = await client.web.webScrapeImages({ url: 'https://example.com', actions: [{ do: 'wait', timeMs: 0 }], + country: 'de', dedupe: true, enrichment: { classification: true, From dac4cf3623508d4598bb71035dfc4f14a4d79b8b Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 21 Sep 2026 06:37:33 +0000 Subject: [PATCH 061/232] seal --- src/resources/web.ts | 306 ++++++++++++++++++++++++++++++-- tests/api-resources/web.test.ts | 5 + 2 files changed, 299 insertions(+), 12 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index b6aa5784..b88a2c38 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -142,16 +142,23 @@ export class Web extends APIResource { } /** - * Downloads a resource and returns its bytes as base64. Supports images, PDFs, - * HTML pages, and any other content type without image conversion, text - * extraction, or character-encoding changes. HTTP compression is decoded before - * base64 encoding. HTML is the original HTTP response; JavaScript is not rendered. + * Downloads a resource and returns its bytes as base64. Without waitForMs, returns + * the original HTTP response without image conversion, text extraction, or + * character-encoding changes. HTTP compression is decoded before base64 encoding. + * Supply waitForMs to render HTML with JavaScript in the browser and return the + * resulting HTML as UTF-8 bytes after the wait. Non-HTML resources, including + * images and PDFs, keep their original bytes and do not incur a browser wait. * Follows public redirects and retries failed downloads through ISP and * residential proxies, with a direct fallback. When country is specified, only a * residential proxy in that country is used. Supply headers such as Referer for - * images that require a referring page. Downloads are not cached. Maximum decoded - * resource size: 20 MiB (20971520 bytes), before base64 encoding. Successful - * requests cost 1 credit; errors are not billed. + * images that require a referring page. Cached results are reused according to + * maxAgeMs (default: 1 day; maximum: 30 days). Set maxAgeMs=0 to fetch fresh and + * refresh the cache. Cache identity includes the exact URL, country, waitForMs, + * and normalized outbound headers. Credential-bearing headers and zero data + * retention bypass cache reads and writes. cache_metadata reports hit, miss, or + * zdr and the cached result age in milliseconds. Maximum decoded resource size: 20 + * MiB (20971520 bytes), before base64 encoding. Successful requests cost 1 credit; + * errors are not billed. * * @example * ```ts @@ -1354,8 +1361,8 @@ export interface WebScreenshotResponse { key_metadata?: WebScreenshotResponse.KeyMetadata; /** - * Public image URL for standard requests, or an in-memory data URL when ZDR is - * enabled. + * Public image URL for standard requests, or an in-memory data URL when ZDR or + * non-empty custom headers are supplied. */ screenshot?: string; @@ -1806,6 +1813,13 @@ export interface WebWebScrapeBytesResponse { */ bytes: string; + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + cache_metadata: WebWebScrapeBytesResponse.CacheMetadata; + /** * Number of decoded resource bytes, before base64 encoding. */ @@ -1849,6 +1863,24 @@ export interface WebWebScrapeBytesResponse { } export namespace WebWebScrapeBytesResponse { + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + export interface CacheMetadata { + /** + * Age of the cached data in milliseconds. Zero for miss and zdr responses. + */ + age_ms: number; + + /** + * Whether the response was served from cache, required fresh work, or honored + * zero-data-retention cache bypass. + */ + status: 'hit' | 'miss' | 'zdr'; + } + /** * Credit usage, included whenever a valid API key is provided. */ @@ -2626,8 +2658,8 @@ export interface WebWebScrapeScreenshotResponse { request_id: string; /** - * Public image URL for standard requests, or an in-memory data URL when ZDR is - * enabled. + * Public image URL for standard requests, or an in-memory data URL when ZDR or + * non-empty custom headers are supplied. */ screenshot: string; @@ -3491,6 +3523,17 @@ export interface WebScreenshotParams { */ handleCookiePopup?: boolean; + /** + * Optional outbound HTTP headers, using the same JSON object or deep-object query + * format as other scrape endpoints (for example headers[Authorization]=Bearer + * token). Headers are scoped to the target origin during capture. For domain/page + * requests, discovery receives no custom headers and only pages on the resolved + * origin are eligible. Non-empty headers bypass screenshot caching and return an + * in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted + * headers. + */ + headers?: { [key: string]: string }; + /** * Return a cached screenshot if a prior screenshot for the same parameters exists * and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when @@ -4634,10 +4677,18 @@ export interface WebWebScrapeBytesParams { * as a JSON object or deep-object query params such as * headers[Referer]=https://example.com/. Host, Content-Length, and hop-by-hop * transport headers are rejected. Authorization and cookies are removed when a - * redirect changes origin. + * redirect changes origin. Credential-bearing headers bypass cache reads and + * writes; other headers are included in the cache key. */ headers?: { [key: string]: string }; + /** + * Return a cached result if a prior scrape for the same parameters exists and is + * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when + * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + */ + maxAgeMs?: number | null; + /** * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 * characters. @@ -4651,6 +4702,16 @@ export interface WebWebScrapeBytesParams { */ timeoutOpts?: WebWebScrapeBytesParams.TimeoutOpts; + /** + * Optional browser wait time after initial page load, in milliseconds (0–30000; 0 + * uses 500). When supplied, HTML is rendered with JavaScript and returned as UTF-8 + * bytes. Other resources keep their original bytes without a browser wait. Omit to + * download the original HTTP response. When combined with timeoutOpts, + * timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter + * deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. + */ + waitForMs?: number | null; + /** * Set to enabled to bypass shared caches and omit request and response content * from retained usage logs. Asset uploads are skipped, so hosted image URLs are @@ -5139,6 +5200,216 @@ export interface WebWebScrapeImagesParams { | WebWebScrapeImagesParams.WebScrapeScrollAction > | null; + /** + * Fetch the target page through a residential proxy in this country (ISO 3166-1 + * alpha-2). + */ + country?: + | 'ad' + | 'ae' + | 'af' + | 'ag' + | 'ai' + | 'al' + | 'am' + | 'ao' + | 'ar' + | 'at' + | 'au' + | 'aw' + | 'az' + | 'ba' + | 'bb' + | 'bd' + | 'be' + | 'bf' + | 'bg' + | 'bh' + | 'bi' + | 'bj' + | 'bm' + | 'bn' + | 'bo' + | 'bq' + | 'br' + | 'bs' + | 'bw' + | 'by' + | 'bz' + | 'ca' + | 'cd' + | 'cf' + | 'cg' + | 'ch' + | 'ci' + | 'cl' + | 'cm' + | 'cn' + | 'co' + | 'cr' + | 'cv' + | 'cw' + | 'cy' + | 'cz' + | 'de' + | 'dj' + | 'dk' + | 'dm' + | 'do' + | 'dz' + | 'ec' + | 'ee' + | 'eg' + | 'es' + | 'et' + | 'fi' + | 'fj' + | 'fr' + | 'ga' + | 'gb' + | 'gd' + | 'ge' + | 'gf' + | 'gg' + | 'gh' + | 'gm' + | 'gn' + | 'gp' + | 'gq' + | 'gr' + | 'gt' + | 'gu' + | 'gw' + | 'gy' + | 'hk' + | 'hn' + | 'hr' + | 'ht' + | 'hu' + | 'id' + | 'ie' + | 'il' + | 'im' + | 'in' + | 'iq' + | 'ir' + | 'is' + | 'it' + | 'je' + | 'jm' + | 'jo' + | 'jp' + | 'ke' + | 'kg' + | 'kh' + | 'kn' + | 'kr' + | 'kw' + | 'ky' + | 'kz' + | 'la' + | 'lb' + | 'lc' + | 'lk' + | 'lr' + | 'ls' + | 'lt' + | 'lu' + | 'lv' + | 'ly' + | 'ma' + | 'mc' + | 'md' + | 'me' + | 'mf' + | 'mg' + | 'mk' + | 'ml' + | 'mm' + | 'mn' + | 'mo' + | 'mq' + | 'mr' + | 'mt' + | 'mu' + | 'mv' + | 'mw' + | 'mx' + | 'my' + | 'mz' + | 'na' + | 'nc' + | 'ne' + | 'ng' + | 'ni' + | 'nl' + | 'no' + | 'np' + | 'nz' + | 'om' + | 'pa' + | 'pe' + | 'pf' + | 'pg' + | 'ph' + | 'pk' + | 'pl' + | 'pr' + | 'ps' + | 'pt' + | 'py' + | 'qa' + | 're' + | 'ro' + | 'rs' + | 'ru' + | 'rw' + | 'sa' + | 'sc' + | 'sd' + | 'se' + | 'sg' + | 'si' + | 'sk' + | 'sl' + | 'sm' + | 'sn' + | 'so' + | 'sr' + | 'ss' + | 'st' + | 'sv' + | 'sx' + | 'sy' + | 'sz' + | 'tc' + | 'td' + | 'tg' + | 'th' + | 'tj' + | 'tl' + | 'tm' + | 'tn' + | 'tr' + | 'tt' + | 'tw' + | 'tz' + | 'ua' + | 'ug' + | 'us' + | 'uy' + | 'uz' + | 'vc' + | 've' + | 'vg' + | 'vi' + | 'vn' + | 'ye' + | 'yt' + | 'za' + | 'zm' + | 'zw'; + /** * When true, visually duplicate images are removed: every image is loaded and * perceptually hashed, and only the highest-resolution copy of each duplicate @@ -5972,6 +6243,17 @@ export interface WebWebScrapeScreenshotParams { */ handleCookiePopup?: boolean; + /** + * Optional outbound HTTP headers, using the same JSON object or deep-object query + * format as other scrape endpoints (for example headers[Authorization]=Bearer + * token). Headers are scoped to the target origin during capture. For domain/page + * requests, discovery receives no custom headers and only pages on the resolved + * origin are eligible. Non-empty headers bypass screenshot caching and return an + * in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted + * headers. + */ + headers?: { [key: string]: string }; + /** * Return a cached screenshot if a prior screenshot for the same parameters exists * and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index fb6345a3..a30a369f 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -194,6 +194,7 @@ describe('resource web', () => { domain: 'xxx', fullScreenshot: 'true', handleCookiePopup: true, + headers: { foo: 'J!' }, maxAgeMs: 0, page: 'login', scrollOffset: 0, @@ -314,8 +315,10 @@ describe('resource web', () => { url: 'https://example.com', country: 'de', headers: { foo: 'J!' }, + maxAgeMs: 0, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1, behavior: 'fail' }, + waitForMs: 0, zdr: 'enabled', }); }); @@ -376,6 +379,7 @@ describe('resource web', () => { const response = await client.web.webScrapeImages({ url: 'https://example.com', actions: [{ do: 'wait', timeMs: 0 }], + country: 'de', dedupe: true, enrichment: { classification: true, @@ -455,6 +459,7 @@ describe('resource web', () => { country: 'de', fullScreenshot: 'true', handleCookiePopup: true, + headers: { foo: 'J!' }, maxAgeMs: 0, scrollOffset: 0, tags: ['production', 'team-alpha'], From 3c92f39ccd9d60820af5874e866fcc8058a9f2d5 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 21 Sep 2026 18:42:22 +0000 Subject: [PATCH 062/232] feat(scrape): add unified scrape API (#1182) Stainless-Generated-From: c2bbfa8bc0e994e362ebef8b71f3db8d5436bc44 --- .stats.yml | 2 +- api.md | 2 + src/client.ts | 4 + src/resources/index.ts | 2 + src/resources/web.ts | 688 ++++++++++++++++++++++++++++++++ tests/api-resources/web.test.ts | 73 ++++ 6 files changed, 770 insertions(+), 1 deletion(-) diff --git a/.stats.yml b/.stats.yml index 4e6a016a..c550abf3 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 50 +configured_endpoints: 51 diff --git a/api.md b/api.md index bce5b1ab..ec2596eb 100644 --- a/api.md +++ b/api.md @@ -17,6 +17,7 @@ Types: - WebExtractCompetitorsResponse - WebExtractFontsResponse - WebExtractStyleguideResponse +- WebScrapeResponse - WebScreenshotResponse - WebSearchResponse - WebWebCrawlMdResponse @@ -34,6 +35,7 @@ Methods: - client.web.extractCompetitors({ ...params }) -> WebExtractCompetitorsResponse - client.web.extractFonts({ ...params }) -> WebExtractFontsResponse - client.web.extractStyleguide({ ...params }) -> WebExtractStyleguideResponse +- client.web.scrape({ ...params }) -> WebScrapeResponse - client.web.screenshot({ ...params }) -> WebScreenshotResponse - client.web.search({ ...params }) -> WebSearchResponse - client.web.webCrawlMd({ ...params }) -> WebWebCrawlMdResponse diff --git a/src/client.ts b/src/client.ts index 9b06ee2c..b8568076 100644 --- a/src/client.ts +++ b/src/client.ts @@ -98,6 +98,8 @@ import { WebExtractResponse, WebExtractStyleguideParams, WebExtractStyleguideResponse, + WebScrapeParams, + WebScrapeResponse, WebScreenshotParams, WebScreenshotResponse, WebSearchParams, @@ -890,6 +892,7 @@ export declare namespace ContextDev { type WebExtractCompetitorsResponse as WebExtractCompetitorsResponse, type WebExtractFontsResponse as WebExtractFontsResponse, type WebExtractStyleguideResponse as WebExtractStyleguideResponse, + type WebScrapeResponse as WebScrapeResponse, type WebScreenshotResponse as WebScreenshotResponse, type WebSearchResponse as WebSearchResponse, type WebWebCrawlMdResponse as WebWebCrawlMdResponse, @@ -904,6 +907,7 @@ export declare namespace ContextDev { type WebExtractCompetitorsParams as WebExtractCompetitorsParams, type WebExtractFontsParams as WebExtractFontsParams, type WebExtractStyleguideParams as WebExtractStyleguideParams, + type WebScrapeParams as WebScrapeParams, type WebScreenshotParams as WebScreenshotParams, type WebSearchParams as WebSearchParams, type WebWebCrawlMdParams as WebWebCrawlMdParams, diff --git a/src/resources/index.ts b/src/resources/index.ts index abb56d4c..3628f91f 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -76,6 +76,7 @@ export { type WebExtractCompetitorsResponse, type WebExtractFontsResponse, type WebExtractStyleguideResponse, + type WebScrapeResponse, type WebScreenshotResponse, type WebSearchResponse, type WebWebCrawlMdResponse, @@ -90,6 +91,7 @@ export { type WebExtractCompetitorsParams, type WebExtractFontsParams, type WebExtractStyleguideParams, + type WebScrapeParams, type WebScreenshotParams, type WebSearchParams, type WebWebCrawlMdParams, diff --git a/src/resources/web.ts b/src/resources/web.ts index b88a2c38..283baeb2 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -99,6 +99,25 @@ export class Web extends APIResource { return this._client.get('/web/styleguide', { query, ...options }); } + /** + * Capture the requested formats from one page visit. Shared settings apply once. + * HTML-only requests use the existing fast acquisition path. One credit per + * capture, or two with browser actions; PDF OCR adds one credit per recovered + * page. Original response bytes and screenshots are limited to 20 MiB each, + * screenshots to 40 megapixels, and the combined browser capture to 60 MiB. + * + * @example + * ```ts + * const response = await client.web.scrape({ + * formats: { html: true }, + * url: 'https://example.com', + * }); + * ``` + */ + scrape(body: WebScrapeParams, options?: RequestOptions): APIPromise { + return this._client.post('/web/scrape', { body, ...options }); + } + /** * Capture a screenshot of a website. * @@ -1317,6 +1336,335 @@ export namespace WebExtractStyleguideResponse { } } +export interface WebScrapeResponse { + /** + * Original HTTP response body. Waiting, actions, and content filters never change + * it. + */ + bytes: WebScrapeResponse.Bytes; + + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + cache_metadata: WebScrapeResponse.CacheMetadata; + + /** + * Rendered HTML after content filters. + */ + html: WebScrapeResponse.HTML; + + /** + * Images after content filters. Empty when none are found. + */ + images: WebScrapeResponse.Images; + + /** + * Markdown after content filters. + */ + markdown: WebScrapeResponse.Markdown; + + /** + * Page details, when available. + */ + metadata: WebScrapeResponse.Metadata; + + /** + * Fields produced by parseParams.rules, after shared content filters. + */ + parsed: WebScrapeResponse.Parsed; + + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + + /** + * An image data URL. Use directly as an image src. + */ + screenshot: WebScrapeResponse.Screenshot; + + /** + * Final URL after redirects and browser actions. + */ + url: string; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: WebScrapeResponse.KeyMetadata; +} + +export namespace WebScrapeResponse { + /** + * Original HTTP response body. Waiting, actions, and content filters never change + * it. + */ + export interface Bytes { + data: Bytes.Data | null; + + requested: boolean; + } + + export namespace Bytes { + export interface Data { + /** + * Original response body as base64, after HTTP decompression. Maximum decoded + * size: 20 MiB. + */ + base64: string; + + contentType: string; + } + } + + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + export interface CacheMetadata { + /** + * Age of the cached data in milliseconds. Zero for miss and zdr responses. + */ + age_ms: number; + + /** + * Whether the response was served from cache, required fresh work, or honored + * zero-data-retention cache bypass. + */ + status: 'hit' | 'miss' | 'zdr'; + } + + /** + * Rendered HTML after content filters. + */ + export interface HTML { + data: string | null; + + requested: boolean; + } + + /** + * Images after content filters. Empty when none are found. + */ + export interface Images { + data: Array | null; + + requested: boolean; + } + + export namespace Images { + export interface Data { + /** + * Alt text, if present. + */ + alt: string | null; + + /** + * Image URL, or a data URI for inline images. + */ + url: string; + + classification?: + | 'photography' + | 'illustration' + | 'logo' + | 'wordmark' + | 'icon' + | 'pattern' + | 'graphic' + | 'other'; + + /** + * Hosted copy when file enrichment is requested and zdr is disabled. Valid for 24 + * hours from the original capture. + */ + fileUrl?: string; + + height?: number; + + width?: number; + } + } + + /** + * Markdown after content filters. + */ + export interface Markdown { + data: string | null; + + requested: boolean; + } + + /** + * Page details, when available. + */ + export interface Metadata { + /** + * Additional non-social meta tags not promoted to top-level metadata fields. + */ + additionalMeta?: { [key: string]: string | Array }; + + /** + * Resolved alternate links from link rel=alternate tags. + */ + alternates?: Array; + + /** + * Author metadata, when present. + */ + author?: string; + + /** + * Resolved canonical URL, when present. + */ + canonicalUrl?: string; + + /** + * Best description extracted from standard, Open Graph, or Twitter metadata. + */ + description?: string; + + /** + * Resolved favicon URL, when present. + */ + favicon?: string; + + /** + * Page headings (h1–h6) in document order, extracted from the unfiltered document. + * Capped at the first 500 headings. Omitted when the page has none. + */ + headings?: Array; + + /** + * Primary resolved preview image from Open Graph, Twitter, or image metadata. + */ + image?: string; + + /** + * JSON-LD structured data blocks parsed from the page. + */ + jsonLd?: Array<{ [key: string]: unknown }>; + + /** + * Keywords extracted from the page's keywords meta tag. + */ + keywords?: Array; + + /** + * Language extracted from html lang or language meta tags. + */ + language?: string; + + /** + * Modified timestamp/date from page metadata, when present. + */ + modifiedTime?: string; + + /** + * Open Graph metadata with the og: prefix removed and keys camel-cased. + */ + openGraph?: { [key: string]: string | Array }; + + /** + * Published timestamp/date from page metadata, when present. + */ + publishedTime?: string; + + /** + * Robots meta directive, when present. + */ + robots?: string; + + /** + * Site or application name from page metadata. + */ + siteName?: string; + + /** + * Best title extracted from the page. + */ + title?: string; + + /** + * Twitter card metadata with the twitter: prefix removed and keys camel-cased. + */ + twitter?: { [key: string]: string | Array }; + } + + export namespace Metadata { + export interface Alternate { + /** + * Resolved alternate URL. + */ + href: string; + + /** + * Language or locale for the alternate URL, when present. + */ + hreflang?: string; + + /** + * Alternate resource title, when present. + */ + title?: string; + + /** + * Alternate resource MIME type, when present. + */ + type?: string; + } + + export interface Heading { + /** + * Heading level, 1–6 (from h1–h6). + */ + level: number; + + /** + * Heading text with whitespace collapsed, truncated to 1000 characters. + */ + text: string; + } + } + + /** + * Fields produced by parseParams.rules, after shared content filters. + */ + export interface Parsed { + data: { [key: string]: unknown } | null; + + requested: boolean; + } + + /** + * An image data URL. Use directly as an image src. + */ + export interface Screenshot { + data: string | null; + + requested: boolean; + } + + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + export interface WebScreenshotResponse { /** * Cache outcome for this response. Composite responses are hits only when every @@ -3269,6 +3617,344 @@ export namespace WebExtractStyleguideParams { } } +export interface WebScrapeParams { + /** + * Outputs to return. Enable at least one; omitted formats are false. + */ + formats: WebScrapeParams.Formats; + + /** + * The URL to scrape. + */ + url: string; + + /** + * Image options. Requires formats.images: true. + */ + imageParams?: WebScrapeParams.ImageParams; + + /** + * Markdown options. Requires formats.markdown: true. + */ + markdownParams?: WebScrapeParams.MarkdownParams; + + /** + * Maximum age for the entire capture, including bytes. Defaults to 1 day; 0 + * fetches fresh. Captures with hosted image files refresh after 23 hours. + */ + maxAgeMs?: number; + + /** + * Required when formats.parse is true. + */ + parseParams?: WebScrapeParams.ParseParams; + + /** + * Screenshot options. Requires formats.screenshot: true. + */ + screenshotParams?: WebScrapeParams.ScreenshotParams; + + /** + * Shared browser and content settings. Content filters leave screenshots and + * original bytes unchanged. + */ + sharedParams?: WebScrapeParams.SharedParams; + + /** + * Labels for tracking request usage. Not retained when zdr is enabled. + */ + tags?: Array; + + /** + * Total deadline, including navigation, actions, waiting, and all outputs. + */ + timeoutMs?: number; + + /** + * Zero data retention. Bypasses caches and uploads; excludes request/response + * content and tags from logs. Must be enabled for your organization. + */ + zdr?: 'enabled' | 'disabled'; +} + +export namespace WebScrapeParams { + /** + * Outputs to return. Enable at least one; omitted formats are false. + */ + export interface Formats { + /** + * The original HTTP response body. + */ + bytes?: boolean; + + /** + * Rendered HTML. + */ + html?: boolean; + + /** + * Images found on the page. + */ + images?: boolean; + + /** + * Page content as Markdown. + */ + markdown?: boolean; + + /** + * Fields selected by parseParams.rules. + */ + parse?: boolean; + + /** + * An inline image of the page. + */ + screenshot?: boolean; + } + + /** + * Image options. Requires formats.images: true. + */ + export interface ImageParams { + /** + * For visual duplicates, keep the largest image. + */ + dedupe?: 'none' | 'visual'; + + /** + * Add dimensions, a visual category, or a hosted file URL. + */ + enrich?: Array<'dimensions' | 'classification' | 'file'>; + } + + /** + * Markdown options. Requires formats.markdown: true. + */ + export interface MarkdownParams { + includeImages?: boolean; + + includeLinks?: boolean; + + /** + * Base64 images use placeholders by default. Requires includeImages: true. + */ + inlineImages?: 'placeholder' | 'preserve'; + } + + /** + * Required when formats.parse is true. + */ + export interface ParseParams { + /** + * Map field names to CSS selectors or rules. Missing items return null; missing + * lists return []. + */ + rules: { [key: string]: string | ParseParams.UnionMember1 }; + } + + export namespace ParseParams { + export interface UnionMember1 { + selector: string; + + output?: 'text' | 'html' | string | unknown; + + type?: 'item' | 'list'; + } + } + + /** + * Screenshot options. Requires formats.screenshot: true. + */ + export interface ScreenshotParams { + /** + * Viewport, full page, one visible element, or a rectangle. Maximum 40 megapixels. + */ + area?: 'viewport' | 'fullPage' | ScreenshotParams.Element | ScreenshotParams.Rectangle; + + format?: 'png' | 'jpeg' | 'webp'; + } + + export namespace ScreenshotParams { + export interface Element { + /** + * Must match one visible element. + */ + selector: string; + } + + /** + * Pixels from the document origin. + */ + export interface Rectangle { + height: number; + + width: number; + + x: number; + + y: number; + } + } + + /** + * Shared browser and content settings. Content filters leave screenshots and + * original bytes unchanged. + */ + export interface SharedParams { + /** + * Run in order before capture. A failed action fails the request. Bypasses + * caching. + */ + actions?: Array; + + /** + * Supported two-letter country code, case-insensitive. Applies to every output, + * including image downloads. + */ + country?: string; + + /** + * Dismiss cookie banners by accepting cookies before actions. + */ + dismissCookies?: boolean; + + /** + * Dismiss other popups before actions. + */ + dismissPopups?: boolean; + + /** + * Remove matching content. Exclusions win. + */ + excludeSelectors?: Array; + + /** + * Headers for the target origin. Requests with custom headers bypass caching. + */ + headers?: { [key: string]: string }; + + /** + * Include iframe content in extraction. Screenshots show visible frames + * regardless. + */ + includeFrames?: boolean; + + /** + * Keep matching content after mainContentOnly. + */ + includeSelectors?: Array; + + /** + * Keep only main content in HTML, Markdown, images, and parsed fields. + */ + mainContentOnly?: boolean; + + /** + * Document parsing options. + */ + parsers?: SharedParams.Parsers; + + /** + * Settle animations before capture. Defaults to true with screenshots, otherwise + * false. + */ + settleAnimations?: boolean; + + /** + * Override the browser color scheme. + */ + theme?: 'light' | 'dark'; + + /** + * Browser dimensions in pixels. + */ + viewport?: SharedParams.Viewport; + + /** + * After actions, wait this many milliseconds or until a CSS selector is visible. + * Defaults to 500 ms, or 2000 ms with frames or an XML URL. Set 0 to skip. + */ + waitFor?: number | string; + } + + export namespace SharedParams { + export interface Perform { + action: string; + + type: 'perform'; + } + + export interface Scroll { + type: 'scroll'; + + amount?: number | 'viewport' | 'max'; + + direction?: 'down' | 'up' | 'left' | 'right'; + + maxScrolls?: number; + + /** + * Scroll this container. Omit to scroll the page. + */ + selector?: string; + } + + export interface Wait { + milliseconds: number; + + type: 'wait'; + } + + export interface WaitFor { + selector: string; + + type: 'waitFor'; + } + + /** + * Document parsing options. + */ + export interface Parsers { + /** + * PDF text options for HTML, Markdown, and parsed fields. + */ + pdf?: Parsers.Pdf; + } + + export namespace Parsers { + /** + * PDF text options for HTML, Markdown, and parsed fields. + */ + export interface Pdf { + /** + * Last page to parse. Must be at least startPage. + */ + endPage?: number; + + /** + * Read text from scanned pages. + */ + ocr?: 'off' | 'auto'; + + /** + * First page to parse, starting at 1. + */ + startPage?: number; + } + } + + /** + * Browser dimensions in pixels. + */ + export interface Viewport { + height?: number; + + width?: number; + } + } +} + export interface WebScreenshotParams { /** * Optional parameter for comprehensive popup cleanup. If 'true', the browser @@ -6442,6 +7128,7 @@ export declare namespace Web { type WebExtractCompetitorsResponse as WebExtractCompetitorsResponse, type WebExtractFontsResponse as WebExtractFontsResponse, type WebExtractStyleguideResponse as WebExtractStyleguideResponse, + type WebScrapeResponse as WebScrapeResponse, type WebScreenshotResponse as WebScreenshotResponse, type WebSearchResponse as WebSearchResponse, type WebWebCrawlMdResponse as WebWebCrawlMdResponse, @@ -6456,6 +7143,7 @@ export declare namespace Web { type WebExtractCompetitorsParams as WebExtractCompetitorsParams, type WebExtractFontsParams as WebExtractFontsParams, type WebExtractStyleguideParams as WebExtractStyleguideParams, + type WebScrapeParams as WebScrapeParams, type WebScreenshotParams as WebScreenshotParams, type WebSearchParams as WebSearchParams, type WebWebCrawlMdParams as WebWebCrawlMdParams, diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index a30a369f..6990f8bf 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -169,6 +169,79 @@ describe('resource web', () => { ).rejects.toThrow(ContextDev.NotFoundError); }); + // Mock server tests are disabled + test.skip('scrape: only required params', async () => { + const responsePromise = client.web.scrape({ + formats: {}, + url: 'https://example.com', + }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('scrape: required and optional params', async () => { + const response = await client.web.scrape({ + formats: { + bytes: true, + html: true, + images: true, + markdown: true, + parse: true, + screenshot: true, + }, + url: 'https://example.com', + imageParams: { dedupe: 'none', enrich: ['dimensions'] }, + markdownParams: { + includeImages: true, + includeLinks: true, + inlineImages: 'placeholder', + }, + maxAgeMs: 0, + parseParams: { + rules: { + title: 'h1', + links: { + selector: 'a', + output: '@href', + type: 'list', + }, + }, + }, + screenshotParams: { area: 'viewport', format: 'png' }, + sharedParams: { + actions: [{ action: 'Click the product details tab', type: 'perform' }], + country: 'US', + dismissCookies: true, + dismissPopups: true, + excludeSelectors: ['P'], + headers: { 'Accept-Language': 'en-US' }, + includeFrames: true, + includeSelectors: ['P'], + mainContentOnly: true, + parsers: { + pdf: { + endPage: 1, + ocr: 'off', + startPage: 1, + }, + }, + settleAnimations: true, + theme: 'light', + viewport: { height: 240, width: 240 }, + waitFor: 500, + }, + tags: ['production', 'team-alpha'], + timeoutMs: 1, + zdr: 'enabled', + }); + }); + // Mock server tests are disabled test.skip('screenshot', async () => { const responsePromise = client.web.screenshot(); From c2bbfa8bc0e994e362ebef8b71f3db8d5436bc44 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 21 Sep 2026 18:42:22 +0000 Subject: [PATCH 063/232] seal --- .stats.yml | 2 +- api.md | 2 + src/client.ts | 4 + src/resources/index.ts | 2 + src/resources/web.ts | 688 ++++++++++++++++++++++++++++++++ tests/api-resources/web.test.ts | 73 ++++ 6 files changed, 770 insertions(+), 1 deletion(-) diff --git a/.stats.yml b/.stats.yml index 4e6a016a..c550abf3 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 50 +configured_endpoints: 51 diff --git a/api.md b/api.md index bce5b1ab..ec2596eb 100644 --- a/api.md +++ b/api.md @@ -17,6 +17,7 @@ Types: - WebExtractCompetitorsResponse - WebExtractFontsResponse - WebExtractStyleguideResponse +- WebScrapeResponse - WebScreenshotResponse - WebSearchResponse - WebWebCrawlMdResponse @@ -34,6 +35,7 @@ Methods: - client.web.extractCompetitors({ ...params }) -> WebExtractCompetitorsResponse - client.web.extractFonts({ ...params }) -> WebExtractFontsResponse - client.web.extractStyleguide({ ...params }) -> WebExtractStyleguideResponse +- client.web.scrape({ ...params }) -> WebScrapeResponse - client.web.screenshot({ ...params }) -> WebScreenshotResponse - client.web.search({ ...params }) -> WebSearchResponse - client.web.webCrawlMd({ ...params }) -> WebWebCrawlMdResponse diff --git a/src/client.ts b/src/client.ts index 9b06ee2c..b8568076 100644 --- a/src/client.ts +++ b/src/client.ts @@ -98,6 +98,8 @@ import { WebExtractResponse, WebExtractStyleguideParams, WebExtractStyleguideResponse, + WebScrapeParams, + WebScrapeResponse, WebScreenshotParams, WebScreenshotResponse, WebSearchParams, @@ -890,6 +892,7 @@ export declare namespace ContextDev { type WebExtractCompetitorsResponse as WebExtractCompetitorsResponse, type WebExtractFontsResponse as WebExtractFontsResponse, type WebExtractStyleguideResponse as WebExtractStyleguideResponse, + type WebScrapeResponse as WebScrapeResponse, type WebScreenshotResponse as WebScreenshotResponse, type WebSearchResponse as WebSearchResponse, type WebWebCrawlMdResponse as WebWebCrawlMdResponse, @@ -904,6 +907,7 @@ export declare namespace ContextDev { type WebExtractCompetitorsParams as WebExtractCompetitorsParams, type WebExtractFontsParams as WebExtractFontsParams, type WebExtractStyleguideParams as WebExtractStyleguideParams, + type WebScrapeParams as WebScrapeParams, type WebScreenshotParams as WebScreenshotParams, type WebSearchParams as WebSearchParams, type WebWebCrawlMdParams as WebWebCrawlMdParams, diff --git a/src/resources/index.ts b/src/resources/index.ts index abb56d4c..3628f91f 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -76,6 +76,7 @@ export { type WebExtractCompetitorsResponse, type WebExtractFontsResponse, type WebExtractStyleguideResponse, + type WebScrapeResponse, type WebScreenshotResponse, type WebSearchResponse, type WebWebCrawlMdResponse, @@ -90,6 +91,7 @@ export { type WebExtractCompetitorsParams, type WebExtractFontsParams, type WebExtractStyleguideParams, + type WebScrapeParams, type WebScreenshotParams, type WebSearchParams, type WebWebCrawlMdParams, diff --git a/src/resources/web.ts b/src/resources/web.ts index b88a2c38..283baeb2 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -99,6 +99,25 @@ export class Web extends APIResource { return this._client.get('/web/styleguide', { query, ...options }); } + /** + * Capture the requested formats from one page visit. Shared settings apply once. + * HTML-only requests use the existing fast acquisition path. One credit per + * capture, or two with browser actions; PDF OCR adds one credit per recovered + * page. Original response bytes and screenshots are limited to 20 MiB each, + * screenshots to 40 megapixels, and the combined browser capture to 60 MiB. + * + * @example + * ```ts + * const response = await client.web.scrape({ + * formats: { html: true }, + * url: 'https://example.com', + * }); + * ``` + */ + scrape(body: WebScrapeParams, options?: RequestOptions): APIPromise { + return this._client.post('/web/scrape', { body, ...options }); + } + /** * Capture a screenshot of a website. * @@ -1317,6 +1336,335 @@ export namespace WebExtractStyleguideResponse { } } +export interface WebScrapeResponse { + /** + * Original HTTP response body. Waiting, actions, and content filters never change + * it. + */ + bytes: WebScrapeResponse.Bytes; + + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + cache_metadata: WebScrapeResponse.CacheMetadata; + + /** + * Rendered HTML after content filters. + */ + html: WebScrapeResponse.HTML; + + /** + * Images after content filters. Empty when none are found. + */ + images: WebScrapeResponse.Images; + + /** + * Markdown after content filters. + */ + markdown: WebScrapeResponse.Markdown; + + /** + * Page details, when available. + */ + metadata: WebScrapeResponse.Metadata; + + /** + * Fields produced by parseParams.rules, after shared content filters. + */ + parsed: WebScrapeResponse.Parsed; + + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + + /** + * An image data URL. Use directly as an image src. + */ + screenshot: WebScrapeResponse.Screenshot; + + /** + * Final URL after redirects and browser actions. + */ + url: string; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: WebScrapeResponse.KeyMetadata; +} + +export namespace WebScrapeResponse { + /** + * Original HTTP response body. Waiting, actions, and content filters never change + * it. + */ + export interface Bytes { + data: Bytes.Data | null; + + requested: boolean; + } + + export namespace Bytes { + export interface Data { + /** + * Original response body as base64, after HTTP decompression. Maximum decoded + * size: 20 MiB. + */ + base64: string; + + contentType: string; + } + } + + /** + * Cache outcome for this response. Composite responses are hits only when every + * cache-controlled fetch contributing to the output was a hit; age_ms is the + * oldest contributing hit. + */ + export interface CacheMetadata { + /** + * Age of the cached data in milliseconds. Zero for miss and zdr responses. + */ + age_ms: number; + + /** + * Whether the response was served from cache, required fresh work, or honored + * zero-data-retention cache bypass. + */ + status: 'hit' | 'miss' | 'zdr'; + } + + /** + * Rendered HTML after content filters. + */ + export interface HTML { + data: string | null; + + requested: boolean; + } + + /** + * Images after content filters. Empty when none are found. + */ + export interface Images { + data: Array | null; + + requested: boolean; + } + + export namespace Images { + export interface Data { + /** + * Alt text, if present. + */ + alt: string | null; + + /** + * Image URL, or a data URI for inline images. + */ + url: string; + + classification?: + | 'photography' + | 'illustration' + | 'logo' + | 'wordmark' + | 'icon' + | 'pattern' + | 'graphic' + | 'other'; + + /** + * Hosted copy when file enrichment is requested and zdr is disabled. Valid for 24 + * hours from the original capture. + */ + fileUrl?: string; + + height?: number; + + width?: number; + } + } + + /** + * Markdown after content filters. + */ + export interface Markdown { + data: string | null; + + requested: boolean; + } + + /** + * Page details, when available. + */ + export interface Metadata { + /** + * Additional non-social meta tags not promoted to top-level metadata fields. + */ + additionalMeta?: { [key: string]: string | Array }; + + /** + * Resolved alternate links from link rel=alternate tags. + */ + alternates?: Array; + + /** + * Author metadata, when present. + */ + author?: string; + + /** + * Resolved canonical URL, when present. + */ + canonicalUrl?: string; + + /** + * Best description extracted from standard, Open Graph, or Twitter metadata. + */ + description?: string; + + /** + * Resolved favicon URL, when present. + */ + favicon?: string; + + /** + * Page headings (h1–h6) in document order, extracted from the unfiltered document. + * Capped at the first 500 headings. Omitted when the page has none. + */ + headings?: Array; + + /** + * Primary resolved preview image from Open Graph, Twitter, or image metadata. + */ + image?: string; + + /** + * JSON-LD structured data blocks parsed from the page. + */ + jsonLd?: Array<{ [key: string]: unknown }>; + + /** + * Keywords extracted from the page's keywords meta tag. + */ + keywords?: Array; + + /** + * Language extracted from html lang or language meta tags. + */ + language?: string; + + /** + * Modified timestamp/date from page metadata, when present. + */ + modifiedTime?: string; + + /** + * Open Graph metadata with the og: prefix removed and keys camel-cased. + */ + openGraph?: { [key: string]: string | Array }; + + /** + * Published timestamp/date from page metadata, when present. + */ + publishedTime?: string; + + /** + * Robots meta directive, when present. + */ + robots?: string; + + /** + * Site or application name from page metadata. + */ + siteName?: string; + + /** + * Best title extracted from the page. + */ + title?: string; + + /** + * Twitter card metadata with the twitter: prefix removed and keys camel-cased. + */ + twitter?: { [key: string]: string | Array }; + } + + export namespace Metadata { + export interface Alternate { + /** + * Resolved alternate URL. + */ + href: string; + + /** + * Language or locale for the alternate URL, when present. + */ + hreflang?: string; + + /** + * Alternate resource title, when present. + */ + title?: string; + + /** + * Alternate resource MIME type, when present. + */ + type?: string; + } + + export interface Heading { + /** + * Heading level, 1–6 (from h1–h6). + */ + level: number; + + /** + * Heading text with whitespace collapsed, truncated to 1000 characters. + */ + text: string; + } + } + + /** + * Fields produced by parseParams.rules, after shared content filters. + */ + export interface Parsed { + data: { [key: string]: unknown } | null; + + requested: boolean; + } + + /** + * An image data URL. Use directly as an image src. + */ + export interface Screenshot { + data: string | null; + + requested: boolean; + } + + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + export interface WebScreenshotResponse { /** * Cache outcome for this response. Composite responses are hits only when every @@ -3269,6 +3617,344 @@ export namespace WebExtractStyleguideParams { } } +export interface WebScrapeParams { + /** + * Outputs to return. Enable at least one; omitted formats are false. + */ + formats: WebScrapeParams.Formats; + + /** + * The URL to scrape. + */ + url: string; + + /** + * Image options. Requires formats.images: true. + */ + imageParams?: WebScrapeParams.ImageParams; + + /** + * Markdown options. Requires formats.markdown: true. + */ + markdownParams?: WebScrapeParams.MarkdownParams; + + /** + * Maximum age for the entire capture, including bytes. Defaults to 1 day; 0 + * fetches fresh. Captures with hosted image files refresh after 23 hours. + */ + maxAgeMs?: number; + + /** + * Required when formats.parse is true. + */ + parseParams?: WebScrapeParams.ParseParams; + + /** + * Screenshot options. Requires formats.screenshot: true. + */ + screenshotParams?: WebScrapeParams.ScreenshotParams; + + /** + * Shared browser and content settings. Content filters leave screenshots and + * original bytes unchanged. + */ + sharedParams?: WebScrapeParams.SharedParams; + + /** + * Labels for tracking request usage. Not retained when zdr is enabled. + */ + tags?: Array; + + /** + * Total deadline, including navigation, actions, waiting, and all outputs. + */ + timeoutMs?: number; + + /** + * Zero data retention. Bypasses caches and uploads; excludes request/response + * content and tags from logs. Must be enabled for your organization. + */ + zdr?: 'enabled' | 'disabled'; +} + +export namespace WebScrapeParams { + /** + * Outputs to return. Enable at least one; omitted formats are false. + */ + export interface Formats { + /** + * The original HTTP response body. + */ + bytes?: boolean; + + /** + * Rendered HTML. + */ + html?: boolean; + + /** + * Images found on the page. + */ + images?: boolean; + + /** + * Page content as Markdown. + */ + markdown?: boolean; + + /** + * Fields selected by parseParams.rules. + */ + parse?: boolean; + + /** + * An inline image of the page. + */ + screenshot?: boolean; + } + + /** + * Image options. Requires formats.images: true. + */ + export interface ImageParams { + /** + * For visual duplicates, keep the largest image. + */ + dedupe?: 'none' | 'visual'; + + /** + * Add dimensions, a visual category, or a hosted file URL. + */ + enrich?: Array<'dimensions' | 'classification' | 'file'>; + } + + /** + * Markdown options. Requires formats.markdown: true. + */ + export interface MarkdownParams { + includeImages?: boolean; + + includeLinks?: boolean; + + /** + * Base64 images use placeholders by default. Requires includeImages: true. + */ + inlineImages?: 'placeholder' | 'preserve'; + } + + /** + * Required when formats.parse is true. + */ + export interface ParseParams { + /** + * Map field names to CSS selectors or rules. Missing items return null; missing + * lists return []. + */ + rules: { [key: string]: string | ParseParams.UnionMember1 }; + } + + export namespace ParseParams { + export interface UnionMember1 { + selector: string; + + output?: 'text' | 'html' | string | unknown; + + type?: 'item' | 'list'; + } + } + + /** + * Screenshot options. Requires formats.screenshot: true. + */ + export interface ScreenshotParams { + /** + * Viewport, full page, one visible element, or a rectangle. Maximum 40 megapixels. + */ + area?: 'viewport' | 'fullPage' | ScreenshotParams.Element | ScreenshotParams.Rectangle; + + format?: 'png' | 'jpeg' | 'webp'; + } + + export namespace ScreenshotParams { + export interface Element { + /** + * Must match one visible element. + */ + selector: string; + } + + /** + * Pixels from the document origin. + */ + export interface Rectangle { + height: number; + + width: number; + + x: number; + + y: number; + } + } + + /** + * Shared browser and content settings. Content filters leave screenshots and + * original bytes unchanged. + */ + export interface SharedParams { + /** + * Run in order before capture. A failed action fails the request. Bypasses + * caching. + */ + actions?: Array; + + /** + * Supported two-letter country code, case-insensitive. Applies to every output, + * including image downloads. + */ + country?: string; + + /** + * Dismiss cookie banners by accepting cookies before actions. + */ + dismissCookies?: boolean; + + /** + * Dismiss other popups before actions. + */ + dismissPopups?: boolean; + + /** + * Remove matching content. Exclusions win. + */ + excludeSelectors?: Array; + + /** + * Headers for the target origin. Requests with custom headers bypass caching. + */ + headers?: { [key: string]: string }; + + /** + * Include iframe content in extraction. Screenshots show visible frames + * regardless. + */ + includeFrames?: boolean; + + /** + * Keep matching content after mainContentOnly. + */ + includeSelectors?: Array; + + /** + * Keep only main content in HTML, Markdown, images, and parsed fields. + */ + mainContentOnly?: boolean; + + /** + * Document parsing options. + */ + parsers?: SharedParams.Parsers; + + /** + * Settle animations before capture. Defaults to true with screenshots, otherwise + * false. + */ + settleAnimations?: boolean; + + /** + * Override the browser color scheme. + */ + theme?: 'light' | 'dark'; + + /** + * Browser dimensions in pixels. + */ + viewport?: SharedParams.Viewport; + + /** + * After actions, wait this many milliseconds or until a CSS selector is visible. + * Defaults to 500 ms, or 2000 ms with frames or an XML URL. Set 0 to skip. + */ + waitFor?: number | string; + } + + export namespace SharedParams { + export interface Perform { + action: string; + + type: 'perform'; + } + + export interface Scroll { + type: 'scroll'; + + amount?: number | 'viewport' | 'max'; + + direction?: 'down' | 'up' | 'left' | 'right'; + + maxScrolls?: number; + + /** + * Scroll this container. Omit to scroll the page. + */ + selector?: string; + } + + export interface Wait { + milliseconds: number; + + type: 'wait'; + } + + export interface WaitFor { + selector: string; + + type: 'waitFor'; + } + + /** + * Document parsing options. + */ + export interface Parsers { + /** + * PDF text options for HTML, Markdown, and parsed fields. + */ + pdf?: Parsers.Pdf; + } + + export namespace Parsers { + /** + * PDF text options for HTML, Markdown, and parsed fields. + */ + export interface Pdf { + /** + * Last page to parse. Must be at least startPage. + */ + endPage?: number; + + /** + * Read text from scanned pages. + */ + ocr?: 'off' | 'auto'; + + /** + * First page to parse, starting at 1. + */ + startPage?: number; + } + } + + /** + * Browser dimensions in pixels. + */ + export interface Viewport { + height?: number; + + width?: number; + } + } +} + export interface WebScreenshotParams { /** * Optional parameter for comprehensive popup cleanup. If 'true', the browser @@ -6442,6 +7128,7 @@ export declare namespace Web { type WebExtractCompetitorsResponse as WebExtractCompetitorsResponse, type WebExtractFontsResponse as WebExtractFontsResponse, type WebExtractStyleguideResponse as WebExtractStyleguideResponse, + type WebScrapeResponse as WebScrapeResponse, type WebScreenshotResponse as WebScreenshotResponse, type WebSearchResponse as WebSearchResponse, type WebWebCrawlMdResponse as WebWebCrawlMdResponse, @@ -6456,6 +7143,7 @@ export declare namespace Web { type WebExtractCompetitorsParams as WebExtractCompetitorsParams, type WebExtractFontsParams as WebExtractFontsParams, type WebExtractStyleguideParams as WebExtractStyleguideParams, + type WebScrapeParams as WebScrapeParams, type WebScreenshotParams as WebScreenshotParams, type WebSearchParams as WebSearchParams, type WebWebCrawlMdParams as WebWebCrawlMdParams, diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index a30a369f..6990f8bf 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -169,6 +169,79 @@ describe('resource web', () => { ).rejects.toThrow(ContextDev.NotFoundError); }); + // Mock server tests are disabled + test.skip('scrape: only required params', async () => { + const responsePromise = client.web.scrape({ + formats: {}, + url: 'https://example.com', + }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('scrape: required and optional params', async () => { + const response = await client.web.scrape({ + formats: { + bytes: true, + html: true, + images: true, + markdown: true, + parse: true, + screenshot: true, + }, + url: 'https://example.com', + imageParams: { dedupe: 'none', enrich: ['dimensions'] }, + markdownParams: { + includeImages: true, + includeLinks: true, + inlineImages: 'placeholder', + }, + maxAgeMs: 0, + parseParams: { + rules: { + title: 'h1', + links: { + selector: 'a', + output: '@href', + type: 'list', + }, + }, + }, + screenshotParams: { area: 'viewport', format: 'png' }, + sharedParams: { + actions: [{ action: 'Click the product details tab', type: 'perform' }], + country: 'US', + dismissCookies: true, + dismissPopups: true, + excludeSelectors: ['P'], + headers: { 'Accept-Language': 'en-US' }, + includeFrames: true, + includeSelectors: ['P'], + mainContentOnly: true, + parsers: { + pdf: { + endPage: 1, + ocr: 'off', + startPage: 1, + }, + }, + settleAnimations: true, + theme: 'light', + viewport: { height: 240, width: 240 }, + waitFor: 500, + }, + tags: ['production', 'team-alpha'], + timeoutMs: 1, + zdr: 'enabled', + }); + }); + // Mock server tests are disabled test.skip('screenshot', async () => { const responsePromise = client.web.screenshot(); From 57dd03dd18f93840faf239efdaeeca8a8f6fbaec Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 21 Sep 2026 22:46:59 +0000 Subject: [PATCH 064/232] fix(scrape): reuse legacy caches across all output formats (#1197) Stainless-Generated-From: 67cfb5cd751fdfce06c38a9583e89115252921f2 --- src/resources/web.ts | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 283baeb2..35b85abf 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -100,11 +100,14 @@ export class Web extends APIResource { } /** - * Capture the requested formats from one page visit. Shared settings apply once. - * HTML-only requests use the existing fast acquisition path. One credit per - * capture, or two with browser actions; PDF OCR adds one credit per recovered - * page. Original response bytes and screenshots are limited to 20 MiB each, - * screenshots to 40 megapixels, and the combined browser capture to 60 MiB. + * Reuse cached outputs independently and capture missing formats in one page + * visit. Each cache key includes only the settings that affect that output. HTML + * is shared with Markdown and parsed fields. Cached outputs can come from + * different visits within maxAgeMs; use 0 for a fresh capture. HTML-only requests + * use the existing fast acquisition path. One credit per request, including cache + * hits, or two with browser actions; PDF OCR adds one credit per recovered page on + * fresh extraction. Original response bytes and screenshots are limited to 20 MiB + * each, screenshots to 40 megapixels, and the combined browser capture to 60 MiB. * * @example * ```ts @@ -3639,8 +3642,10 @@ export interface WebScrapeParams { markdownParams?: WebScrapeParams.MarkdownParams; /** - * Maximum age for the entire capture, including bytes. Defaults to 1 day; 0 - * fetches fresh. Captures with hosted image files refresh after 23 hours. + * Maximum age of each cached output. Defaults to 1 day; 0 fetches fresh and + * updates the requested outputs. Compatible outputs are shared with the individual + * scrape endpoints. Image results with hosted files refresh after 23 hours; other + * outputs retain their own freshness. */ maxAgeMs?: number; From 67cfb5cd751fdfce06c38a9583e89115252921f2 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 21 Sep 2026 22:46:59 +0000 Subject: [PATCH 065/232] seal --- src/resources/web.ts | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 283baeb2..35b85abf 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -100,11 +100,14 @@ export class Web extends APIResource { } /** - * Capture the requested formats from one page visit. Shared settings apply once. - * HTML-only requests use the existing fast acquisition path. One credit per - * capture, or two with browser actions; PDF OCR adds one credit per recovered - * page. Original response bytes and screenshots are limited to 20 MiB each, - * screenshots to 40 megapixels, and the combined browser capture to 60 MiB. + * Reuse cached outputs independently and capture missing formats in one page + * visit. Each cache key includes only the settings that affect that output. HTML + * is shared with Markdown and parsed fields. Cached outputs can come from + * different visits within maxAgeMs; use 0 for a fresh capture. HTML-only requests + * use the existing fast acquisition path. One credit per request, including cache + * hits, or two with browser actions; PDF OCR adds one credit per recovered page on + * fresh extraction. Original response bytes and screenshots are limited to 20 MiB + * each, screenshots to 40 megapixels, and the combined browser capture to 60 MiB. * * @example * ```ts @@ -3639,8 +3642,10 @@ export interface WebScrapeParams { markdownParams?: WebScrapeParams.MarkdownParams; /** - * Maximum age for the entire capture, including bytes. Defaults to 1 day; 0 - * fetches fresh. Captures with hosted image files refresh after 23 hours. + * Maximum age of each cached output. Defaults to 1 day; 0 fetches fresh and + * updates the requested outputs. Compatible outputs are shared with the individual + * scrape endpoints. Image results with hosted files refresh after 23 hours; other + * outputs retain their own freshness. */ maxAgeMs?: number; From bb950e714a482b50d540a8abceea92fddf3e6678 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 22 Sep 2026 06:30:02 +0000 Subject: [PATCH 066/232] feat(scrape): align timeout options and public SDK methods (#1207) Stainless-Generated-From: 3ded9dc0f8665d46c239d03eb1d7f85661699a5a --- .stats.yml | 2 +- api.md | 36 +- src/client.ts | 63 +- src/resources/ai.ts | 615 --- src/resources/brand.ts | 317 -- src/resources/index.ts | 30 +- src/resources/monitors.ts | 494 +++ src/resources/web.ts | 5530 +++++--------------------- tests/api-resources/ai.test.ts | 56 - tests/api-resources/brand.test.ts | 23 - tests/api-resources/monitors.test.ts | 29 + tests/api-resources/web.test.ts | 298 +- 12 files changed, 1561 insertions(+), 5932 deletions(-) delete mode 100644 src/resources/ai.ts delete mode 100644 tests/api-resources/ai.test.ts diff --git a/.stats.yml b/.stats.yml index c550abf3..48f88c43 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 51 +configured_endpoints: 43 diff --git a/api.md b/api.md index ec2596eb..c9330f41 100644 --- a/api.md +++ b/api.md @@ -13,63 +13,35 @@ Methods: Types: - WebAnswersResponse -- WebExtractResponse - WebExtractCompetitorsResponse -- WebExtractFontsResponse - WebExtractStyleguideResponse +- WebMapURLsResponse - WebScrapeResponse - WebScreenshotResponse - WebSearchResponse - WebWebCrawlMdResponse -- WebWebScrapeBytesResponse -- WebWebScrapeHTMLResponse -- WebWebScrapeImagesResponse -- WebWebScrapeMdResponse -- WebWebScrapeScreenshotResponse -- WebWebScrapeSitemapResponse Methods: - client.web.answers({ ...params }) -> WebAnswersResponse -- client.web.extract({ ...params }) -> WebExtractResponse - client.web.extractCompetitors({ ...params }) -> WebExtractCompetitorsResponse -- client.web.extractFonts({ ...params }) -> WebExtractFontsResponse - client.web.extractStyleguide({ ...params }) -> WebExtractStyleguideResponse +- client.web.mapUrls({ ...params }) -> WebMapURLsResponse - client.web.scrape({ ...params }) -> WebScrapeResponse - client.web.screenshot({ ...params }) -> WebScreenshotResponse - client.web.search({ ...params }) -> WebSearchResponse - client.web.webCrawlMd({ ...params }) -> WebWebCrawlMdResponse -- client.web.webScrapeBytes({ ...params }) -> WebWebScrapeBytesResponse -- client.web.webScrapeHTML({ ...params }) -> WebWebScrapeHTMLResponse -- client.web.webScrapeImages({ ...params }) -> WebWebScrapeImagesResponse -- client.web.webScrapeMd({ ...params }) -> WebWebScrapeMdResponse -- client.web.webScrapeScreenshot({ ...params }) -> WebWebScrapeScreenshotResponse -- client.web.webScrapeSitemap({ ...params }) -> WebWebScrapeSitemapResponse - -# AI - -Types: - -- AIExtractProductResponse -- AIExtractProductsResponse - -Methods: - -- client.ai.extractProduct({ ...params }) -> AIExtractProductResponse -- client.ai.extractProducts({ ...params }) -> AIExtractProductsResponse # Brand Types: - BrandRetrieveResponse -- BrandRetrieveSimplifiedResponse - BrandSearchResponse Methods: - client.brand.retrieve({ ...params }) -> BrandRetrieveResponse -- client.brand.retrieveSimplified({ ...params }) -> BrandRetrieveSimplifiedResponse - client.brand.search({ ...params }) -> BrandSearchResponse # Industry @@ -111,6 +83,8 @@ Types: - MonitorListChangesResponse - MonitorListRunsResponse - MonitorRetrieveChangeResponse +- MonitorRetrieveRunResponse +- MonitorRotateWebhookSecretResponse - MonitorRunResponse Methods: @@ -127,6 +101,8 @@ Methods: - client.monitors.listChanges(monitorID, { ...params }) -> MonitorListChangesResponse - client.monitors.listRuns(monitorID, { ...params }) -> MonitorListRunsResponse - client.monitors.retrieveChange(changeID) -> MonitorRetrieveChangeResponse +- client.monitors.retrieveRun(runID, { ...params }) -> MonitorRetrieveRunResponse +- client.monitors.rotateWebhookSecret(monitorID) -> MonitorRotateWebhookSecretResponse - client.monitors.run(monitorID) -> MonitorRunResponse # Batch diff --git a/src/client.ts b/src/client.ts index b8568076..d76ce6da 100644 --- a/src/client.ts +++ b/src/client.ts @@ -17,13 +17,6 @@ import * as Errors from './core/error'; import * as Uploads from './core/uploads'; import * as API from './resources/index'; import { APIPromise } from './core/api-promise'; -import { - AI, - AIExtractProductParams, - AIExtractProductResponse, - AIExtractProductsParams, - AIExtractProductsResponse, -} from './resources/ai'; import { Batch, BatchCancelResponse, @@ -44,8 +37,6 @@ import { Brand, BrandRetrieveParams, BrandRetrieveResponse, - BrandRetrieveSimplifiedParams, - BrandRetrieveSimplifiedResponse, BrandSearchParams, BrandSearchResponse, } from './resources/brand'; @@ -76,6 +67,9 @@ import { MonitorListRunsResponse, MonitorRetrieveChangeResponse, MonitorRetrieveResponse, + MonitorRetrieveRunParams, + MonitorRetrieveRunResponse, + MonitorRotateWebhookSecretResponse, MonitorRunResponse, MonitorUpdateParams, MonitorUpdateResponse, @@ -92,12 +86,10 @@ import { WebAnswersResponse, WebExtractCompetitorsParams, WebExtractCompetitorsResponse, - WebExtractFontsParams, - WebExtractFontsResponse, - WebExtractParams, - WebExtractResponse, WebExtractStyleguideParams, WebExtractStyleguideResponse, + WebMapURLsParams, + WebMapURLsResponse, WebScrapeParams, WebScrapeResponse, WebScreenshotParams, @@ -106,18 +98,6 @@ import { WebSearchResponse, WebWebCrawlMdParams, WebWebCrawlMdResponse, - WebWebScrapeBytesParams, - WebWebScrapeBytesResponse, - WebWebScrapeHTMLParams, - WebWebScrapeHTMLResponse, - WebWebScrapeImagesParams, - WebWebScrapeImagesResponse, - WebWebScrapeMdParams, - WebWebScrapeMdResponse, - WebWebScrapeScreenshotParams, - WebWebScrapeScreenshotResponse, - WebWebScrapeSitemapParams, - WebWebScrapeSitemapResponse, } from './resources/web'; import { RetryConfig, Webhooks } from './resources/webhooks/webhooks'; import { type Fetch } from './internal/builtin-types'; @@ -839,7 +819,6 @@ export class ContextDev { parse: API.Parse = new API.Parse(this); web: API.Web = new API.Web(this); - ai: API.AI = new API.AI(this); brand: API.Brand = new API.Brand(this); industry: API.Industry = new API.Industry(this); utility: API.Utility = new API.Utility(this); @@ -865,7 +844,6 @@ export class ContextDev { ContextDev.Parse = Parse; ContextDev.Web = Web; -ContextDev.AI = AI; ContextDev.Brand = Brand; ContextDev.Industry = Industry; ContextDev.Utility = Utility; @@ -888,52 +866,28 @@ export declare namespace ContextDev { export { Web as Web, type WebAnswersResponse as WebAnswersResponse, - type WebExtractResponse as WebExtractResponse, type WebExtractCompetitorsResponse as WebExtractCompetitorsResponse, - type WebExtractFontsResponse as WebExtractFontsResponse, type WebExtractStyleguideResponse as WebExtractStyleguideResponse, + type WebMapURLsResponse as WebMapURLsResponse, type WebScrapeResponse as WebScrapeResponse, type WebScreenshotResponse as WebScreenshotResponse, type WebSearchResponse as WebSearchResponse, type WebWebCrawlMdResponse as WebWebCrawlMdResponse, - type WebWebScrapeBytesResponse as WebWebScrapeBytesResponse, - type WebWebScrapeHTMLResponse as WebWebScrapeHTMLResponse, - type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, - type WebWebScrapeMdResponse as WebWebScrapeMdResponse, - type WebWebScrapeScreenshotResponse as WebWebScrapeScreenshotResponse, - type WebWebScrapeSitemapResponse as WebWebScrapeSitemapResponse, type WebAnswersParams as WebAnswersParams, - type WebExtractParams as WebExtractParams, type WebExtractCompetitorsParams as WebExtractCompetitorsParams, - type WebExtractFontsParams as WebExtractFontsParams, type WebExtractStyleguideParams as WebExtractStyleguideParams, + type WebMapURLsParams as WebMapURLsParams, type WebScrapeParams as WebScrapeParams, type WebScreenshotParams as WebScreenshotParams, type WebSearchParams as WebSearchParams, type WebWebCrawlMdParams as WebWebCrawlMdParams, - type WebWebScrapeBytesParams as WebWebScrapeBytesParams, - type WebWebScrapeHTMLParams as WebWebScrapeHTMLParams, - type WebWebScrapeImagesParams as WebWebScrapeImagesParams, - type WebWebScrapeMdParams as WebWebScrapeMdParams, - type WebWebScrapeScreenshotParams as WebWebScrapeScreenshotParams, - type WebWebScrapeSitemapParams as WebWebScrapeSitemapParams, - }; - - export { - AI as AI, - type AIExtractProductResponse as AIExtractProductResponse, - type AIExtractProductsResponse as AIExtractProductsResponse, - type AIExtractProductParams as AIExtractProductParams, - type AIExtractProductsParams as AIExtractProductsParams, }; export { Brand as Brand, type BrandRetrieveResponse as BrandRetrieveResponse, - type BrandRetrieveSimplifiedResponse as BrandRetrieveSimplifiedResponse, type BrandSearchResponse as BrandSearchResponse, type BrandRetrieveParams as BrandRetrieveParams, - type BrandRetrieveSimplifiedParams as BrandRetrieveSimplifiedParams, type BrandSearchParams as BrandSearchParams, }; @@ -966,6 +920,8 @@ export declare namespace ContextDev { type MonitorListChangesResponse as MonitorListChangesResponse, type MonitorListRunsResponse as MonitorListRunsResponse, type MonitorRetrieveChangeResponse as MonitorRetrieveChangeResponse, + type MonitorRetrieveRunResponse as MonitorRetrieveRunResponse, + type MonitorRotateWebhookSecretResponse as MonitorRotateWebhookSecretResponse, type MonitorRunResponse as MonitorRunResponse, type MonitorCreateParams as MonitorCreateParams, type MonitorUpdateParams as MonitorUpdateParams, @@ -975,6 +931,7 @@ export declare namespace ContextDev { type MonitorListAccountRunsParams as MonitorListAccountRunsParams, type MonitorListChangesParams as MonitorListChangesParams, type MonitorListRunsParams as MonitorListRunsParams, + type MonitorRetrieveRunParams as MonitorRetrieveRunParams, }; export { diff --git a/src/resources/ai.ts b/src/resources/ai.ts deleted file mode 100644 index 079505f4..00000000 --- a/src/resources/ai.ts +++ /dev/null @@ -1,615 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { APIResource } from '../core/resource'; -import { APIPromise } from '../core/api-promise'; -import { RequestOptions } from '../internal/request-options'; - -export class AI extends APIResource { - /** - * Given a single URL, determines if it is a product page and extracts the product - * information. - * - * @example - * ```ts - * const response = await client.ai.extractProduct({ - * url: 'https://example.com', - * }); - * ``` - */ - extractProduct( - body: AIExtractProductParams, - options?: RequestOptions, - ): APIPromise { - return this._client.post('/brand/ai/product', { body, ...options }); - } - - /** - * Extract product information from a brand's website. We will analyze the website - * and return a list of products with details such as name, description, image, - * pricing, features, and more. - * - * @example - * ```ts - * const response = await client.ai.extractProducts({ - * domain: 'domain', - * }); - * ``` - */ - extractProducts( - body: AIExtractProductsParams, - options?: RequestOptions, - ): APIPromise { - return this._client.post('/brand/ai/products', { body, ...options }); - } -} - -export interface AIExtractProductResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: AIExtractProductResponse.CacheMetadata; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Whether the given URL is a product detail page - */ - is_product_page?: boolean; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: AIExtractProductResponse.KeyMetadata; - - /** - * True when the timeout ended processing and this response contains only usable - * results completed so far. Unfinished results are omitted. - */ - partial?: boolean; - - /** - * The detected ecommerce platform, or null if not a product page - */ - platform?: 'amazon' | 'tiktok_shop' | 'etsy' | 'generic' | null; - - /** - * The extracted product data, or null if not a product page - */ - product?: AIExtractProductResponse.Product | null; -} - -export namespace AIExtractProductResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } - - /** - * The extracted product data, or null if not a product page - */ - export interface Product { - /** - * Description of the product - */ - description: string; - - /** - * List of product features - */ - features: Array; - - /** - * URLs to product images on the page (up to 7) - */ - images: Array; - - /** - * Name of the product - */ - name: string; - - /** - * Stock Keeping Unit (product identifier). Null if no identifier is found. - */ - sku: string | null; - - /** - * Tags associated with the product - */ - tags: Array; - - /** - * Target audience for the product (array of strings) - */ - target_audience: Array; - - /** - * Normalized stock or ordering availability - */ - availability?: - | 'in_stock' - | 'out_of_stock' - | 'limited_availability' - | 'preorder' - | 'backorder' - | 'made_to_order' - | 'discontinued' - | null; - - /** - * Billing frequency for the product - */ - billing_frequency?: 'monthly' | 'yearly' | 'one_time' | 'usage_based' | null; - - /** - * Category of the product - */ - category?: string | null; - - /** - * Currency code for the price (e.g., USD, EUR) - */ - currency?: string | null; - - /** - * Dimension statements shown for the product, preserving labels, values, and units - */ - dimensions?: Array; - - /** - * URL to the product image - */ - image_url?: string | null; - - /** - * Price of the product - */ - price?: number | null; - - /** - * Pricing model for the product - */ - pricing_model?: 'per_seat' | 'flat' | 'tiered' | 'freemium' | 'custom' | null; - - /** - * Original or regular price before a displayed discount - */ - regular_price?: number | null; - - /** - * URL to the product page - */ - url?: string | null; - - /** - * Product variations, such as different colors or sizes, with their attributes and - * images. Empty if none are found. May not include every variation offered by the - * store. - */ - variants?: Array; - } - - export namespace Product { - export interface Variant { - /** - * Explicit variant attributes such as color, size, material, pattern and - * properties declared by page. - */ - attributes: { [key: string]: string }; - - /** - * Original source image URLs explicitly attached to this variant. - */ - images: Array; - - sku: string | null; - - /** - * Variant or offer URL when provided by the source. May be shared by variants. - */ - url: string | null; - } - } -} - -export interface AIExtractProductsResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: AIExtractProductsResponse.CacheMetadata; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: AIExtractProductsResponse.KeyMetadata; - - /** - * True when timeoutOpts.behavior=return-partial returned the usable results - * collected before the deadline. Partial collections are not cached as complete - * results. - */ - partial?: boolean; - - /** - * Array of products extracted from the website - */ - products?: Array; -} - -export namespace AIExtractProductsResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } - - export interface Product { - /** - * Description of the product - */ - description: string; - - /** - * List of product features - */ - features: Array; - - /** - * URLs to product images on the page (up to 7) - */ - images: Array; - - /** - * Name of the product - */ - name: string; - - /** - * Stock Keeping Unit (product identifier). Null if no identifier is found. - */ - sku: string | null; - - /** - * Tags associated with the product - */ - tags: Array; - - /** - * Target audience for the product (array of strings) - */ - target_audience: Array; - - /** - * Normalized stock or ordering availability - */ - availability?: - | 'in_stock' - | 'out_of_stock' - | 'limited_availability' - | 'preorder' - | 'backorder' - | 'made_to_order' - | 'discontinued' - | null; - - /** - * Billing frequency for the product - */ - billing_frequency?: 'monthly' | 'yearly' | 'one_time' | 'usage_based' | null; - - /** - * Category of the product - */ - category?: string | null; - - /** - * Currency code for the price (e.g., USD, EUR) - */ - currency?: string | null; - - /** - * Dimension statements shown for the product, preserving labels, values, and units - */ - dimensions?: Array; - - /** - * URL to the product image - */ - image_url?: string | null; - - /** - * Price of the product - */ - price?: number | null; - - /** - * Pricing model for the product - */ - pricing_model?: 'per_seat' | 'flat' | 'tiered' | 'freemium' | 'custom' | null; - - /** - * Original or regular price before a displayed discount - */ - regular_price?: number | null; - - /** - * URL to the product page - */ - url?: string | null; - - /** - * Product variations, such as different colors or sizes, with their attributes and - * images. Empty if none are found. May not include every variation offered by the - * store. - */ - variants?: Array; - } - - export namespace Product { - export interface Variant { - /** - * Explicit variant attributes such as color, size, material, pattern and - * properties declared by page. - */ - attributes: { [key: string]: string }; - - /** - * Original source image URLs explicitly attached to this variant. - */ - images: Array; - - sku: string | null; - - /** - * Variant or offer URL when provided by the source. May be shared by variants. - */ - url: string | null; - } - } -} - -export interface AIExtractProductParams { - /** - * The product page URL to extract product data from. - */ - url: string; - - /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 7 days (604800000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. - */ - maxAgeMs?: number; - - /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: AIExtractProductParams.TimeoutOpts; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace AIExtractProductParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export type AIExtractProductsParams = AIExtractProductsParams.ByDomain | AIExtractProductsParams.ByDirectURL; - -export declare namespace AIExtractProductsParams { - export interface ByDomain { - /** - * The domain name to analyze. - */ - domain: string; - - /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 7 days (604800000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. - */ - maxAgeMs?: number; - - /** - * Maximum number of products to extract. - */ - maxProducts?: number; - - /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: ByDomain.TimeoutOpts; - } - - export namespace ByDomain { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } - } - - export interface ByDirectURL { - /** - * A specific URL to use directly as the starting point for extraction without - * domain resolution. - */ - directUrl: string; - - /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 7 days (604800000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. - */ - maxAgeMs?: number; - - /** - * Maximum number of products to extract. - */ - maxProducts?: number; - - /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: ByDirectURL.TimeoutOpts; - } - - export namespace ByDirectURL { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } - } -} - -export declare namespace AI { - export { - type AIExtractProductResponse as AIExtractProductResponse, - type AIExtractProductsResponse as AIExtractProductsResponse, - type AIExtractProductParams as AIExtractProductParams, - type AIExtractProductsParams as AIExtractProductsParams, - }; -} diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 11e94515..28b9c457 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -24,25 +24,6 @@ export class Brand extends APIResource { return this._client.post('/brand/retrieve', { body, ...options }); } - /** - * Returns a simplified version of brand data containing only essential - * information: domain, title, colors, logos, and backdrops. Optimized for faster - * responses and reduced data transfer. - * - * @example - * ```ts - * const response = await client.brand.retrieveSimplified({ - * domain: 'xxx', - * }); - * ``` - */ - retrieveSimplified( - query: BrandRetrieveSimplifiedParams, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/brand/retrieve-simplified', { query, ...options }); - } - /** * Search indexed brands by name or domain * @@ -906,247 +887,6 @@ export namespace BrandRetrieveResponse { } } -export interface BrandRetrieveSimplifiedResponse { - /** - * Simplified brand information - */ - brand: BrandRetrieveSimplifiedResponse.Brand; - - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: BrandRetrieveSimplifiedResponse.CacheMetadata; - - /** - * HTTP status code of the response - */ - code: number; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Status of the response, e.g., 'ok' - */ - status: string; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: BrandRetrieveSimplifiedResponse.KeyMetadata; - - /** - * True when the timeout ended processing and only completed brand data is - * returned. - */ - partial?: boolean; -} - -export namespace BrandRetrieveSimplifiedResponse { - /** - * Simplified brand information - */ - export interface Brand { - /** - * An array of backdrop images for the brand - */ - backdrops?: Array; - - /** - * An array of brand colors - */ - colors?: Array; - - /** - * The domain name of the brand - */ - domain?: string; - - /** - * An array of logos associated with the brand - */ - logos?: Array; - - /** - * The title or name of the brand - */ - title?: string; - } - - export namespace Brand { - export interface Backdrop { - /** - * Array of colors in the backdrop image - */ - colors?: Array; - - /** - * Resolution of the backdrop image - */ - resolution?: Backdrop.Resolution; - - /** - * URL of the backdrop image - */ - url?: string; - } - - export namespace Backdrop { - export interface Color { - /** - * Color in hexadecimal format - */ - hex?: string; - - /** - * Name of the color - */ - name?: string; - } - - /** - * Resolution of the backdrop image - */ - export interface Resolution { - /** - * Aspect ratio of the image (width/height) - */ - aspect_ratio?: number; - - /** - * Height of the image in pixels - */ - height?: number; - - /** - * Width of the image in pixels - */ - width?: number; - } - } - - export interface Color { - /** - * Color in hexadecimal format - */ - hex?: string; - - /** - * Name of the color - */ - name?: string; - - /** - * Where the color was observed: 'site' colors come from the website's own theme - * signals (rendered page colors, manifest, theme-color meta), 'logo' colors from - * logo image pixels. - */ - source?: 'site' | 'logo'; - } - - export interface Logo { - /** - * Array of colors in the logo - */ - colors?: Array; - - /** - * Indicates when this logo is best used: 'light' = best for light mode, 'dark' = - * best for dark mode, 'has_opaque_background' = can be used for either as image - * has its own background - */ - mode?: 'light' | 'dark' | 'has_opaque_background'; - - /** - * Resolution of the logo image - */ - resolution?: Logo.Resolution; - - /** - * Type of the logo based on resolution (e.g., 'icon', 'logo') - */ - type?: 'icon' | 'logo'; - - /** - * CDN hosted url of the logo (ready for display) - */ - url?: string; - } - - export namespace Logo { - export interface Color { - /** - * Color in hexadecimal format - */ - hex?: string; - - /** - * Name of the color - */ - name?: string; - } - - /** - * Resolution of the logo image - */ - export interface Resolution { - /** - * Aspect ratio of the image (width/height) - */ - aspect_ratio?: number; - - /** - * Height of the image in pixels - */ - height?: number; - - /** - * Width of the image in pixels - */ - width?: number; - } - } - } - - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - export interface BrandSearchResponse { /** * Unique id of this API call, also sent in the X-Request-Id response header. Quote @@ -2210,61 +1950,6 @@ export declare namespace BrandRetrieveParams { } } -export interface BrandRetrieveSimplifiedParams { - /** - * Domain name to retrieve simplified brand data for - */ - domain: string; - - /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. - */ - maxAgeMs?: number | null; - - /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. - */ - tags?: Array; - - /** - * Optional theme preference used when selecting brand assets. - */ - theme?: 'light' | 'dark'; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: BrandRetrieveSimplifiedParams.TimeoutOpts; -} - -export namespace BrandRetrieveSimplifiedParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } -} - export interface BrandSearchParams { /** * Search term, matched against the fields selected by queryBy (e.g. 'nike', @@ -2300,10 +1985,8 @@ export interface BrandSearchParams { export declare namespace Brand { export { type BrandRetrieveResponse as BrandRetrieveResponse, - type BrandRetrieveSimplifiedResponse as BrandRetrieveSimplifiedResponse, type BrandSearchResponse as BrandSearchResponse, type BrandRetrieveParams as BrandRetrieveParams, - type BrandRetrieveSimplifiedParams as BrandRetrieveSimplifiedParams, type BrandSearchParams as BrandSearchParams, }; } diff --git a/src/resources/index.ts b/src/resources/index.ts index 3628f91f..17ccfefe 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -1,12 +1,5 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -export { - AI, - type AIExtractProductResponse, - type AIExtractProductsResponse, - type AIExtractProductParams, - type AIExtractProductsParams, -} from './ai'; export { Batch, type PageErrorCount, @@ -26,10 +19,8 @@ export { export { Brand, type BrandRetrieveResponse, - type BrandRetrieveSimplifiedResponse, type BrandSearchResponse, type BrandRetrieveParams, - type BrandRetrieveSimplifiedParams, type BrandSearchParams, } from './brand'; export { @@ -55,6 +46,8 @@ export { type MonitorListChangesResponse, type MonitorListRunsResponse, type MonitorRetrieveChangeResponse, + type MonitorRetrieveRunResponse, + type MonitorRotateWebhookSecretResponse, type MonitorRunResponse, type MonitorCreateParams, type MonitorUpdateParams, @@ -64,6 +57,7 @@ export { type MonitorListAccountRunsParams, type MonitorListChangesParams, type MonitorListRunsParams, + type MonitorRetrieveRunParams, } from './monitors'; export { News, type NewsSearchResponse, type NewsSearchParams } from './news'; export { Parse, type ParseHandleResponse, type ParseHandleParams } from './parse'; @@ -72,34 +66,20 @@ export { Utility, type UtilityPrefetchResponse, type UtilityPrefetchParams } fro export { Web, type WebAnswersResponse, - type WebExtractResponse, type WebExtractCompetitorsResponse, - type WebExtractFontsResponse, type WebExtractStyleguideResponse, + type WebMapURLsResponse, type WebScrapeResponse, type WebScreenshotResponse, type WebSearchResponse, type WebWebCrawlMdResponse, - type WebWebScrapeBytesResponse, - type WebWebScrapeHTMLResponse, - type WebWebScrapeImagesResponse, - type WebWebScrapeMdResponse, - type WebWebScrapeScreenshotResponse, - type WebWebScrapeSitemapResponse, type WebAnswersParams, - type WebExtractParams, type WebExtractCompetitorsParams, - type WebExtractFontsParams, type WebExtractStyleguideParams, + type WebMapURLsParams, type WebScrapeParams, type WebScreenshotParams, type WebSearchParams, type WebWebCrawlMdParams, - type WebWebScrapeBytesParams, - type WebWebScrapeHTMLParams, - type WebWebScrapeImagesParams, - type WebWebScrapeMdParams, - type WebWebScrapeScreenshotParams, - type WebWebScrapeSitemapParams, } from './web'; export { Webhooks, type RetryConfig } from './webhooks/webhooks'; diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index ab847006..b54dd5bb 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -210,6 +210,46 @@ export class Monitors extends APIResource { return this._client.get(path`/monitors/changes/${changeID}`, options); } + /** + * Fetches one run for a monitor, including lifecycle status, timing, credits + * charged, and any detected change. + * + * @example + * ```ts + * const response = await client.monitors.retrieveRun( + * 'run_123', + * { monitor_id: 'mon_123' }, + * ); + * ``` + */ + retrieveRun( + runID: string, + params: MonitorRetrieveRunParams, + options?: RequestOptions, + ): APIPromise { + const { monitor_id } = params; + return this._client.get(path`/monitors/${monitor_id}/runs/${runID}`, options); + } + + /** + * Generates a new signing secret for the monitor's webhook and returns the updated + * monitor (including the new `webhook.secret`). The previous secret stops signing + * deliveries immediately, so update your endpoint before rotating. + * + * @example + * ```ts + * const response = await client.monitors.rotateWebhookSecret( + * 'mon_123', + * ); + * ``` + */ + rotateWebhookSecret( + monitorID: string, + options?: RequestOptions, + ): APIPromise { + return this._client.post(path`/monitors/${monitorID}/webhook/rotate-secret`, options); + } + /** * Triggers an immediate run of the monitor outside its normal schedule. The run is * queued and processed asynchronously. @@ -2200,6 +2240,453 @@ export namespace MonitorRetrieveChangeResponse { } } +export interface MonitorRetrieveRunResponse { + id: string; + + /** + * True when this run established the monitor's initial baseline; baseline runs + * perform no change detection. + */ + baseline_created: boolean; + + change_detected: boolean; + + change_detection_type: 'exact' | 'semantic'; + + /** + * Credits charged for this run (0 for skipped/failed runs). + */ + credits_charged: number; + + monitor_id: string; + + /** + * The first run after monitor creation is a baseline run. + */ + run_type: 'baseline' | 'scheduled'; + + /** + * Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` + * (insufficient credits, monitor paused, or superseded by a concurrent run). + */ + status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; + + target_type: 'page' | 'sitemap' | 'extract'; + + change_id?: string | null; + + completed_at?: string | null; + + error?: MonitorRetrieveRunResponse.Error | null; + + /** + * Why a skipped run never executed; null unless status is `skipped`. + */ + skip_reason?: 'insufficient_credits' | 'monitor_paused' | 'superseded' | null; + + started_at?: string | null; + + /** + * All webhook deliveries attempted by this run — one per subscribed event that + * fired. Omitted when no webhook was attempted, including runs created before + * event selection was added. + */ + webhook_deliveries?: Array; + + /** + * @deprecated Deprecated: use `webhook_deliveries`, which records every attempt + * now that a run can deliver multiple events. Omitted when no webhook was + * attempted, including historical runs created before delivery tracking was added. + */ + webhook_delivery?: WebhookDelivery; + + /** + * Webhook delivery IDs for this run. + */ + webhook_delivery_ids?: Array; +} + +export namespace MonitorRetrieveRunResponse { + export interface Error { + code: string; + + message: string; + } +} + +/** + * A web monitor. `mode` is the constant `web`; behavior is described by `target` + * (page/sitemap/extract) and `change_detection` (exact/semantic). + */ +export interface MonitorRotateWebhookSecretResponse { + id: string; + + /** + * Discriminated union describing how changes are detected. + */ + change_detection: + | MonitorRotateWebhookSecretResponse.MonitorsExactChangeDetection + | MonitorRotateWebhookSecretResponse.MonitorsSemanticChangeDetection; + + created_at: string; + + /** + * Top-level monitor category. Always `web` today; the concrete behavior is + * described by `target` and `change_detection`. + */ + mode: 'web'; + + name: string; + + /** + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + schedule: MonitorRotateWebhookSecretResponse.Schedule; + + /** + * Monitor lifecycle status. `failed` means the most recent run failed (see the + * monitor's `last_error`); failed monitors keep running on schedule and flip back + * to `active` on the next successful run. Monitors are auto-`paused` after + * repeated consecutive failures or insufficient-credit skips; resume by PATCHing + * status to `active`. + */ + status: 'active' | 'paused' | 'failed'; + + /** + * Discriminated union describing what the monitor watches. + */ + target: + | MonitorRotateWebhookSecretResponse.MonitorsPageTarget + | MonitorRotateWebhookSecretResponse.MonitorsSitemapTarget + | MonitorRotateWebhookSecretResponse.MonitorsExtractTarget; + + updated_at: string; + + /** + * Current baseline: the last observed value the monitor compares new snapshots + * against. Its shape follows `target.type` (page/sitemap/extract). Only populated + * on GET /monitors/{monitor_id}; null until the first baseline run completes (and + * after a target or change_detection update, which resets the baseline). + */ + baseline?: + | MonitorRotateWebhookSecretResponse.MonitorsPageBaseline + | MonitorRotateWebhookSecretResponse.MonitorsSitemapBaseline + | MonitorRotateWebhookSecretResponse.MonitorsExtractBaseline + | null; + + last_change_at?: string | null; + + /** + * Error from the most recent failed run; null when the last run succeeded. + */ + last_error?: MonitorRotateWebhookSecretResponse.LastError | null; + + last_run_at?: string | null; + + /** + * When the next scheduled run is due. + */ + next_run_at?: string | null; + + /** + * User-defined tags for grouping and filtering monitors and their changes. + * Duplicates are removed. + */ + tags?: Array; + + webhook?: MonitorRotateWebhookSecretResponse.Webhook | null; + + /** + * Present while webhook deliveries are failing consecutively; null when deliveries + * are healthy or no webhook is configured. Cleared on the next successful delivery + * and when the webhook URL changes. + */ + webhook_failure?: MonitorRotateWebhookSecretResponse.WebhookFailure | null; +} + +export namespace MonitorRotateWebhookSecretResponse { + /** + * Detect exact changes. For page targets, this means visible text diffs. For + * sitemap targets, this means URL additions and removals. + */ + export interface MonitorsExactChangeDetection { + type: 'exact'; + } + + /** + * Detect meaning-level changes to page content, ignoring cosmetic or + * instruction-irrelevant differences. Which changes are meaningful is judged + * against the page or extract target's `instructions` (and an extract target's + * `schema`, when provided). + */ + export interface MonitorsSemanticChangeDetection { + type: 'semantic'; + + confidence_threshold?: number; + } + + /** + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + export interface Schedule { + /** + * Number of units between runs. The resulting interval (frequency × unit) must be + * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; + * maximum 365 when unit is days). + */ + frequency: number; + + type: 'interval'; + + unit: 'minutes' | 'hours' | 'days'; + } + + /** + * Watch a single web page. Exact detection reports visible-text diffs; semantic + * detection judges confirmed stable diffs against `instructions`. + */ + export interface MonitorsPageTarget { + type: 'page'; + + url: string; + + /** + * CSS selectors for HTML regions to remove before text extraction. Applied after + * include_selectors; exclusion takes precedence when an element matches both. Omit + * or pass an empty array to apply no explicit exclusions. Changing these selectors + * creates a new baseline. + */ + exclude_selectors?: Array; + + /** + * CSS selectors defining the HTML regions to monitor. Matching subtrees are + * combined in document order before text extraction, instead of automatic + * main-content selection. Omit or pass an empty array to use automatic + * main-content extraction. If the filtered page has no usable text, the run fails + * without replacing the baseline. Changing these selectors creates a new baseline. + */ + include_selectors?: Array; + + /** + * Plain-language goal describing which page changes matter. When provided without + * change_detection, semantic detection is inferred. + */ + instructions?: string; + + /** + * Normalize whitespace before comparing or analyzing text. + */ + normalize_whitespace?: boolean; + } + + /** + * Watch a sitemap for URL additions and removals. Crawled URLs are normalized + * (lowercased host, no trailing slash/fragment) and scoped to the monitored site + * and its subdomains before comparison. On a detected difference the sitemap is + * re-fetched within the same run and only URLs both observations agree on are + * reported, suppressing transient crawl flaps. + */ + export interface MonitorsSitemapTarget { + type: 'sitemap'; + + /** + * Sitemap URL to monitor. + */ + url: string; + + /** + * URL path patterns to exclude (max 50). + */ + exclude?: Array; + + /** + * URL path patterns to include (max 50). + */ + include?: Array; + + /** + * Maximum number of sitemap URLs to track (capped at 10,000). + */ + max_urls?: number; + } + + /** + * Watch the monitor-relevant pages of a site for meaningful changes. A crawl + * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to + * track; each run re-checks exactly those pages, and confirmed content changes are + * judged for relevance against the monitor's `instructions` (and `schema`, when + * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + */ + export interface MonitorsExtractTarget { + /** + * Natural-language instructions guiding which pages and facts to track and which + * changes to report. + */ + instructions: string; + + type: 'extract'; + + /** + * Root URL to extract structured data from. + */ + url: string; + + follow_subdomains?: boolean; + + /** + * Optional maximum link depth from the starting URL (0 = only the starting page). + */ + max_depth?: number; + + /** + * Maximum number of pages to track. + */ + max_pages?: number; + + /** + * JSON Schema describing the data you care about. It is used three ways: it guides + * which pages are selected for tracking, it gives the change judge extra context + * on which changes matter (alongside `instructions`), and it defines the shape of + * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most + * about once a day). It is not a response format for changes: change events and + * webhook payloads always contain diffs, summaries, and evidence excerpts — never + * data in this schema's shape. If omitted, a default summary + key-points schema + * is used. + */ + schema?: { [key: string]: unknown }; + } + + /** + * Current baseline of a `page` monitor: the visible page text as last observed. + */ + export interface MonitorsPageBaseline { + /** + * When this baseline was last captured or replaced. + */ + captured_at: string; + + /** + * The page's visible text as last observed. + */ + text: string; + } + + /** + * Current baseline of a `sitemap` monitor: the normalized URL set as last + * observed. + */ + export interface MonitorsSitemapBaseline { + /** + * When this baseline was last captured or replaced. + */ + captured_at: string; + + /** + * Number of URLs in the baseline. + */ + url_count: number; + + /** + * The sitemap URLs as last observed (sorted, normalized). + */ + urls: Array; + } + + /** + * Current baseline of an `extract` monitor: the pages it tracks and the structured + * data as last extracted. + */ + export interface MonitorsExtractBaseline { + /** + * When this baseline was last captured or replaced. + */ + captured_at: string; + + /** + * The extracted structured data, matching the monitor's extraction schema (same + * shape as the /web/extract endpoint's `data`). Refreshed when the monitor + * re-discovers its page set (at most about once a day); `null` when no extraction + * has been captured yet. + */ + data: unknown; + + /** + * The page URLs the monitor tracks and analyzes for changes. + */ + urls_analyzed: Array; + } + + /** + * Error from the most recent failed run; null when the last run succeeded. + */ + export interface LastError { + code: string; + + message: string; + } + + export interface Webhook { + /** + * Webhook URL events are delivered to. Slack incoming webhook URLs are + * automatically formatted as Slack messages. + */ + url: string; + + /** + * Events delivered to this endpoint. `change.detected` fires only when a run + * detects a change; `run.completed` fires on every completed run — including runs + * that detected no change — and embeds the change when one was detected. Defaults + * to `["change.detected"]` when omitted. + */ + events?: Array<'change.detected' | 'run.completed'>; + + /** + * Webhook retry settings. Use {} for the default schedule. + */ + retry?: WebhooksAPI.RetryConfig; + + /** + * Signing secret used to verify webhook authenticity. Omitted unless the API key + * has monitors:write permission or full access. Each delivery includes an + * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over + * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time + * compare and reject stale timestamps to prevent replay. Generated by the API; + * cannot be set by clients. + */ + secret?: string; + } + + /** + * Present while webhook deliveries are failing consecutively; null when deliveries + * are healthy or no webhook is configured. Cleared on the next successful delivery + * and when the webhook URL changes. + */ + export interface WebhookFailure { + /** + * Number of consecutive delivery attempts that did not succeed. + */ + consecutive_failures: number; + + last_failed_at: string; + + /** + * Human-readable description of the most recent failure. + */ + last_message: string; + + /** + * Outcome of the most recent failed delivery. rejected means a non-2xx response; + * failed means no HTTP response was received; skipped_unsafe_url means the URL + * failed the public-endpoint safety check. + */ + last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; + } +} + export interface MonitorRunResponse { monitor_id: string; @@ -2815,6 +3302,10 @@ export interface MonitorListRunsParams { status?: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; } +export interface MonitorRetrieveRunParams { + monitor_id: string; +} + export declare namespace Monitors { export { type WebhookDelivery as WebhookDelivery, @@ -2830,6 +3321,8 @@ export declare namespace Monitors { type MonitorListChangesResponse as MonitorListChangesResponse, type MonitorListRunsResponse as MonitorListRunsResponse, type MonitorRetrieveChangeResponse as MonitorRetrieveChangeResponse, + type MonitorRetrieveRunResponse as MonitorRetrieveRunResponse, + type MonitorRotateWebhookSecretResponse as MonitorRotateWebhookSecretResponse, type MonitorRunResponse as MonitorRunResponse, type MonitorCreateParams as MonitorCreateParams, type MonitorUpdateParams as MonitorUpdateParams, @@ -2839,5 +3332,6 @@ export declare namespace Monitors { type MonitorListAccountRunsParams as MonitorListAccountRunsParams, type MonitorListChangesParams as MonitorListChangesParams, type MonitorListRunsParams as MonitorListRunsParams, + type MonitorRetrieveRunParams as MonitorRetrieveRunParams, }; } diff --git a/src/resources/web.ts b/src/resources/web.ts index 35b85abf..227beb57 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -28,27 +28,6 @@ export class Web extends APIResource { return this._client.post('/web/answers', { body, ...options }); } - /** - * Crawl a website, use the provided JSON Schema and instructions to prioritize - * relevant internal links, and extract structured data from the selected pages. - * - * @example - * ```ts - * const response = await client.web.extract({ - * schema: { - * type: 'bar', - * properties: 'bar', - * required: 'bar', - * additionalProperties: 'bar', - * }, - * url: 'https://example.com', - * }); - * ``` - */ - extract(body: WebExtractParams, options?: RequestOptions): APIPromise { - return this._client.post('/web/extract', { body, ...options }); - } - /** * Analyze a company's landing page and web search evidence to return direct * competitors for the same product or market. @@ -68,35 +47,40 @@ export class Web extends APIResource { } /** - * Scrape font information from a website including font families, usage - * statistics, fallbacks, and element/word counts. + * Extract a comprehensive design system from a website including colors, + * typography, spacing, shadows, and UI components. * * @example * ```ts - * const response = await client.web.extractFonts(); + * const response = await client.web.extractStyleguide(); * ``` */ - extractFonts( - query: WebExtractFontsParams | null | undefined = {}, + extractStyleguide( + query: WebExtractStyleguideParams | null | undefined = {}, options?: RequestOptions, - ): APIPromise { - return this._client.get('/web/fonts', { query, ...options }); + ): APIPromise { + return this._client.get('/web/styleguide', { query, ...options }); } /** - * Extract a comprehensive design system from a website including colors, - * typography, spacing, shadows, and UI components. + * Discovers URLs using the same sitemap crawl, filters, and limits as + * /web/scrape/sitemap. Each URL includes its available title, description, + * keywords, and language. URLs without stored enrichment are returned immediately + * with only the URL and queued for background HTML scraping, so later requests can + * include their metadata. Responses are never cached as a whole; every request + * reads the current per-URL enrichment. Zero data retention and credential-bearing + * discovery requests return URLs without reading or storing shared enrichment or + * queuing background scrapes. Costs 1 credit, or 2 credits with search. * * @example * ```ts - * const response = await client.web.extractStyleguide(); + * const response = await client.web.mapUrls({ + * domain: 'xxx', + * }); * ``` */ - extractStyleguide( - query: WebExtractStyleguideParams | null | undefined = {}, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/web/styleguide', { query, ...options }); + mapUrls(query: WebMapURLsParams, options?: RequestOptions): APIPromise { + return this._client.get('/web/urls', { query, ...options }); } /** @@ -162,172 +146,6 @@ export class Web extends APIResource { webCrawlMd(body: WebWebCrawlMdParams, options?: RequestOptions): APIPromise { return this._client.post('/web/crawl', { body, ...options }); } - - /** - * Downloads a resource and returns its bytes as base64. Without waitForMs, returns - * the original HTTP response without image conversion, text extraction, or - * character-encoding changes. HTTP compression is decoded before base64 encoding. - * Supply waitForMs to render HTML with JavaScript in the browser and return the - * resulting HTML as UTF-8 bytes after the wait. Non-HTML resources, including - * images and PDFs, keep their original bytes and do not incur a browser wait. - * Follows public redirects and retries failed downloads through ISP and - * residential proxies, with a direct fallback. When country is specified, only a - * residential proxy in that country is used. Supply headers such as Referer for - * images that require a referring page. Cached results are reused according to - * maxAgeMs (default: 1 day; maximum: 30 days). Set maxAgeMs=0 to fetch fresh and - * refresh the cache. Cache identity includes the exact URL, country, waitForMs, - * and normalized outbound headers. Credential-bearing headers and zero data - * retention bypass cache reads and writes. cache_metadata reports hit, miss, or - * zdr and the cached result age in milliseconds. Maximum decoded resource size: 20 - * MiB (20971520 bytes), before base64 encoding. Successful requests cost 1 credit; - * errors are not billed. - * - * @example - * ```ts - * const response = await client.web.webScrapeBytes({ - * url: 'https://example.com', - * }); - * ``` - */ - webScrapeBytes( - query: WebWebScrapeBytesParams, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/web/scrape/bytes', { query, ...options }); - } - - /** - * Scrapes the given URL and returns the HTML content of the page. Optional - * extractRules return deterministic structured data in extracted using CSS - * selectors, attributes, lists, and nested rules, without an LLM or additional - * credits. Rules run on the returned HTML after selector and main-content - * filtering. Send extractRules as a JSON-encoded query parameter. The base request - * costs 1 credit; requests with browser actions cost 2 credits. A request that - * hits its timeoutOpts.milliseconds deadline fails with 408 and is not billed, - * unless timeoutOpts.behavior=return-partial is set — then the page as rendered so - * far is returned with `finalDOMState: "still-loading"` and billed at the base - * cost of 1 credit. - * - * @example - * ```ts - * const response = await client.web.webScrapeHTML({ - * url: 'https://example.com', - * }); - * ``` - */ - webScrapeHTML( - query: WebWebScrapeHTMLParams, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/web/scrape/html', { query, ...options }); - } - - /** - * Extract image assets from a web page, including standard URLs, inline SVGs, data - * URIs, responsive image sources, metadata, CSS backgrounds, video posters, and - * embeds. The base request costs 1 credit, or 2 credits with browser actions. When - * enrichment is enabled, the entire call costs 5 credits, including requests that - * also use actions. - * - * @example - * ```ts - * const response = await client.web.webScrapeImages({ - * url: 'https://example.com', - * }); - * ``` - */ - webScrapeImages( - query: WebWebScrapeImagesParams, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/web/scrape/images', { query, ...options }); - } - - /** - * Scrapes the given URL into LLM usable Markdown. Inspect key_metadata on JSON - * responses from a recognized API key; use error_code to distinguish stable - * failure categories. - * - * ### YouTube - * - * YouTube URLs return the video or channel itself rather than the surrounding - * player and navigation chrome. A URL addressing a single video (`/watch`, - * `youtu.be`, `/shorts`, `/embed`, `/live`) returns its title, channel, duration, - * view count, keywords, full description, and the transcript when the video has - * captions that can be retrieved; videos without captions return everything except - * the transcript. A channel URL (`/channel/UC…`, `/@handle`, `/c/…`, `/user/…`) - * returns its name, handle, subscriber count, video count, and full description. - * When `includeImages=true`, video responses also include the thumbnail and - * channel responses include the avatar. Costs the same as any other scrape. - * - * ### Billing & errors - * - * | HTTP status | Billed? | Meaning | - * | ----------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - * | 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing. A partial result (`finalDOMState: "still-loading"`, only with timeoutOpts.behavior=return-partial) is billed at the base 1 credit with no OCR or actions surcharge | - * | 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds | - * | 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code | - * | 404 | Yes — 1 credit, or 2 credits with actions | Target page returned or fingerprinted as not found | - * | 408 | No | Request timed out. With timeoutOpts.behavior=return-partial this only happens when nothing usable had rendered by the deadline | - * | 413 | No | Target content exceeds the maximum supported size (20 MB) | - * | 415 | No | Unsupported content type | - * | 429 | No | Per-minute rate limit exceeded; honor Retry-After | - * | 500 | No | Internal error | - * - * @example - * ```ts - * const response = await client.web.webScrapeMd({ - * url: 'https://example.com', - * }); - * ``` - */ - webScrapeMd(query: WebWebScrapeMdParams, options?: RequestOptions): APIPromise { - return this._client.get('/web/scrape/markdown', { query, ...options }); - } - - /** - * Capture the given HTTP or HTTPS URL with configurable viewport, full-page - * capture, wait time, popup handling, theme, scroll offset, cache age, country, - * and request timeout. Defaults to a 1920x1080 viewport, a 3-second wait, and a - * cache age of 1 day. With timeoutOpts.behavior=return-partial, a screenshot of - * the page rendered so far may be returned; inspect finalDOMState to identify an - * incomplete render. Successful requests cost 1 credit; errors are not billed. - * - * @example - * ```ts - * const response = await client.web.webScrapeScreenshot({ - * url: 'https://example.com', - * }); - * ``` - */ - webScrapeScreenshot( - query: WebWebScrapeScreenshotParams, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/web/scrape/screenshot', { query, ...options }); - } - - /** - * Crawl an entire website's sitemap and return all discovered page URLs. Set - * `includeSubdomains=true` to also discover public pages and sitemaps on child - * hosts such as `docs.example.com` or `brand.example.com`. Pass `search` to have - * the discovered URLs filtered down to the pages about a phrase (for example - * `pricing and plans` or `api authentication docs`), most relevant first — a - * searched crawl scans the whole sitemap and costs 2 credits instead of 1. - * - * @example - * ```ts - * const response = await client.web.webScrapeSitemap({ - * domain: 'xxx', - * }); - * ``` - */ - webScrapeSitemap( - query: WebWebScrapeSitemapParams, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/web/scrape/sitemap', { query, ...options }); - } } export interface WebAnswersResponse { @@ -371,137 +189,6 @@ export namespace WebAnswersResponse { } } -export interface WebExtractResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: WebExtractResponse.CacheMetadata; - - /** - * Extracted data matching the request schema - */ - data: { [key: string]: unknown }; - - metadata: WebExtractResponse.Metadata; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Status of the response, e.g., 'ok' - */ - status: string; - - /** - * The starting URL that was analyzed - */ - url: string; - - /** - * List of URLs whose Markdown was used for extraction - */ - urls_analyzed: Array; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: WebExtractResponse.KeyMetadata; - - /** - * True when the timeout ended processing and this response contains only usable - * results completed so far. Unfinished results are omitted. - */ - partial?: boolean; -} - -export namespace WebExtractResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - export interface Metadata { - maxCrawlDepth: number; - - /** - * Number of crawled pages excluded because they were anti-bot challenges, error - * pages, or parked-domain placeholders. - */ - numBlocked: number; - - numFailed: number; - - numSkipped: number; - - numSucceeded: number; - - numUrls: number; - - /** - * One verified outcome per requested browser action, in request order. - */ - actionsApplied?: Array; - } - - export namespace Metadata { - export interface ActionsApplied { - instruction: string; - - /** - * Applied means the requested page state was visibly verified. Failed means it was - * not verified. Skipped means it was not attempted. - */ - status: 'applied' | 'failed' | 'skipped'; - - /** - * Visible page evidence used to verify an applied action. - */ - completionEvidence?: string; - - durationMs?: number; - - error?: string; - - method?: string; - - targetDescription?: string; - } - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - export interface WebExtractCompetitorsResponse { /** * Direct competitors ordered by relevance and confidence. @@ -615,28 +302,13 @@ export namespace WebExtractCompetitorsResponse { } } -export interface WebExtractFontsResponse { +export interface WebExtractStyleguideResponse { /** * Cache outcome for this response. Composite responses are hits only when every * cache-controlled fetch contributing to the output was a hit; age_ms is the * oldest contributing hit. */ - cache_metadata: WebExtractFontsResponse.CacheMetadata; - - /** - * HTTP status code, e.g., 200 - */ - code: number; - - /** - * The normalized domain that was processed - */ - domain: string; - - /** - * Array of font usage information - */ - fonts: Array; + cache_metadata: WebExtractStyleguideResponse.CacheMetadata; /** * Unique id of this API call, also sent in the X-Request-Id response header. Quote @@ -645,9 +317,14 @@ export interface WebExtractFontsResponse { request_id: string; /** - * Status of the response, e.g., 'ok' + * HTTP status code */ - status: string; + code?: number; + + /** + * The normalized domain that was processed + */ + domain?: string; /** * How complete the returned content is. `loaded` means the page finished the waits @@ -659,19 +336,22 @@ export interface WebExtractFontsResponse { finalDOMState?: 'loaded' | 'still-loading'; /** - * Font assets keyed by family name as it appears in the fonts array (non-generic - * names only). Clients match entries in fonts to pick a file URL from files. - * Omitted when no families resolve to Google or custom @font-face URLs. + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: WebExtractStyleguideResponse.KeyMetadata; + + /** + * Status of the response, e.g., 'ok' */ - fontLinks?: { [key: string]: WebExtractFontsResponse.FontLinks }; + status?: string; /** - * Credit usage, included whenever a valid API key is provided. + * Comprehensive styleguide data extracted from the website */ - key_metadata?: WebExtractFontsResponse.KeyMetadata; + styleguide?: WebExtractStyleguideResponse.Styleguide; } -export namespace WebExtractFontsResponse { +export namespace WebExtractStyleguideResponse { /** * Cache outcome for this response. Composite responses are hits only when every * cache-controlled fetch contributing to the output was a hit; age_ms is the @@ -690,190 +370,46 @@ export namespace WebExtractFontsResponse { status: 'hit' | 'miss' | 'zdr'; } - export interface Font { + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { /** - * Array of fallback font families + * Credits used by this request. */ - fallbacks: Array; + credits_consumed: number; /** - * Font family name + * Credits remaining for your organization. */ - font: string; + credits_remaining: number; + } + /** + * Comprehensive styleguide data extracted from the website + */ + export interface Styleguide { /** - * Number of elements using this font + * Primary colors used on the website */ - num_elements: number; + colors: Styleguide.Colors; /** - * Number of words using this font + * UI component styles */ - num_words: number; + components: Styleguide.Components; /** - * Percentage of elements using this font + * Spacing system used on the website */ - percent_elements: number; + elementSpacing: Styleguide.ElementSpacing; /** - * Percentage of words using this font + * Font assets keyed by family name as it appears in fontFamily/fontFallbacks + * (non-generic names only). Clients match typography.fontFamily / fontWeight or + * button styles to pick a file URL from files. */ - percent_words: number; - - /** - * Array of CSS selectors or element types where this font is used - */ - uses: Array; - } - - export interface FontLinks { - /** - * Upright font files keyed by weight string (e.g. "400" for regular, "500", - * "700"). Values are absolute URLs. - */ - files: { [key: string]: string }; - - type: 'google' | 'custom'; - - /** - * Google Fonts category when type is google (e.g. sans-serif, serif, monospace, - * display, handwriting). Omitted for custom fonts when unknown. - */ - category?: string; - - /** - * Present when type is custom: human-readable name derived from the fontLinks key - * (strip build/hash suffixes, split camelCase / PascalCase, normalize separators). - * Google entries omit this. - */ - displayName?: string; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - -export interface WebExtractStyleguideResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: WebExtractStyleguideResponse.CacheMetadata; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * HTTP status code - */ - code?: number; - - /** - * The normalized domain that was processed - */ - domain?: string; - - /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. - */ - finalDOMState?: 'loaded' | 'still-loading'; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: WebExtractStyleguideResponse.KeyMetadata; - - /** - * Status of the response, e.g., 'ok' - */ - status?: string; - - /** - * Comprehensive styleguide data extracted from the website - */ - styleguide?: WebExtractStyleguideResponse.Styleguide; -} - -export namespace WebExtractStyleguideResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } - - /** - * Comprehensive styleguide data extracted from the website - */ - export interface Styleguide { - /** - * Primary colors used on the website - */ - colors: Styleguide.Colors; - - /** - * UI component styles - */ - components: Styleguide.Components; - - /** - * Spacing system used on the website - */ - elementSpacing: Styleguide.ElementSpacing; - - /** - * Font assets keyed by family name as it appears in fontFamily/fontFallbacks - * (non-generic names only). Clients match typography.fontFamily / fontWeight or - * button styles to pick a file URL from files. - */ - fontLinks: { [key: string]: Styleguide.FontLinks }; + fontLinks: { [key: string]: Styleguide.FontLinks }; /** * The primary color mode of the website design @@ -1339,6 +875,56 @@ export namespace WebExtractStyleguideResponse { } } +export interface WebMapURLsResponse { + domain: string; + + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + + success: true; + + urls: Array; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: WebMapURLsResponse.KeyMetadata; + + partial?: boolean; +} + +export namespace WebMapURLsResponse { + export interface URL { + url: string; + + description?: string; + + keywords?: Array; + + language?: string; + + title?: string; + } + + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + export interface WebScrapeResponse { /** * Original HTTP response body. Waiting, actions, and content filters never change @@ -1394,6 +980,12 @@ export interface WebScrapeResponse { */ url: string; + /** + * Present when return-partial captures a page that is still loading or returns + * images before image processing finishes. Partial responses are not cached. + */ + isPartial?: true; + /** * Credit usage, included whenever a valid API key is provided. */ @@ -2157,3705 +1749,650 @@ export namespace WebWebCrawlMdResponse { } } -export interface WebWebScrapeBytesResponse { +export interface WebAnswersParams { /** - * Base64-encoded resource bytes, without a data URI prefix. Decode this field to - * recover the downloaded file. + * What to research and answer, in plain language. Naming a domain in the task (for + * example "pricing on context.dev") makes the agent read that site before it + * searches. */ - bytes: string; + task: string; /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * An example object with placeholder values (for example {"pricing_page_url": "", + * "plans": [{"name": "", "price": 0}]}). Object keys and value types are + * preserved; unknown values may be null. Empty arrays accept any JSON items. + * Defaults to {"result": ""}. Maximum 8 levels, 500 values, and 16000 characters. */ - cache_metadata: WebWebScrapeBytesResponse.CacheMetadata; + json_format?: { [key: string]: unknown }; /** - * Number of decoded resource bytes, before base64 encoding. + * Research level: fast uses a smaller model and research budget for 10 credits; + * ultra uses deeper reasoning and research for 100 credits. Defaults to ultra. + * Only successful requests consume credits. */ - contentLength: number; + mode?: 'fast' | 'ultra'; /** - * The Content-Type returned by the origin, including any charset. Defaults to - * application/octet-stream when absent. + * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. */ - contentType: string; - - encoding: 'base64'; + tags?: Array; /** - * The resource URL after redirects. + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - finalUrl: string; + timeoutOpts?: WebAnswersParams.TimeoutOpts; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ - request_id: string; + zdr?: 'enabled' | 'disabled'; +} +export namespace WebAnswersParams { /** - * HTTP status returned by the origin. + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - statusCode: number; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; - success: true; + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } +} +export interface WebExtractCompetitorsParams { /** - * The requested resource URL. + * Company domain to analyze, such as `stripe.com`. Full http(s) URLs are accepted + * and normalized to their domain. */ - url: string; + domain: string; /** - * Credit usage, included whenever a valid API key is provided. + * Exact number of direct competitors to return. Defaults to 5. */ - key_metadata?: WebWebScrapeBytesResponse.KeyMetadata; -} + numCompetitors?: number; -export namespace WebWebScrapeBytesResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; + tags?: Array; - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: WebExtractCompetitorsParams.TimeoutOpts; /** - * Credit usage, included whenever a valid API key is provided. + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ - export interface KeyMetadata { + zdr?: 'enabled' | 'disabled'; +} + +export namespace WebExtractCompetitorsParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { /** - * Credits used by this request. + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). */ - credits_consumed: number; + milliseconds: number; /** - * Credits remaining for your organization. + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. */ - credits_remaining: number; + behavior?: 'fail' | 'return-partial'; } } -export interface WebWebScrapeHTMLResponse { +export interface WebExtractStyleguideParams { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Optional browser color scheme to emulate for websites that respond to + * prefers-color-scheme. This value is part of the styleguide cache key. */ - cache_metadata: WebWebScrapeHTMLResponse.CacheMetadata; + colorScheme?: 'light' | 'dark'; /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. + * A specific URL to fetch the styleguide from directly, bypassing domain + * resolution (e.g., 'https://example.com/design-system'). When provided, the + * styleguide is extracted from this exact URL. You must provide either 'domain' or + * 'directUrl', but not both. */ - finalDOMState: 'loaded' | 'still-loading'; + directUrl?: string; /** - * The scraped content of the page. For normal pages this is the raw HTML. When the - * page is a sitemap or feed served behind an XSL stylesheet (which browsers render - * into HTML), this is the underlying XML instead — see the `type` field. + * Domain name to extract styleguide from (e.g., 'example.com', 'google.com'). The + * domain will be automatically normalized and validated. You must provide either + * 'domain' or 'directUrl', but not both. */ - html: string; + domain?: string; /** - * Metadata extracted from the scraped page HTML. + * Maximum age in milliseconds for cached brand data before the API performs a hard + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ - metadata: WebWebScrapeHTMLResponse.Metadata; + maxAgeMs?: number | null; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ - request_id: string; + tags?: Array; /** - * Indicates success + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - success: true; + timeoutOpts?: WebExtractStyleguideParams.TimeoutOpts; /** - * Detected content type of the returned `html` field. Sitemaps and feeds are - * surfaced as `xml`; ordinary pages are `html`. Excel workbooks are surfaced as - * `xlsx`/`xls` with the extracted sheets as HTML tables; PowerPoint presentations - * are surfaced as `pptx`/`ppt` with the extracted slides as HTML. + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ - type: - | 'html' - | 'xml' - | 'json' - | 'text' - | 'csv' - | 'markdown' - | 'svg' - | 'pdf' - | 'docx' - | 'doc' - | 'xlsx' - | 'xls' - | 'pptx' - | 'ppt'; + zdr?: 'enabled' | 'disabled'; +} +export namespace WebExtractStyleguideParams { /** - * The URL that was scraped + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - url: string; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 5000. + */ + behavior?: 'fail' | 'return-partial'; + } +} +export interface WebMapURLsParams { /** - * One verified outcome per requested browser action, in request order. + * Domain to build a sitemap for */ - actionsApplied?: Array; + domain: string; /** - * True when an action was applied but the returned content could not be refreshed - * afterward. + * Optional outbound HTTP headers forwarded only to the target URL, sent as + * deep-object query params such as headers[X-Custom]=value. When provided, caching + * is bypassed: the result is neither read from nor written to cache. */ - actionsHtmlStale?: boolean; + headers?: { [key: string]: string }; /** - * Present only when extractRules is supplied. Keys match the requested fields. - * Values are normalized text, raw attribute strings, outer HTML, nested objects, - * or lists. Missing items are null; lists with no matches are empty. Rules run on - * the returned HTML after filtering. + * When true, discover and include public pages and sitemaps on subdomains of the + * requested domain. Defaults to false. */ - extracted?: { [key: string]: string | unknown | Array | null }; + includeSubdomains?: boolean; /** - * Credit usage, included whenever a valid API key is provided. + * Maximum number of links to return from the sitemap crawl. Defaults to 10,000. + * Minimum is 1, maximum is 100,000. */ - key_metadata?: WebWebScrapeHTMLResponse.KeyMetadata; -} + maxLinks?: number; -export namespace WebWebScrapeHTMLResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Optional search phrase. When provided, the crawled sitemap is filtered to the + * pages whose URLs are about that phrase, most relevant first, and the request + * costs 2 credits instead of 1. */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; + search?: string; - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } + /** + * Optional explicit sitemap URL. When provided, exactly this sitemap is crawled + * instead of discovering the domain's sitemaps. + */ + sitemapUrl?: string; /** - * Metadata extracted from the scraped page HTML. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ - export interface Metadata { - /** - * Final URL scraped after redirects or scraper fallback, when known. Falls back to - * sourceUrl when unavailable. - */ - finalUrl: string; + tags?: Array; - /** - * Original URL requested by the caller. - */ - sourceUrl: string; + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: WebMapURLsParams.TimeoutOpts; - /** - * Additional non-social meta tags not promoted to top-level metadata fields. - */ - additionalMeta?: { [key: string]: string | Array }; + /** + * Optional RE2-compatible regex pattern. Only URLs matching this pattern are + * returned and counted against maxLinks. + */ + urlRegex?: string; - /** - * Resolved alternate links from link rel=alternate tags. - */ - alternates?: Array; + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; +} +export namespace WebMapURLsParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { /** - * Author metadata, when present. + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). */ - author?: string; + milliseconds: number; /** - * Resolved canonical URL, when present. + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. */ - canonicalUrl?: string; + behavior?: 'fail' | 'return-partial'; + } +} - /** - * Best description extracted from standard, Open Graph, or Twitter metadata. - */ - description?: string; +export interface WebScrapeParams { + /** + * Outputs to return. Enable at least one; omitted formats are false. + */ + formats: WebScrapeParams.Formats; - /** - * Resolved favicon URL, when present. - */ - favicon?: string; + /** + * The URL to scrape. + */ + url: string; - /** - * Page headings (h1–h6) in document order, extracted from the unfiltered document. - * Capped at the first 500 headings. Omitted when the page has none. - */ - headings?: Array; + /** + * Image options. Requires formats.images: true. + */ + imageParams?: WebScrapeParams.ImageParams; - /** - * Primary resolved preview image from Open Graph, Twitter, or image metadata. - */ - image?: string; + /** + * Markdown options. Requires formats.markdown: true. + */ + markdownParams?: WebScrapeParams.MarkdownParams; - /** - * JSON-LD structured data blocks parsed from the page. - */ - jsonLd?: Array<{ [key: string]: unknown }>; + /** + * Maximum age of each cached output. Defaults to 1 day; 0 fetches fresh and + * updates the requested outputs. Compatible outputs are shared with the individual + * scrape endpoints. Image results with hosted files refresh after 23 hours; other + * outputs retain their own freshness. + */ + maxAgeMs?: number; - /** - * Keywords extracted from the page's keywords meta tag. - */ - keywords?: Array; - - /** - * Language extracted from html lang or language meta tags. - */ - language?: string; - - /** - * Modified timestamp/date from page metadata, when present. - */ - modifiedTime?: string; - - /** - * Open Graph metadata with the og: prefix removed and keys camel-cased. - */ - openGraph?: { [key: string]: string | Array }; - - /** - * Published timestamp/date from page metadata, when present. - */ - publishedTime?: string; - - /** - * Robots meta directive, when present. - */ - robots?: string; - - /** - * Site or application name from page metadata. - */ - siteName?: string; - - /** - * Best title extracted from the page. - */ - title?: string; - - /** - * Twitter card metadata with the twitter: prefix removed and keys camel-cased. - */ - twitter?: { [key: string]: string | Array }; - } - - export namespace Metadata { - export interface Alternate { - /** - * Resolved alternate URL. - */ - href: string; - - /** - * Language or locale for the alternate URL, when present. - */ - hreflang?: string; - - /** - * Alternate resource title, when present. - */ - title?: string; - - /** - * Alternate resource MIME type, when present. - */ - type?: string; - } - - export interface Heading { - /** - * Heading level, 1–6 (from h1–h6). - */ - level: number; - - /** - * Heading text with whitespace collapsed, truncated to 1000 characters. - */ - text: string; - } - } - - export interface ActionsApplied { - instruction: string; - - /** - * Applied means the requested page state was visibly verified. Failed means it was - * not verified. Skipped means it was not attempted. - */ - status: 'applied' | 'failed' | 'skipped'; - - /** - * Visible page evidence used to verify an applied action. - */ - completionEvidence?: string; - - durationMs?: number; - - error?: string; - - method?: string; - - targetDescription?: string; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - -export interface WebWebScrapeImagesResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: WebWebScrapeImagesResponse.CacheMetadata; - - /** - * Images found on the page. - */ - images: Array; + /** + * Required when formats.parse is true. + */ + parseParams?: WebScrapeParams.ParseParams; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Always true on success. - */ - success: true; - - /** - * Page URL that was scraped. + * Screenshot options. Requires formats.screenshot: true. */ - url: string; + screenshotParams?: WebScrapeParams.ScreenshotParams; /** - * One verified outcome per requested browser action, in request order. + * Shared browser and content settings. Content filters leave screenshots and + * original bytes unchanged. */ - actionsApplied?: Array; + sharedParams?: WebScrapeParams.SharedParams; /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. + * Labels for tracking request usage. Not retained when zdr is enabled. */ - finalDOMState?: 'loaded' | 'still-loading'; + tags?: Array; /** - * Credit usage, included whenever a valid API key is provided. + * Total deadline, including navigation, actions, waiting, and all outputs. + * Defaults to 60000 milliseconds with behavior fail. Use return-partial to capture + * the current page state and return captured images if image processing cannot + * finish before the deadline; these responses set isPartial and are not cached. + * Every requested format must still be available. Fixed waits must fit before a + * response reserve of up to 5000 milliseconds (at most one quarter of the timeout) + * when using return-partial. */ - key_metadata?: WebWebScrapeImagesResponse.KeyMetadata; + timeoutOpts?: WebScrapeParams.TimeoutOpts; /** - * True when the deadline interrupted rendering or image enrichment. Partial - * results are billed at the base request cost, without enrichment or actions - * surcharges. + * Zero data retention. Bypasses caches and uploads; excludes request/response + * content and tags from logs. Must be enabled for your organization. */ - partial?: boolean; + zdr?: 'enabled' | 'disabled'; } -export namespace WebWebScrapeImagesResponse { +export namespace WebScrapeParams { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Outputs to return. Enable at least one; omitted formats are false. */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - export interface Image { - /** - * Image alt text, or null when unavailable. - */ - alt: string | null; - - /** - * Where the image was found. - */ - element: 'img' | 'svg' | 'link' | 'source' | 'video' | 'css' | 'object' | 'meta' | 'background'; - - /** - * Original image value: URL, inline SVG or HTML, or base64 data URI. - */ - src: string; - - /** - * Format of src. - */ - type: 'url' | 'html' | 'base64'; - + export interface Formats { /** - * Requested metadata for images that could be processed. + * The original HTTP response body. */ - enrichment?: Image.Enrichment; - } + bytes?: boolean; - export namespace Image { /** - * Requested metadata for images that could be processed. + * Rendered HTML. */ - export interface Enrichment { - /** - * Image height in pixels, when measured. - */ - height?: number; - - /** - * Detected MIME type, when hosted. - */ - mimetype?: string; - - /** - * Visual asset category, when classified. - */ - type?: 'photography' | 'illustration' | 'logo' | 'wordmark' | 'icon' | 'pattern' | 'graphic' | 'other'; - - /** - * Brand.dev CDN URL, when hosted. - */ - url?: string; - - /** - * Image width in pixels, when measured. - */ - width?: number; - } - } - - export interface ActionsApplied { - instruction: string; + html?: boolean; /** - * Applied means the requested page state was visibly verified. Failed means it was - * not verified. Skipped means it was not attempted. + * Images found on the page. */ - status: 'applied' | 'failed' | 'skipped'; + images?: boolean; /** - * Visible page evidence used to verify an applied action. + * Page content as Markdown. */ - completionEvidence?: string; - - durationMs?: number; - - error?: string; - - method?: string; - - targetDescription?: string; - } + markdown?: boolean; - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { /** - * Credits used by this request. + * Fields selected by parseParams.rules. */ - credits_consumed: number; + parse?: boolean; /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - -export interface WebWebScrapeMdResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: WebWebScrapeMdResponse.CacheMetadata; - - /** - * UTF-8 byte length of the returned Markdown. Use 0 to identify an empty result - * and compare small values against your workload's minimum useful-content - * threshold. - */ - contentLength: number; - - /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. - */ - finalDOMState: 'loaded' | 'still-loading'; - - /** - * Page content converted to GitHub Flavored Markdown - */ - markdown: string; - - /** - * Metadata extracted from the scraped page HTML. - */ - metadata: WebWebScrapeMdResponse.Metadata; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Indicates success - */ - success: true; - - /** - * The URL that was scraped - */ - url: string; - - /** - * One verified outcome per requested browser action, in request order. - */ - actionsApplied?: Array; - - /** - * True when an action was applied but the returned content could not be refreshed - * afterward. - */ - actionsHtmlStale?: boolean; - - /** - * Only present when includeHTML=true: the page HTML the Markdown was converted - * from — the same body the Scrape HTML endpoint returns for the equivalent - * request. - */ - html?: string; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: WebWebScrapeMdResponse.KeyMetadata; -} - -export namespace WebWebScrapeMdResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - /** - * Metadata extracted from the scraped page HTML. - */ - export interface Metadata { - /** - * Final URL scraped after redirects or scraper fallback, when known. Falls back to - * sourceUrl when unavailable. - */ - finalUrl: string; - - /** - * Original URL requested by the caller. - */ - sourceUrl: string; - - /** - * Additional non-social meta tags not promoted to top-level metadata fields. - */ - additionalMeta?: { [key: string]: string | Array }; - - /** - * Resolved alternate links from link rel=alternate tags. - */ - alternates?: Array; - - /** - * Author metadata, when present. - */ - author?: string; - - /** - * Resolved canonical URL, when present. - */ - canonicalUrl?: string; - - /** - * Best description extracted from standard, Open Graph, or Twitter metadata. - */ - description?: string; - - /** - * Resolved favicon URL, when present. - */ - favicon?: string; - - /** - * Page headings (h1–h6) in document order, extracted from the unfiltered document. - * Capped at the first 500 headings. Omitted when the page has none. - */ - headings?: Array; - - /** - * Primary resolved preview image from Open Graph, Twitter, or image metadata. - */ - image?: string; - - /** - * JSON-LD structured data blocks parsed from the page. - */ - jsonLd?: Array<{ [key: string]: unknown }>; - - /** - * Keywords extracted from the page's keywords meta tag. - */ - keywords?: Array; - - /** - * Language extracted from html lang or language meta tags. - */ - language?: string; - - /** - * Modified timestamp/date from page metadata, when present. - */ - modifiedTime?: string; - - /** - * Open Graph metadata with the og: prefix removed and keys camel-cased. - */ - openGraph?: { [key: string]: string | Array }; - - /** - * Published timestamp/date from page metadata, when present. - */ - publishedTime?: string; - - /** - * Robots meta directive, when present. - */ - robots?: string; - - /** - * Site or application name from page metadata. - */ - siteName?: string; - - /** - * Best title extracted from the page. - */ - title?: string; - - /** - * Twitter card metadata with the twitter: prefix removed and keys camel-cased. - */ - twitter?: { [key: string]: string | Array }; - } - - export namespace Metadata { - export interface Alternate { - /** - * Resolved alternate URL. - */ - href: string; - - /** - * Language or locale for the alternate URL, when present. - */ - hreflang?: string; - - /** - * Alternate resource title, when present. - */ - title?: string; - - /** - * Alternate resource MIME type, when present. - */ - type?: string; - } - - export interface Heading { - /** - * Heading level, 1–6 (from h1–h6). - */ - level: number; - - /** - * Heading text with whitespace collapsed, truncated to 1000 characters. - */ - text: string; - } - } - - export interface ActionsApplied { - instruction: string; - - /** - * Applied means the requested page state was visibly verified. Failed means it was - * not verified. Skipped means it was not attempted. - */ - status: 'applied' | 'failed' | 'skipped'; - - /** - * Visible page evidence used to verify an applied action. - */ - completionEvidence?: string; - - durationMs?: number; - - error?: string; - - method?: string; - - targetDescription?: string; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - -export interface WebWebScrapeScreenshotResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: WebWebScrapeScreenshotResponse.CacheMetadata; - - /** - * Height of the returned image in pixels. - */ - height: number; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Public image URL for standard requests, or an in-memory data URL when ZDR or - * non-empty custom headers are supplied. - */ - screenshot: string; - - /** - * The requested page URL. - */ - url: string; - - /** - * Width of the returned image in pixels. - */ - width: number; - - /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. - */ - finalDOMState?: 'loaded' | 'still-loading'; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: WebWebScrapeScreenshotResponse.KeyMetadata; -} - -export namespace WebWebScrapeScreenshotResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - -export interface WebWebScrapeSitemapResponse { - /** - * The normalized domain that was crawled - */ - domain: string; - - /** - * Metadata about the sitemap crawl operation - */ - meta: WebWebScrapeSitemapResponse.Meta; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Indicates success - */ - success: true; - - /** - * Discovered page URLs from the sitemap, up to `maxLinks`. When `search` is set - * these are only the matching pages, most relevant first. - */ - urls: Array; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: WebWebScrapeSitemapResponse.KeyMetadata; - - /** - * True when timeoutOpts.behavior=return-partial returned the usable results - * collected before the deadline. Partial collections are not cached as complete - * results. - */ - partial?: boolean; -} - -export namespace WebWebScrapeSitemapResponse { - /** - * Metadata about the sitemap crawl operation - */ - export interface Meta { - /** - * Number of errors encountered during crawling - */ - errors: number; - - /** - * Total number of sitemap files discovered - */ - sitemapsDiscovered: number; - - /** - * Number of sitemap files successfully fetched and parsed - */ - sitemapsFetched: number; - - /** - * Number of sitemap files skipped (due to errors, timeouts, or limits) - */ - sitemapsSkipped: number; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - -export interface WebAnswersParams { - /** - * What to research and answer, in plain language. Naming a domain in the task (for - * example "pricing on context.dev") makes the agent read that site before it - * searches. - */ - task: string; - - /** - * An example object with placeholder values (for example {"pricing_page_url": "", - * "plans": [{"name": "", "price": 0}]}). Object keys and value types are - * preserved; unknown values may be null. Empty arrays accept any JSON items. - * Defaults to {"result": ""}. Maximum 8 levels, 500 values, and 16000 characters. - */ - json_format?: { [key: string]: unknown }; - - /** - * Research level: fast uses a smaller model and research budget for 10 credits; - * ultra uses deeper reasoning and research for 100 credits. Defaults to ultra. - * Only successful requests consume credits. - */ - mode?: 'fast' | 'ultra'; - - /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebAnswersParams.TimeoutOpts; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebAnswersParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export interface WebExtractParams { - /** - * JSON Schema for the returned data object. Image fields such as `image_urls` or - * `product_photos` automatically make page image references available to - * extraction, so product data and photos can be returned in one call. TypeScript - * Zod users can pass a JSON Schema generated from a Zod object; Python users can - * pass the equivalent JSON Schema object. - */ - schema: { [key: string]: unknown }; - - /** - * The starting website URL to crawl and extract from. Must include http:// or - * https://. - */ - url: string; - - /** - * Optional browser actions executed in order on the requested page after it loads, - * before links are discovered or additional pages are crawled. Requires a paid - * plan. When actions are provided and stopAfterMs is omitted, the crawl budget - * defaults to 110000 ms. - */ - actions?: Array< - | WebExtractParams.WebScrapeWaitAction - | WebExtractParams.WebScrapePerformAction - | WebExtractParams.WebScrapeScrollAction - >; - - /** - * When true, every returned value must be grounded in facts stated on the page; - * fields that cannot be supported by the page are returned as null/empty. When - * false (default), the model may make reasonable inferences and derivations from - * the page content (e.g. ideal customer, competitor analysis, recommendations) - * while keeping verifiable specifics (names, quotes, URLs, dates, metrics) - * faithful to the source. - */ - factCheck?: boolean; - - /** - * When true, follow links on subdomains of the starting URL's domain. - */ - followSubdomains?: boolean; - - /** - * When true, iframe contents are included in Markdown before extraction. - */ - includeFrames?: boolean; - - /** - * Optional extraction guidance, such as which facts to prioritize or how to - * interpret fields in the schema. - */ - instructions?: string; - - /** - * Return cached scrape results if a prior scrape for the same parameters is - * younger than this many milliseconds. Defaults to 7 days (604800000 ms). - */ - maxAgeMs?: number; - - /** - * Optional maximum link depth from the starting URL (0 = only the starting page). - * If omitted, there is no crawl depth limit. - */ - maxDepth?: number; - - /** - * Maximum number of pages to analyze for extraction. Hard cap: 50. Defaults to 5. - */ - maxPages?: number; - - pdf?: WebExtractParams.Pdf; - - /** - * When true, waits briefly for CSS and transition animations to settle before - * extracting each crawled page. Defaults to false. This adds a bit of latency in - * exchange for more stable output on animated pages. - */ - settleAnimations?: boolean; - - /** - * Soft time budget for the crawl in milliseconds. Min: 10000 (10s). Max: 110000 - * (110s). Defaults to 80000 (80s), or 110000 (110s) when browser actions are - * provided. - */ - stopAfterMs?: number; - - /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebExtractParams.TimeoutOpts; - - /** - * Optional browser wait time in milliseconds after initial page load for each - * crawled page. - */ - waitForMs?: number; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebExtractParams { - /** - * Pause for a fixed number of milliseconds before continuing to the next action. - */ - export interface WebScrapeWaitAction { - do: 'wait'; - - timeMs: number; - } - - /** - * Resolve and perform one natural-language browser action. - */ - export interface WebScrapePerformAction { - action: string; - - do: 'perform'; - } - - /** - * Scroll the page or a selected scrollable container, waiting adaptively for - * content and dimensions to settle after each iteration. - */ - export interface WebScrapeScrollAction { - do: 'scroll'; - - /** - * Pixels per scroll, one visible viewport, or the current scroll boundary. - * Defaults to viewport. - */ - amount?: number | 'viewport' | 'max'; - - /** - * CSS selector for the first matching scroll container. Defaults to the page. - */ - container?: string; - - /** - * Direction to scroll. Defaults to down. - */ - direction?: 'up' | 'down' | 'left' | 'right'; - - /** - * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop - * changing. Defaults to 1. - */ - maxScrolls?: number; - } - - export interface Pdf { - /** - * Last 1-based PDF page to parse. Must be greater than or equal to start when both - * are provided. - */ - end?: number; - - /** - * When true, PDF pages are fetched and parsed. When false, PDF pages are skipped. - */ - shouldParse?: boolean; - - /** - * First 1-based PDF page to parse. - */ - start?: number; - } - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export interface WebExtractCompetitorsParams { - /** - * Company domain to analyze, such as `stripe.com`. Full http(s) URLs are accepted - * and normalized to their domain. - */ - domain: string; - - /** - * Exact number of direct competitors to return. Defaults to 5. - */ - numCompetitors?: number; - - /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebExtractCompetitorsParams.TimeoutOpts; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebExtractCompetitorsParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export interface WebExtractFontsParams { - /** - * A specific URL to fetch fonts from directly, bypassing domain resolution (e.g., - * 'https://example.com/design-system'). When provided, fonts are extracted from - * this exact URL. You must provide either 'domain' or 'directUrl', but not both. - */ - directUrl?: string; - - /** - * Domain name to extract fonts from (e.g., 'example.com', 'google.com'). The - * domain will be automatically normalized and validated. You must provide either - * 'domain' or 'directUrl', but not both. - */ - domain?: string; - - /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. - */ - maxAgeMs?: number | null; - - /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebExtractFontsParams.TimeoutOpts; -} - -export namespace WebExtractFontsParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export interface WebExtractStyleguideParams { - /** - * Optional browser color scheme to emulate for websites that respond to - * prefers-color-scheme. This value is part of the styleguide cache key. - */ - colorScheme?: 'light' | 'dark'; - - /** - * A specific URL to fetch the styleguide from directly, bypassing domain - * resolution (e.g., 'https://example.com/design-system'). When provided, the - * styleguide is extracted from this exact URL. You must provide either 'domain' or - * 'directUrl', but not both. - */ - directUrl?: string; - - /** - * Domain name to extract styleguide from (e.g., 'example.com', 'google.com'). The - * domain will be automatically normalized and validated. You must provide either - * 'domain' or 'directUrl', but not both. - */ - domain?: string; - - /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. - */ - maxAgeMs?: number | null; - - /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebExtractStyleguideParams.TimeoutOpts; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebExtractStyleguideParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export interface WebScrapeParams { - /** - * Outputs to return. Enable at least one; omitted formats are false. - */ - formats: WebScrapeParams.Formats; - - /** - * The URL to scrape. - */ - url: string; - - /** - * Image options. Requires formats.images: true. - */ - imageParams?: WebScrapeParams.ImageParams; - - /** - * Markdown options. Requires formats.markdown: true. - */ - markdownParams?: WebScrapeParams.MarkdownParams; - - /** - * Maximum age of each cached output. Defaults to 1 day; 0 fetches fresh and - * updates the requested outputs. Compatible outputs are shared with the individual - * scrape endpoints. Image results with hosted files refresh after 23 hours; other - * outputs retain their own freshness. - */ - maxAgeMs?: number; - - /** - * Required when formats.parse is true. - */ - parseParams?: WebScrapeParams.ParseParams; - - /** - * Screenshot options. Requires formats.screenshot: true. - */ - screenshotParams?: WebScrapeParams.ScreenshotParams; - - /** - * Shared browser and content settings. Content filters leave screenshots and - * original bytes unchanged. - */ - sharedParams?: WebScrapeParams.SharedParams; - - /** - * Labels for tracking request usage. Not retained when zdr is enabled. - */ - tags?: Array; - - /** - * Total deadline, including navigation, actions, waiting, and all outputs. - */ - timeoutMs?: number; - - /** - * Zero data retention. Bypasses caches and uploads; excludes request/response - * content and tags from logs. Must be enabled for your organization. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebScrapeParams { - /** - * Outputs to return. Enable at least one; omitted formats are false. - */ - export interface Formats { - /** - * The original HTTP response body. - */ - bytes?: boolean; - - /** - * Rendered HTML. - */ - html?: boolean; - - /** - * Images found on the page. - */ - images?: boolean; - - /** - * Page content as Markdown. - */ - markdown?: boolean; - - /** - * Fields selected by parseParams.rules. - */ - parse?: boolean; - - /** - * An inline image of the page. - */ - screenshot?: boolean; - } - - /** - * Image options. Requires formats.images: true. - */ - export interface ImageParams { - /** - * For visual duplicates, keep the largest image. - */ - dedupe?: 'none' | 'visual'; - - /** - * Add dimensions, a visual category, or a hosted file URL. - */ - enrich?: Array<'dimensions' | 'classification' | 'file'>; - } - - /** - * Markdown options. Requires formats.markdown: true. - */ - export interface MarkdownParams { - includeImages?: boolean; - - includeLinks?: boolean; - - /** - * Base64 images use placeholders by default. Requires includeImages: true. - */ - inlineImages?: 'placeholder' | 'preserve'; - } - - /** - * Required when formats.parse is true. - */ - export interface ParseParams { - /** - * Map field names to CSS selectors or rules. Missing items return null; missing - * lists return []. - */ - rules: { [key: string]: string | ParseParams.UnionMember1 }; - } - - export namespace ParseParams { - export interface UnionMember1 { - selector: string; - - output?: 'text' | 'html' | string | unknown; - - type?: 'item' | 'list'; - } - } - - /** - * Screenshot options. Requires formats.screenshot: true. - */ - export interface ScreenshotParams { - /** - * Viewport, full page, one visible element, or a rectangle. Maximum 40 megapixels. - */ - area?: 'viewport' | 'fullPage' | ScreenshotParams.Element | ScreenshotParams.Rectangle; - - format?: 'png' | 'jpeg' | 'webp'; - } - - export namespace ScreenshotParams { - export interface Element { - /** - * Must match one visible element. - */ - selector: string; - } - - /** - * Pixels from the document origin. - */ - export interface Rectangle { - height: number; - - width: number; - - x: number; - - y: number; - } - } - - /** - * Shared browser and content settings. Content filters leave screenshots and - * original bytes unchanged. - */ - export interface SharedParams { - /** - * Run in order before capture. A failed action fails the request. Bypasses - * caching. - */ - actions?: Array; - - /** - * Supported two-letter country code, case-insensitive. Applies to every output, - * including image downloads. - */ - country?: string; - - /** - * Dismiss cookie banners by accepting cookies before actions. - */ - dismissCookies?: boolean; - - /** - * Dismiss other popups before actions. - */ - dismissPopups?: boolean; - - /** - * Remove matching content. Exclusions win. - */ - excludeSelectors?: Array; - - /** - * Headers for the target origin. Requests with custom headers bypass caching. - */ - headers?: { [key: string]: string }; - - /** - * Include iframe content in extraction. Screenshots show visible frames - * regardless. - */ - includeFrames?: boolean; - - /** - * Keep matching content after mainContentOnly. - */ - includeSelectors?: Array; - - /** - * Keep only main content in HTML, Markdown, images, and parsed fields. - */ - mainContentOnly?: boolean; - - /** - * Document parsing options. - */ - parsers?: SharedParams.Parsers; - - /** - * Settle animations before capture. Defaults to true with screenshots, otherwise - * false. - */ - settleAnimations?: boolean; - - /** - * Override the browser color scheme. - */ - theme?: 'light' | 'dark'; - - /** - * Browser dimensions in pixels. - */ - viewport?: SharedParams.Viewport; - - /** - * After actions, wait this many milliseconds or until a CSS selector is visible. - * Defaults to 500 ms, or 2000 ms with frames or an XML URL. Set 0 to skip. - */ - waitFor?: number | string; - } - - export namespace SharedParams { - export interface Perform { - action: string; - - type: 'perform'; - } - - export interface Scroll { - type: 'scroll'; - - amount?: number | 'viewport' | 'max'; - - direction?: 'down' | 'up' | 'left' | 'right'; - - maxScrolls?: number; - - /** - * Scroll this container. Omit to scroll the page. - */ - selector?: string; - } - - export interface Wait { - milliseconds: number; - - type: 'wait'; - } - - export interface WaitFor { - selector: string; - - type: 'waitFor'; - } - - /** - * Document parsing options. - */ - export interface Parsers { - /** - * PDF text options for HTML, Markdown, and parsed fields. - */ - pdf?: Parsers.Pdf; - } - - export namespace Parsers { - /** - * PDF text options for HTML, Markdown, and parsed fields. - */ - export interface Pdf { - /** - * Last page to parse. Must be at least startPage. - */ - endPage?: number; - - /** - * Read text from scanned pages. - */ - ocr?: 'off' | 'auto'; - - /** - * First page to parse, starting at 1. - */ - startPage?: number; - } - } - - /** - * Browser dimensions in pixels. - */ - export interface Viewport { - height?: number; - - width?: number; - } - } -} - -export interface WebScreenshotParams { - /** - * Optional parameter for comprehensive popup cleanup. If 'true', the browser - * dismisses detected cookie/consent UI and clears other detected obstructive - * popups and overlays before capture. If 'false' or not provided, this parameter - * requests no cleanup; handleCookiePopup can still request cookie/consent handling - * independently. - */ - clearPopups?: boolean; - - /** - * Optional parameter to choose the site's visual theme in the screenshot. Use - * 'light' or 'dark' when the site offers both appearances. - */ - colorScheme?: 'light' | 'dark'; - - /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). - */ - country?: - | 'ad' - | 'ae' - | 'af' - | 'ag' - | 'ai' - | 'al' - | 'am' - | 'ao' - | 'ar' - | 'at' - | 'au' - | 'aw' - | 'az' - | 'ba' - | 'bb' - | 'bd' - | 'be' - | 'bf' - | 'bg' - | 'bh' - | 'bi' - | 'bj' - | 'bm' - | 'bn' - | 'bo' - | 'bq' - | 'br' - | 'bs' - | 'bw' - | 'by' - | 'bz' - | 'ca' - | 'cd' - | 'cf' - | 'cg' - | 'ch' - | 'ci' - | 'cl' - | 'cm' - | 'cn' - | 'co' - | 'cr' - | 'cv' - | 'cw' - | 'cy' - | 'cz' - | 'de' - | 'dj' - | 'dk' - | 'dm' - | 'do' - | 'dz' - | 'ec' - | 'ee' - | 'eg' - | 'es' - | 'et' - | 'fi' - | 'fj' - | 'fr' - | 'ga' - | 'gb' - | 'gd' - | 'ge' - | 'gf' - | 'gg' - | 'gh' - | 'gm' - | 'gn' - | 'gp' - | 'gq' - | 'gr' - | 'gt' - | 'gu' - | 'gw' - | 'gy' - | 'hk' - | 'hn' - | 'hr' - | 'ht' - | 'hu' - | 'id' - | 'ie' - | 'il' - | 'im' - | 'in' - | 'iq' - | 'ir' - | 'is' - | 'it' - | 'je' - | 'jm' - | 'jo' - | 'jp' - | 'ke' - | 'kg' - | 'kh' - | 'kn' - | 'kr' - | 'kw' - | 'ky' - | 'kz' - | 'la' - | 'lb' - | 'lc' - | 'lk' - | 'lr' - | 'ls' - | 'lt' - | 'lu' - | 'lv' - | 'ly' - | 'ma' - | 'mc' - | 'md' - | 'me' - | 'mf' - | 'mg' - | 'mk' - | 'ml' - | 'mm' - | 'mn' - | 'mo' - | 'mq' - | 'mr' - | 'mt' - | 'mu' - | 'mv' - | 'mw' - | 'mx' - | 'my' - | 'mz' - | 'na' - | 'nc' - | 'ne' - | 'ng' - | 'ni' - | 'nl' - | 'no' - | 'np' - | 'nz' - | 'om' - | 'pa' - | 'pe' - | 'pf' - | 'pg' - | 'ph' - | 'pk' - | 'pl' - | 'pr' - | 'ps' - | 'pt' - | 'py' - | 'qa' - | 're' - | 'ro' - | 'rs' - | 'ru' - | 'rw' - | 'sa' - | 'sc' - | 'sd' - | 'se' - | 'sg' - | 'si' - | 'sk' - | 'sl' - | 'sm' - | 'sn' - | 'so' - | 'sr' - | 'ss' - | 'st' - | 'sv' - | 'sx' - | 'sy' - | 'sz' - | 'tc' - | 'td' - | 'tg' - | 'th' - | 'tj' - | 'tl' - | 'tm' - | 'tn' - | 'tr' - | 'tt' - | 'tw' - | 'tz' - | 'ua' - | 'ug' - | 'us' - | 'uy' - | 'uz' - | 'vc' - | 've' - | 'vg' - | 'vi' - | 'vn' - | 'ye' - | 'yt' - | 'za' - | 'zm' - | 'zw'; - - /** - * A specific URL to screenshot directly, bypassing domain resolution (e.g., - * 'https://example.com/pricing'). When provided, the screenshot is taken of this - * exact URL. You must provide either 'domain' or 'directUrl', but not both. - */ - directUrl?: string; - - /** - * Domain name to take screenshot of (e.g., 'example.com', 'google.com'). The - * domain will be automatically normalized and validated. You must provide either - * 'domain' or 'directUrl', but not both. - */ - domain?: string; - - /** - * Optional parameter to determine screenshot type. If 'true', takes a full page - * screenshot capturing all content. If 'false' or not provided, takes a viewport - * screenshot (standard browser view). - */ - fullScreenshot?: 'true' | 'false'; - - /** - * Optional parameter to control cookie/consent popup handling. If 'true', we - * dismiss cookie banner before capture. If 'false' or not provided, captures the - * page without that step. - */ - handleCookiePopup?: boolean; - - /** - * Optional outbound HTTP headers, using the same JSON object or deep-object query - * format as other scrape endpoints (for example headers[Authorization]=Bearer - * token). Headers are scoped to the target origin during capture. For domain/page - * requests, discovery receives no custom headers and only pages on the resolved - * origin are eligible. Non-empty headers bypass screenshot caching and return an - * in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted - * headers. - */ - headers?: { [key: string]: string }; - - /** - * Return a cached screenshot if a prior screenshot for the same parameters exists - * and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh. - */ - maxAgeMs?: number | null; - - /** - * Optional parameter to specify which page type to screenshot. If provided, the - * system will scrape the domain's links and use heuristics to find the most - * appropriate URL for the specified page type (30 supported languages). If not - * provided, screenshots the main domain landing page. Only applicable when using - * 'domain', not 'directUrl'. - */ - page?: 'login' | 'signup' | 'blog' | 'careers' | 'pricing' | 'terms' | 'privacy' | 'contact'; - - /** - * Optional vertical scroll offset in pixels for capturing a long page in - * viewport-sized chunks. When provided, the full page is captured once and the - * returned image is the viewport-sized slice that begins at this Y offset (e.g. - * request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page - * top to bottom). The final slice may be shorter than the viewport height. Takes - * precedence over fullScreenshot. Max: 100000. - */ - scrollOffset?: number | null; - - /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebScreenshotParams.TimeoutOpts; - - /** - * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. - */ - viewport?: WebScreenshotParams.Viewport; - - /** - * Optional browser wait time in milliseconds after initial page load before taking - * the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when - * omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at - * least waitForMs + 10000 ms; a shorter deadline is rejected with 400 - * TIMEOUT_TOO_SHORT_FOR_WAIT. - */ - waitForMs?: number | null; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebScreenshotParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. - */ - behavior?: 'fail' | 'return-partial'; - } - - /** - * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. - */ - export interface Viewport { - /** - * Viewport height in pixels. - */ - height?: number; - - /** - * Viewport width in pixels. - */ - width?: number; - } -} - -export interface WebSearchParams { - /** - * Search query. Accepts natural language as well as Google-style search operators - * such as `site:`, `-site:`, `inurl:`, `intitle:`, quoted phrases, and `OR`. - */ - query: string; - - /** - * Two-letter ISO 3166-1 alpha-2 country code to localize results to a specific - * country (maps to Google's `gl` parameter). Example: "us", "gb", "de". - */ - country?: - | 'af' - | 'al' - | 'dz' - | 'as' - | 'ad' - | 'ao' - | 'ai' - | 'aq' - | 'ag' - | 'ar' - | 'am' - | 'aw' - | 'au' - | 'at' - | 'az' - | 'bs' - | 'bh' - | 'bd' - | 'bb' - | 'by' - | 'be' - | 'bz' - | 'bj' - | 'bm' - | 'bt' - | 'bo' - | 'ba' - | 'bw' - | 'bv' - | 'br' - | 'io' - | 'bn' - | 'bg' - | 'bf' - | 'bi' - | 'kh' - | 'cm' - | 'ca' - | 'cv' - | 'ky' - | 'cf' - | 'td' - | 'cl' - | 'cn' - | 'cx' - | 'cc' - | 'co' - | 'km' - | 'cg' - | 'cd' - | 'ck' - | 'cr' - | 'ci' - | 'hr' - | 'cu' - | 'cy' - | 'cz' - | 'dk' - | 'dj' - | 'dm' - | 'do' - | 'ec' - | 'eg' - | 'sv' - | 'gq' - | 'er' - | 'ee' - | 'et' - | 'fk' - | 'fo' - | 'fj' - | 'fi' - | 'fr' - | 'gf' - | 'pf' - | 'tf' - | 'ga' - | 'gm' - | 'ge' - | 'de' - | 'gh' - | 'gi' - | 'gr' - | 'gl' - | 'gd' - | 'gp' - | 'gu' - | 'gt' - | 'gn' - | 'gw' - | 'gy' - | 'ht' - | 'hm' - | 'va' - | 'hn' - | 'hk' - | 'hu' - | 'is' - | 'in' - | 'id' - | 'ir' - | 'iq' - | 'ie' - | 'il' - | 'it' - | 'jm' - | 'jp' - | 'jo' - | 'kz' - | 'ke' - | 'ki' - | 'kp' - | 'kr' - | 'kw' - | 'kg' - | 'la' - | 'lv' - | 'lb' - | 'ls' - | 'lr' - | 'ly' - | 'li' - | 'lt' - | 'lu' - | 'mo' - | 'mk' - | 'mg' - | 'mw' - | 'my' - | 'mv' - | 'ml' - | 'mt' - | 'mh' - | 'mq' - | 'mr' - | 'mu' - | 'yt' - | 'mx' - | 'fm' - | 'md' - | 'mc' - | 'mn' - | 'ms' - | 'ma' - | 'mz' - | 'mm' - | 'na' - | 'nr' - | 'np' - | 'nl' - | 'an' - | 'nc' - | 'nz' - | 'ni' - | 'ne' - | 'ng' - | 'nu' - | 'nf' - | 'mp' - | 'no' - | 'om' - | 'pk' - | 'pw' - | 'ps' - | 'pa' - | 'pg' - | 'py' - | 'pe' - | 'ph' - | 'pn' - | 'pl' - | 'pt' - | 'pr' - | 'qa' - | 're' - | 'ro' - | 'ru' - | 'rw' - | 'sh' - | 'kn' - | 'lc' - | 'pm' - | 'vc' - | 'ws' - | 'sm' - | 'st' - | 'sa' - | 'sn' - | 'rs' - | 'sc' - | 'sl' - | 'sg' - | 'sk' - | 'si' - | 'sb' - | 'so' - | 'za' - | 'gs' - | 'es' - | 'lk' - | 'sd' - | 'sr' - | 'sj' - | 'sz' - | 'se' - | 'ch' - | 'sy' - | 'tw' - | 'tj' - | 'tz' - | 'th' - | 'tl' - | 'tg' - | 'tk' - | 'to' - | 'tt' - | 'tn' - | 'tr' - | 'tm' - | 'tc' - | 'tv' - | 'ug' - | 'ua' - | 'ae' - | 'gb' - | 'us' - | 'um' - | 'uy' - | 'uz' - | 'vu' - | 've' - | 'vn' - | 'vg' - | 'vi' - | 'wf' - | 'eh' - | 'ye' - | 'zm' - | 'zw'; - - /** - * Blocklist — drop results from these domains. Example: ["pinterest.com", - * "reddit.com"]. - */ - excludeDomains?: Array; - - /** - * Restrict results to content published within this window. - */ - freshness?: 'last_24_hours' | 'last_week' | 'last_month' | 'last_year'; - - /** - * Allowlist — only return results from these domains. Example: ["arxiv.org", - * "github.com"]. - */ - includeDomains?: Array; - - /** - * Inline Markdown scraping for each result. Set `enabled: true` to activate. - */ - markdownOptions?: WebSearchParams.MarkdownOptions; - - /** - * Number of results to request and return (10–100). Defaults to 10. - */ - numResults?: number; - - /** - * Expand the query into multiple parallel variants for broader recall. - */ - queryFanout?: boolean; - - /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebSearchParams.TimeoutOpts; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebSearchParams { - /** - * Inline Markdown scraping for each result. Set `enabled: true` to activate. - */ - export interface MarkdownOptions { - /** - * Scrape each result to Markdown. Off by default to keep search cheap and fast. - */ - enabled?: boolean; - - /** - * Render iframe contents into the Markdown. - */ - includeFrames?: boolean; - - /** - * Emit image references in the Markdown. - */ - includeImages?: boolean; - - /** - * Keep hyperlinks in the Markdown. - */ - includeLinks?: boolean; - - /** - * Cache TTL in ms for scraped Markdown keyed by URL + options. Default 1 day, max - * 30 days. Set to 0 to force a fresh scrape. - */ - maxAgeMs?: number; - - /** - * PDF handling. Use start/end to bound text extraction and OCR to a page range. - */ - pdf?: MarkdownOptions.Pdf; - - /** - * Truncate inline base64 image payloads to keep responses small. - */ - shortenBase64Images?: boolean; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: MarkdownOptions.TimeoutOpts; - - /** - * Strip nav, header, footer, and sidebar — keep only the primary article content. - */ - useMainContentOnly?: boolean; - - /** - * Extra wait after page load before rendering, in ms (0–30000). Useful for - * JS-heavy pages. - */ - waitForMs?: number; - } - - export namespace MarkdownOptions { - /** - * PDF handling. Use start/end to bound text extraction and OCR to a page range. - */ - export interface Pdf { - /** - * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must - * be >= start. - */ - end?: number; - - /** - * Parse PDF URLs. When false, PDF results are skipped with WEBSITE_ACCESS_ERROR. - */ - shouldParse?: boolean; - - /** - * First PDF page to parse (1-based, inclusive). Defaults to page 1. - */ - start?: number; - } - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. - */ - behavior?: 'fail' | 'return-partial'; - } - } - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export interface WebWebCrawlMdParams { - /** - * The starting URL for the crawl (must include http:// or https:// protocol) - */ - url: string; - - /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). - */ - country?: - | 'ad' - | 'ae' - | 'af' - | 'ag' - | 'ai' - | 'al' - | 'am' - | 'ao' - | 'ar' - | 'at' - | 'au' - | 'aw' - | 'az' - | 'ba' - | 'bb' - | 'bd' - | 'be' - | 'bf' - | 'bg' - | 'bh' - | 'bi' - | 'bj' - | 'bm' - | 'bn' - | 'bo' - | 'bq' - | 'br' - | 'bs' - | 'bw' - | 'by' - | 'bz' - | 'ca' - | 'cd' - | 'cf' - | 'cg' - | 'ch' - | 'ci' - | 'cl' - | 'cm' - | 'cn' - | 'co' - | 'cr' - | 'cv' - | 'cw' - | 'cy' - | 'cz' - | 'de' - | 'dj' - | 'dk' - | 'dm' - | 'do' - | 'dz' - | 'ec' - | 'ee' - | 'eg' - | 'es' - | 'et' - | 'fi' - | 'fj' - | 'fr' - | 'ga' - | 'gb' - | 'gd' - | 'ge' - | 'gf' - | 'gg' - | 'gh' - | 'gm' - | 'gn' - | 'gp' - | 'gq' - | 'gr' - | 'gt' - | 'gu' - | 'gw' - | 'gy' - | 'hk' - | 'hn' - | 'hr' - | 'ht' - | 'hu' - | 'id' - | 'ie' - | 'il' - | 'im' - | 'in' - | 'iq' - | 'ir' - | 'is' - | 'it' - | 'je' - | 'jm' - | 'jo' - | 'jp' - | 'ke' - | 'kg' - | 'kh' - | 'kn' - | 'kr' - | 'kw' - | 'ky' - | 'kz' - | 'la' - | 'lb' - | 'lc' - | 'lk' - | 'lr' - | 'ls' - | 'lt' - | 'lu' - | 'lv' - | 'ly' - | 'ma' - | 'mc' - | 'md' - | 'me' - | 'mf' - | 'mg' - | 'mk' - | 'ml' - | 'mm' - | 'mn' - | 'mo' - | 'mq' - | 'mr' - | 'mt' - | 'mu' - | 'mv' - | 'mw' - | 'mx' - | 'my' - | 'mz' - | 'na' - | 'nc' - | 'ne' - | 'ng' - | 'ni' - | 'nl' - | 'no' - | 'np' - | 'nz' - | 'om' - | 'pa' - | 'pe' - | 'pf' - | 'pg' - | 'ph' - | 'pk' - | 'pl' - | 'pr' - | 'ps' - | 'pt' - | 'py' - | 'qa' - | 're' - | 'ro' - | 'rs' - | 'ru' - | 'rw' - | 'sa' - | 'sc' - | 'sd' - | 'se' - | 'sg' - | 'si' - | 'sk' - | 'sl' - | 'sm' - | 'sn' - | 'so' - | 'sr' - | 'ss' - | 'st' - | 'sv' - | 'sx' - | 'sy' - | 'sz' - | 'tc' - | 'td' - | 'tg' - | 'th' - | 'tj' - | 'tl' - | 'tm' - | 'tn' - | 'tr' - | 'tt' - | 'tw' - | 'tz' - | 'ua' - | 'ug' - | 'us' - | 'uy' - | 'uz' - | 'vc' - | 've' - | 'vg' - | 'vi' - | 'vn' - | 'ye' - | 'yt' - | 'za' - | 'zm' - | 'zw'; - - /** - * CSS selectors to remove before each crawled page is converted to Markdown. - * Applied after includeSelectors. Exclusion takes precedence: an element matching - * both is removed. Examples: "nav", "footer", ".ad-banner", "[aria-hidden=true]". - */ - excludeSelectors?: Array; - - /** - * When true, follow links on subdomains of the starting URL's domain (e.g. - * docs.example.com when starting from example.com). www and apex are always - * treated as equivalent. - */ - followSubdomains?: boolean; - - /** - * When true, the contents of iframes are rendered to Markdown for each crawled - * page. - */ - includeFrames?: boolean; - - /** - * Include image references in the Markdown output - */ - includeImages?: boolean; - - /** - * Preserve hyperlinks in the Markdown output - */ - includeLinks?: boolean; - - /** - * CSS selectors. When provided, only matching HTML subtrees (and their - * descendants) are kept before each crawled page is converted to Markdown. When - * omitted, the entire document is kept. Examples: "article.main", "#content", - * "[role=main]". - */ - includeSelectors?: Array; - - /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. - */ - maxAgeMs?: number; - - /** - * Maximum link depth from the starting URL (0 = only the starting page) - */ - maxDepth?: number; - - /** - * Maximum number of pages to crawl. Hard cap: 500. - */ - maxPages?: number; - - /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. - */ - pdf?: WebWebCrawlMdParams.Pdf; - - /** - * When true, waits briefly for CSS and transition animations to settle before - * extracting each crawled page. Defaults to false. This adds a bit of latency in - * exchange for more stable output on animated pages. - */ - settleAnimations?: boolean; - - /** - * Truncate base64-encoded image data in the Markdown output - */ - shortenBase64Images?: boolean; - - /** - * Soft time budget for the crawl in milliseconds. After each scrape, the crawler - * checks the elapsed time and, if exceeded, returns the pages collected so far - * instead of continuing. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 - * (80s). - */ - stopAfterMs?: number; - - /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebWebCrawlMdParams.TimeoutOpts; - - /** - * Regex pattern. Only URLs matching this pattern will be followed and scraped. An - * automatic prefix scope in the form ^ follows a redirect of the - * starting page. - */ - urlRegex?: string; - - /** - * Extract only the main content, stripping headers, footers, sidebars, and - * navigation - */ - useMainContentOnly?: boolean; - - /** - * Browser wait time in milliseconds after initial page load for each crawled page. - * Defaults to 3500 (3.5 seconds). Min: 0. Max: 30000 (30 seconds). - */ - waitForMs?: number; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebWebCrawlMdParams { - /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. - */ - export interface Pdf { - /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. - */ - end?: number; - - /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. - */ - ocr?: boolean; - - /** - * When true, PDF pages are fetched and parsed. When false, PDF pages are skipped - * entirely (not included in results and not counted as failures). - */ - shouldParse?: boolean; - - /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. - */ - start?: number; - } - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export interface WebWebScrapeBytesParams { - /** - * Full HTTP(S) URL of the resource to download, such as an image, PDF, or page. - */ - url: string; - - /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). - */ - country?: - | 'ad' - | 'ae' - | 'af' - | 'ag' - | 'ai' - | 'al' - | 'am' - | 'ao' - | 'ar' - | 'at' - | 'au' - | 'aw' - | 'az' - | 'ba' - | 'bb' - | 'bd' - | 'be' - | 'bf' - | 'bg' - | 'bh' - | 'bi' - | 'bj' - | 'bm' - | 'bn' - | 'bo' - | 'bq' - | 'br' - | 'bs' - | 'bw' - | 'by' - | 'bz' - | 'ca' - | 'cd' - | 'cf' - | 'cg' - | 'ch' - | 'ci' - | 'cl' - | 'cm' - | 'cn' - | 'co' - | 'cr' - | 'cv' - | 'cw' - | 'cy' - | 'cz' - | 'de' - | 'dj' - | 'dk' - | 'dm' - | 'do' - | 'dz' - | 'ec' - | 'ee' - | 'eg' - | 'es' - | 'et' - | 'fi' - | 'fj' - | 'fr' - | 'ga' - | 'gb' - | 'gd' - | 'ge' - | 'gf' - | 'gg' - | 'gh' - | 'gm' - | 'gn' - | 'gp' - | 'gq' - | 'gr' - | 'gt' - | 'gu' - | 'gw' - | 'gy' - | 'hk' - | 'hn' - | 'hr' - | 'ht' - | 'hu' - | 'id' - | 'ie' - | 'il' - | 'im' - | 'in' - | 'iq' - | 'ir' - | 'is' - | 'it' - | 'je' - | 'jm' - | 'jo' - | 'jp' - | 'ke' - | 'kg' - | 'kh' - | 'kn' - | 'kr' - | 'kw' - | 'ky' - | 'kz' - | 'la' - | 'lb' - | 'lc' - | 'lk' - | 'lr' - | 'ls' - | 'lt' - | 'lu' - | 'lv' - | 'ly' - | 'ma' - | 'mc' - | 'md' - | 'me' - | 'mf' - | 'mg' - | 'mk' - | 'ml' - | 'mm' - | 'mn' - | 'mo' - | 'mq' - | 'mr' - | 'mt' - | 'mu' - | 'mv' - | 'mw' - | 'mx' - | 'my' - | 'mz' - | 'na' - | 'nc' - | 'ne' - | 'ng' - | 'ni' - | 'nl' - | 'no' - | 'np' - | 'nz' - | 'om' - | 'pa' - | 'pe' - | 'pf' - | 'pg' - | 'ph' - | 'pk' - | 'pl' - | 'pr' - | 'ps' - | 'pt' - | 'py' - | 'qa' - | 're' - | 'ro' - | 'rs' - | 'ru' - | 'rw' - | 'sa' - | 'sc' - | 'sd' - | 'se' - | 'sg' - | 'si' - | 'sk' - | 'sl' - | 'sm' - | 'sn' - | 'so' - | 'sr' - | 'ss' - | 'st' - | 'sv' - | 'sx' - | 'sy' - | 'sz' - | 'tc' - | 'td' - | 'tg' - | 'th' - | 'tj' - | 'tl' - | 'tm' - | 'tn' - | 'tr' - | 'tt' - | 'tw' - | 'tz' - | 'ua' - | 'ug' - | 'us' - | 'uy' - | 'uz' - | 'vc' - | 've' - | 'vg' - | 'vi' - | 'vn' - | 'ye' - | 'yt' - | 'za' - | 'zm' - | 'zw'; - - /** - * Optional outbound HTTP headers, such as Referer, Cookie, or Authorization. Send - * as a JSON object or deep-object query params such as - * headers[Referer]=https://example.com/. Host, Content-Length, and hop-by-hop - * transport headers are rejected. Authorization and cookies are removed when a - * redirect changes origin. Credential-bearing headers bypass cache reads and - * writes; other headers are included in the cache key. - */ - headers?: { [key: string]: string }; - - /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. - */ - maxAgeMs?: number | null; - - /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebWebScrapeBytesParams.TimeoutOpts; - - /** - * Optional browser wait time after initial page load, in milliseconds (0–30000; 0 - * uses 500). When supplied, HTML is rendered with JavaScript and returned as UTF-8 - * bytes. Other resources keep their original bytes without a browser wait. Omit to - * download the original HTTP response. When combined with timeoutOpts, - * timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter - * deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. - */ - waitForMs?: number | null; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebWebScrapeBytesParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. This endpoint supports "fail": return 408 - * REQUEST_TIMEOUT without charging credits. - */ - behavior?: 'fail'; - } -} - -export interface WebWebScrapeHTMLParams { - /** - * Full URL to scrape (must include http:// or https:// protocol) - */ - url: string; - - /** - * Optional browser actions executed in array order after the page loads and before - * content is captured. Requires a paid plan. Send a JSON array in the query - * parameter. Maximum: 5 actions. - */ - actions?: Array< - | WebWebScrapeHTMLParams.WebScrapeWaitAction - | WebWebScrapeHTMLParams.WebScrapePerformAction - | WebWebScrapeHTMLParams.WebScrapeScrollAction - > | null; - - /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). - */ - country?: - | 'ad' - | 'ae' - | 'af' - | 'ag' - | 'ai' - | 'al' - | 'am' - | 'ao' - | 'ar' - | 'at' - | 'au' - | 'aw' - | 'az' - | 'ba' - | 'bb' - | 'bd' - | 'be' - | 'bf' - | 'bg' - | 'bh' - | 'bi' - | 'bj' - | 'bm' - | 'bn' - | 'bo' - | 'bq' - | 'br' - | 'bs' - | 'bw' - | 'by' - | 'bz' - | 'ca' - | 'cd' - | 'cf' - | 'cg' - | 'ch' - | 'ci' - | 'cl' - | 'cm' - | 'cn' - | 'co' - | 'cr' - | 'cv' - | 'cw' - | 'cy' - | 'cz' - | 'de' - | 'dj' - | 'dk' - | 'dm' - | 'do' - | 'dz' - | 'ec' - | 'ee' - | 'eg' - | 'es' - | 'et' - | 'fi' - | 'fj' - | 'fr' - | 'ga' - | 'gb' - | 'gd' - | 'ge' - | 'gf' - | 'gg' - | 'gh' - | 'gm' - | 'gn' - | 'gp' - | 'gq' - | 'gr' - | 'gt' - | 'gu' - | 'gw' - | 'gy' - | 'hk' - | 'hn' - | 'hr' - | 'ht' - | 'hu' - | 'id' - | 'ie' - | 'il' - | 'im' - | 'in' - | 'iq' - | 'ir' - | 'is' - | 'it' - | 'je' - | 'jm' - | 'jo' - | 'jp' - | 'ke' - | 'kg' - | 'kh' - | 'kn' - | 'kr' - | 'kw' - | 'ky' - | 'kz' - | 'la' - | 'lb' - | 'lc' - | 'lk' - | 'lr' - | 'ls' - | 'lt' - | 'lu' - | 'lv' - | 'ly' - | 'ma' - | 'mc' - | 'md' - | 'me' - | 'mf' - | 'mg' - | 'mk' - | 'ml' - | 'mm' - | 'mn' - | 'mo' - | 'mq' - | 'mr' - | 'mt' - | 'mu' - | 'mv' - | 'mw' - | 'mx' - | 'my' - | 'mz' - | 'na' - | 'nc' - | 'ne' - | 'ng' - | 'ni' - | 'nl' - | 'no' - | 'np' - | 'nz' - | 'om' - | 'pa' - | 'pe' - | 'pf' - | 'pg' - | 'ph' - | 'pk' - | 'pl' - | 'pr' - | 'ps' - | 'pt' - | 'py' - | 'qa' - | 're' - | 'ro' - | 'rs' - | 'ru' - | 'rw' - | 'sa' - | 'sc' - | 'sd' - | 'se' - | 'sg' - | 'si' - | 'sk' - | 'sl' - | 'sm' - | 'sn' - | 'so' - | 'sr' - | 'ss' - | 'st' - | 'sv' - | 'sx' - | 'sy' - | 'sz' - | 'tc' - | 'td' - | 'tg' - | 'th' - | 'tj' - | 'tl' - | 'tm' - | 'tn' - | 'tr' - | 'tt' - | 'tw' - | 'tz' - | 'ua' - | 'ug' - | 'us' - | 'uy' - | 'uz' - | 'vc' - | 've' - | 'vg' - | 'vi' - | 'vn' - | 'ye' - | 'yt' - | 'za' - | 'zm' - | 'zw'; - - /** - * CSS selectors to remove from the result. Applied after includeSelectors. - * Exclusion takes precedence: an element matching both is removed. Examples: - * "nav", "footer", ".ad-banner", "[aria-hidden=true]". - */ - excludeSelectors?: Array | null; - - /** - * Optional CSS extraction rules applied to the returned HTML after selector and - * main-content filtering. Use selector strings ("h1", "a@href") or objects with - * selector, type (item or list), and output (text, html, @attribute, or nested - * rules). Text whitespace is normalized; html includes the matched element; - * attributes are returned as written. Missing items are null and missing lists are - * empty. CSS only; XPath is not supported. Maximum: 100 fields across 5 levels. - * Send a JSON-encoded string in the extractRules query parameter. - */ - extractRules?: { [key: string]: string | WebWebScrapeHTMLParams.UnionMember1 }; - - /** - * Optional outbound HTTP headers forwarded only to the target URL, sent as - * deep-object query params such as headers[X-Custom]=value. When provided, caching - * is bypassed: the result is neither read from nor written to cache. - */ - headers?: { [key: string]: string }; - - /** - * When true, iframes are rendered inline into the returned HTML. - */ - includeFrames?: boolean; - - /** - * CSS selectors. When provided, only matching subtrees (and their descendants) are - * kept and everything else is dropped. When omitted, the entire document is kept. - * Examples: "article.main", "#content", "[role=main]". - */ - includeSelectors?: Array | null; - - /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. - */ - maxAgeMs?: number | null; + * An inline image of the page. + */ + screenshot?: boolean; + } /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * Image options. Requires formats.images: true. */ - pdf?: WebWebScrapeHTMLParams.Pdf; + export interface ImageParams { + /** + * For visual duplicates, keep the largest image. + */ + dedupe?: 'none' | 'visual'; - /** - * When true, waits briefly for CSS and transition animations to settle before - * extracting HTML. Defaults to false. This adds a bit of latency in exchange for - * more stable output on animated pages. - */ - settleAnimations?: boolean; + /** + * Add dimensions, a visual category, or a hosted file URL. Each image has a + * maximum processing time of 30000 milliseconds, bounded by the remaining request + * deadline. + */ + enrich?: Array<'dimensions' | 'classification' | 'file'>; + } /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Markdown options. Requires formats.markdown: true. */ - tags?: Array; + export interface MarkdownParams { + includeImages?: boolean; - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebWebScrapeHTMLParams.TimeoutOpts; + includeLinks?: boolean; - /** - * When true, return only the page's main content in the HTML response, excluding - * headers, footers, sidebars, and navigation when detectable. - */ - useMainContentOnly?: boolean; + /** + * Base64 images use placeholders by default. Requires includeImages: true. + */ + inlineImages?: 'placeholder' | 'preserve'; + } /** - * Optional browser wait time in milliseconds after initial page load. Min: 0. Max: - * 30000 (30 seconds). When combined with timeoutOpts, timeoutOpts.milliseconds - * must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 - * TIMEOUT_TOO_SHORT_FOR_WAIT. + * Required when formats.parse is true. */ - waitForMs?: number | null; + export interface ParseParams { + /** + * Map field names to CSS selectors or rules. Missing items return null; missing + * lists return []. + */ + rules: { [key: string]: string | ParseParams.UnionMember1 }; + } - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} + export namespace ParseParams { + export interface UnionMember1 { + selector: string; -export namespace WebWebScrapeHTMLParams { - /** - * Pause for a fixed number of milliseconds before continuing to the next action. - */ - export interface WebScrapeWaitAction { - do: 'wait'; + output?: 'text' | 'html' | string | unknown; - timeMs: number; + type?: 'item' | 'list'; + } } /** - * Resolve and perform one natural-language browser action. + * Screenshot options. Requires formats.screenshot: true. */ - export interface WebScrapePerformAction { - action: string; + export interface ScreenshotParams { + /** + * Viewport, full page, one visible element, or a rectangle. Maximum 40 megapixels. + */ + area?: 'viewport' | 'fullPage' | ScreenshotParams.Element | ScreenshotParams.Rectangle; + + format?: 'png' | 'jpeg' | 'webp'; + } + + export namespace ScreenshotParams { + export interface Element { + /** + * Must match one visible element. + */ + selector: string; + } + + /** + * Pixels from the document origin. + */ + export interface Rectangle { + height: number; + + width: number; + + x: number; - do: 'perform'; + y: number; + } } /** - * Scroll the page or a selected scrollable container, waiting adaptively for - * content and dimensions to settle after each iteration. + * Shared browser and content settings. Content filters leave screenshots and + * original bytes unchanged. */ - export interface WebScrapeScrollAction { - do: 'scroll'; + export interface SharedParams { + /** + * Run in order before capture. A failed action fails the request. Bypasses + * caching. + */ + actions?: Array; /** - * Pixels per scroll, one visible viewport, or the current scroll boundary. - * Defaults to viewport. + * Supported two-letter country code, case-insensitive. Applies to every output, + * including image downloads. */ - amount?: number | 'viewport' | 'max'; + country?: string; /** - * CSS selector for the first matching scroll container. Defaults to the page. + * Dismiss cookie banners by accepting cookies before actions. */ - container?: string; + dismissCookies?: boolean; /** - * Direction to scroll. Defaults to down. + * Dismiss other popups before actions. */ - direction?: 'up' | 'down' | 'left' | 'right'; + dismissPopups?: boolean; /** - * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop - * changing. Defaults to 1. + * Remove matching content. Exclusions win. */ - maxScrolls?: number; - } + excludeSelectors?: Array; - export interface UnionMember1 { - selector: string; + /** + * Headers for the target origin. Requests with custom headers bypass caching. + */ + headers?: { [key: string]: string }; - output?: 'text' | 'html' | string | { [key: string]: string | UnionMember1.UnionMember1 }; + /** + * Include iframe content in extraction. Screenshots show visible frames + * regardless. + */ + includeFrames?: boolean; - type?: 'item' | 'list'; - } + /** + * Keep matching content after mainContentOnly. + */ + includeSelectors?: Array; - export namespace UnionMember1 { - export interface UnionMember1 { - selector: string; + /** + * Keep only main content in HTML, Markdown, images, and parsed fields. + */ + mainContentOnly?: boolean; - output?: 'text' | 'html' | string | unknown; + /** + * Document parsing options. + */ + parsers?: SharedParams.Parsers; - type?: 'item' | 'list'; - } - } + /** + * Settle animations before capture. Defaults to true with screenshots, otherwise + * false. + */ + settleAnimations?: boolean; - /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. - */ - export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Override the browser color scheme. */ - end?: number; + theme?: 'light' | 'dark'; /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. When false, no OCR runs. + * Browser dimensions in pixels. */ - ocr?: boolean; + viewport?: SharedParams.Viewport; /** - * When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and - * a 400 PDF_SKIPPED is returned. + * After actions, wait this many milliseconds or until a CSS selector is visible. + * Defaults to 500 ms, or 2000 ms with frames or an XML URL. Set 0 to skip. */ - shouldParse?: boolean; + waitFor?: number | string; + } + + export namespace SharedParams { + export interface Perform { + action: string; + + type: 'perform'; + } + + export interface Scroll { + type: 'scroll'; + + amount?: number | 'viewport' | 'max'; + + direction?: 'down' | 'up' | 'left' | 'right'; + + maxScrolls?: number; + + /** + * Scroll this container. Omit to scroll the page. + */ + selector?: string; + } + + export interface Wait { + milliseconds: number; + + type: 'wait'; + } + + export interface WaitFor { + selector: string; + + type: 'waitFor'; + } /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * Document parsing options. */ - start?: number; + export interface Parsers { + /** + * PDF text options for HTML, Markdown, and parsed fields. + */ + pdf?: Parsers.Pdf; + } + + export namespace Parsers { + /** + * PDF text options for HTML, Markdown, and parsed fields. + */ + export interface Pdf { + /** + * Last page to parse. Must be at least startPage. + */ + endPage?: number; + + /** + * Read text from scanned pages. + */ + ocr?: 'off' | 'auto'; + + /** + * First page to parse, starting at 1. + */ + startPage?: number; + } + } + + /** + * Browser dimensions in pixels. + */ + export interface Viewport { + height?: number; + + width?: number; + } } /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Total deadline, including navigation, actions, waiting, and all outputs. + * Defaults to 60000 milliseconds with behavior fail. Use return-partial to capture + * the current page state and return captured images if image processing cannot + * finish before the deadline; these responses set isPartial and are not cached. + * Every requested format must still be available. Fixed waits must fit before a + * response reserve of up to 5000 milliseconds (at most one quarter of the timeout) + * when using return-partial. */ export interface TimeoutOpts { /** @@ -5874,22 +2411,21 @@ export namespace WebWebScrapeHTMLParams { } } -export interface WebWebScrapeImagesParams { +export interface WebScreenshotParams { /** - * Page URL to inspect. Must include http:// or https://. + * Optional parameter for comprehensive popup cleanup. If 'true', the browser + * dismisses detected cookie/consent UI and clears other detected obstructive + * popups and overlays before capture. If 'false' or not provided, this parameter + * requests no cleanup; handleCookiePopup can still request cookie/consent handling + * independently. */ - url: string; + clearPopups?: boolean; /** - * Optional browser actions executed in array order after the page loads and before - * content is captured. Requires a paid plan. Send a JSON array in the query - * parameter. Maximum: 5 actions. + * Optional parameter to choose the site's visual theme in the screenshot. Use + * 'light' or 'dark' when the site offers both appearances. */ - actions?: Array< - | WebWebScrapeImagesParams.WebScrapeWaitAction - | WebWebScrapeImagesParams.WebScrapePerformAction - | WebWebScrapeImagesParams.WebScrapeScrollAction - > | null; + colorScheme?: 'light' | 'dark'; /** * Fetch the target page through a residential proxy in this country (ISO 3166-1 @@ -6102,32 +2638,70 @@ export interface WebWebScrapeImagesParams { | 'zw'; /** - * When true, visually duplicate images are removed: every image is loaded and - * perceptually hashed, and only the highest-resolution copy of each duplicate - * group is kept. Images that cannot be downloaded or hashed are kept. Default: - * false. + * A specific URL to screenshot directly, bypassing domain resolution (e.g., + * 'https://example.com/pricing'). When provided, the screenshot is taken of this + * exact URL. You must provide either 'domain' or 'directUrl', but not both. */ - dedupe?: boolean; + directUrl?: string; /** - * Optional per-image processing, sent as deep-object query params such as - * enrichment[resolution]=true. + * Domain name to take screenshot of (e.g., 'example.com', 'google.com'). The + * domain will be automatically normalized and validated. You must provide either + * 'domain' or 'directUrl', but not both. */ - enrichment?: WebWebScrapeImagesParams.Enrichment | null; + domain?: string; /** - * Optional outbound HTTP headers forwarded only to the target URL, sent as - * deep-object query params such as headers[X-Custom]=value. When provided, caching - * is bypassed: the result is neither read from nor written to cache. + * Optional parameter to determine screenshot type. If 'true', takes a full page + * screenshot capturing all content. If 'false' or not provided, takes a viewport + * screenshot (standard browser view). + */ + fullScreenshot?: 'true' | 'false'; + + /** + * Optional parameter to control cookie/consent popup handling. If 'true', we + * dismiss cookie banner before capture. If 'false' or not provided, captures the + * page without that step. + */ + handleCookiePopup?: boolean; + + /** + * Optional outbound HTTP headers, using the same JSON object or deep-object query + * format as other scrape endpoints (for example headers[Authorization]=Bearer + * token). Headers are scoped to the target origin during capture. For domain/page + * requests, discovery receives no custom headers and only pages on the resolved + * origin are eligible. Non-empty headers bypass screenshot caching and return an + * in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted + * headers. */ headers?: { [key: string]: string }; /** - * Reuse a cached result this many milliseconds old or newer. Default: 86400000 (1 - * day). Set to 0 to bypass cache. Maximum: 2592000000 (30 days). + * Return a cached screenshot if a prior screenshot for the same parameters exists + * and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when + * omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh. */ maxAgeMs?: number | null; + /** + * Optional parameter to specify which page type to screenshot. If provided, the + * system will scrape the domain's links and use heuristics to find the most + * appropriate URL for the specified page type (30 supported languages). If not + * provided, screenshots the main domain landing page. Only applicable when using + * 'domain', not 'directUrl'. + */ + page?: 'login' | 'signup' | 'blog' | 'careers' | 'pricing' | 'terms' | 'privacy' | 'contact'; + + /** + * Optional vertical scroll offset in pixels for capturing a long page in + * viewport-sized chunks. When provided, the full page is captured once and the + * returned image is the viewport-sized slice that begins at this Y offset (e.g. + * request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page + * top to bottom). The final slice may be shorter than the viewport height. Takes + * precedence over fullScreenshot. Max: 100000. + */ + scrollOffset?: number | null; + /** * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 * characters. @@ -6139,13 +2713,19 @@ export interface WebWebScrapeImagesParams { * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded * timeoutOpts object. */ - timeoutOpts?: WebWebScrapeImagesParams.TimeoutOpts; + timeoutOpts?: WebScreenshotParams.TimeoutOpts; + + /** + * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. + */ + viewport?: WebScreenshotParams.Viewport; /** - * Optional browser wait time in milliseconds after initial page load before - * collecting images. Min: 0. Max: 30000 (30 seconds). When combined with - * timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a - * shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. + * Optional browser wait time in milliseconds after initial page load before taking + * the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when + * omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at + * least waitForMs + 10000 ms; a shorter deadline is rejected with 400 + * TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; @@ -6159,82 +2739,7 @@ export interface WebWebScrapeImagesParams { zdr?: 'enabled' | 'disabled'; } -export namespace WebWebScrapeImagesParams { - /** - * Pause for a fixed number of milliseconds before continuing to the next action. - */ - export interface WebScrapeWaitAction { - do: 'wait'; - - timeMs: number; - } - - /** - * Resolve and perform one natural-language browser action. - */ - export interface WebScrapePerformAction { - action: string; - - do: 'perform'; - } - - /** - * Scroll the page or a selected scrollable container, waiting adaptively for - * content and dimensions to settle after each iteration. - */ - export interface WebScrapeScrollAction { - do: 'scroll'; - - /** - * Pixels per scroll, one visible viewport, or the current scroll boundary. - * Defaults to viewport. - */ - amount?: number | 'viewport' | 'max'; - - /** - * CSS selector for the first matching scroll container. Defaults to the page. - */ - container?: string; - - /** - * Direction to scroll. Defaults to down. - */ - direction?: 'up' | 'down' | 'left' | 'right'; - - /** - * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop - * changing. Defaults to 1. - */ - maxScrolls?: number; - } - - /** - * Optional per-image processing, sent as deep-object query params such as - * enrichment[resolution]=true. - */ - export interface Enrichment { - /** - * Classify each image by visual asset type. - */ - classification?: boolean; - - /** - * Host materializable images on the Brand.dev CDN and return their URL and MIME - * type. Ignored when zero data retention is enabled. - */ - hostedUrl?: boolean; - - /** - * Per-image enrichment timeout in milliseconds. Default: 30000. Maximum: 60000. - */ - maxTimePerMs?: number; - - /** - * Measure image width and height when possible. - */ - resolution?: boolean; - } - +export namespace WebScreenshotParams { /** * Optional request deadline and behavior on timeout. For GET requests, use * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded @@ -6255,307 +2760,309 @@ export namespace WebWebScrapeImagesParams { */ behavior?: 'fail' | 'return-partial'; } -} -export interface WebWebScrapeMdParams { /** - * Full URL to scrape into LLM usable Markdown (must include http:// or https:// - * protocol) + * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. */ - url: string; + export interface Viewport { + /** + * Viewport height in pixels. + */ + height?: number; + + /** + * Viewport width in pixels. + */ + width?: number; + } +} +export interface WebSearchParams { /** - * Optional browser actions executed in array order after the page loads and before - * content is captured. Requires a paid plan. Send a JSON array in the query - * parameter. Maximum: 5 actions. + * Search query. Accepts natural language as well as Google-style search operators + * such as `site:`, `-site:`, `inurl:`, `intitle:`, quoted phrases, and `OR`. */ - actions?: Array< - | WebWebScrapeMdParams.WebScrapeWaitAction - | WebWebScrapeMdParams.WebScrapePerformAction - | WebWebScrapeMdParams.WebScrapeScrollAction - > | null; + query: string; /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). + * Two-letter ISO 3166-1 alpha-2 country code to localize results to a specific + * country (maps to Google's `gl` parameter). Example: "us", "gb", "de". */ country?: - | 'ad' - | 'ae' | 'af' - | 'ag' - | 'ai' | 'al' - | 'am' + | 'dz' + | 'as' + | 'ad' | 'ao' + | 'ai' + | 'aq' + | 'ag' | 'ar' - | 'at' - | 'au' + | 'am' | 'aw' + | 'au' + | 'at' | 'az' - | 'ba' - | 'bb' + | 'bs' + | 'bh' | 'bd' + | 'bb' + | 'by' | 'be' - | 'bf' - | 'bg' - | 'bh' - | 'bi' + | 'bz' | 'bj' | 'bm' - | 'bn' + | 'bt' | 'bo' - | 'bq' - | 'br' - | 'bs' + | 'ba' | 'bw' - | 'by' - | 'bz' + | 'bv' + | 'br' + | 'io' + | 'bn' + | 'bg' + | 'bf' + | 'bi' + | 'kh' + | 'cm' | 'ca' - | 'cd' + | 'cv' + | 'ky' | 'cf' - | 'cg' - | 'ch' - | 'ci' + | 'td' | 'cl' - | 'cm' | 'cn' + | 'cx' + | 'cc' | 'co' + | 'km' + | 'cg' + | 'cd' + | 'ck' | 'cr' - | 'cv' - | 'cw' + | 'ci' + | 'hr' + | 'cu' | 'cy' | 'cz' - | 'de' - | 'dj' | 'dk' + | 'dj' | 'dm' | 'do' - | 'dz' | 'ec' - | 'ee' | 'eg' - | 'es' + | 'sv' + | 'gq' + | 'er' + | 'ee' | 'et' - | 'fi' + | 'fk' + | 'fo' | 'fj' + | 'fi' | 'fr' + | 'gf' + | 'pf' + | 'tf' | 'ga' - | 'gb' - | 'gd' + | 'gm' | 'ge' - | 'gf' - | 'gg' + | 'de' | 'gh' - | 'gm' - | 'gn' - | 'gp' - | 'gq' + | 'gi' | 'gr' - | 'gt' + | 'gl' + | 'gd' + | 'gp' | 'gu' + | 'gt' + | 'gn' | 'gw' | 'gy' - | 'hk' - | 'hn' - | 'hr' | 'ht' + | 'hm' + | 'va' + | 'hn' + | 'hk' | 'hu' + | 'is' + | 'in' | 'id' + | 'ir' + | 'iq' | 'ie' | 'il' - | 'im' - | 'in' - | 'iq' - | 'ir' - | 'is' | 'it' - | 'je' | 'jm' - | 'jo' | 'jp' + | 'jo' + | 'kz' | 'ke' - | 'kg' - | 'kh' - | 'kn' + | 'ki' + | 'kp' | 'kr' | 'kw' - | 'ky' - | 'kz' + | 'kg' | 'la' + | 'lv' | 'lb' - | 'lc' - | 'lk' - | 'lr' | 'ls' + | 'lr' + | 'ly' + | 'li' | 'lt' | 'lu' - | 'lv' - | 'ly' - | 'ma' - | 'mc' - | 'md' - | 'me' - | 'mf' - | 'mg' + | 'mo' | 'mk' + | 'mg' + | 'mw' + | 'my' + | 'mv' | 'ml' - | 'mm' - | 'mn' - | 'mo' + | 'mt' + | 'mh' | 'mq' | 'mr' - | 'mt' | 'mu' - | 'mv' - | 'mw' + | 'yt' | 'mx' - | 'my' + | 'fm' + | 'md' + | 'mc' + | 'mn' + | 'ms' + | 'ma' | 'mz' + | 'mm' | 'na' + | 'nr' + | 'np' + | 'nl' + | 'an' | 'nc' + | 'nz' + | 'ni' | 'ne' | 'ng' - | 'ni' - | 'nl' + | 'nu' + | 'nf' + | 'mp' | 'no' - | 'np' - | 'nz' | 'om' + | 'pk' + | 'pw' + | 'ps' | 'pa' - | 'pe' - | 'pf' | 'pg' + | 'py' + | 'pe' | 'ph' - | 'pk' + | 'pn' | 'pl' - | 'pr' - | 'ps' | 'pt' - | 'py' + | 'pr' | 'qa' | 're' | 'ro' - | 'rs' | 'ru' | 'rw' + | 'sh' + | 'kn' + | 'lc' + | 'pm' + | 'vc' + | 'ws' + | 'sm' + | 'st' | 'sa' + | 'sn' + | 'rs' | 'sc' - | 'sd' - | 'se' + | 'sl' | 'sg' - | 'si' | 'sk' - | 'sl' - | 'sm' - | 'sn' + | 'si' + | 'sb' | 'so' + | 'za' + | 'gs' + | 'es' + | 'lk' + | 'sd' | 'sr' - | 'ss' - | 'st' - | 'sv' - | 'sx' - | 'sy' + | 'sj' | 'sz' - | 'tc' - | 'td' - | 'tg' - | 'th' + | 'se' + | 'ch' + | 'sy' + | 'tw' | 'tj' + | 'tz' + | 'th' | 'tl' - | 'tm' + | 'tg' + | 'tk' + | 'to' + | 'tt' | 'tn' | 'tr' - | 'tt' - | 'tw' - | 'tz' - | 'ua' + | 'tm' + | 'tc' + | 'tv' | 'ug' + | 'ua' + | 'ae' + | 'gb' | 'us' + | 'um' | 'uy' | 'uz' - | 'vc' + | 'vu' | 've' + | 'vn' | 'vg' | 'vi' - | 'vn' + | 'wf' + | 'eh' | 'ye' - | 'yt' - | 'za' | 'zm' | 'zw'; /** - * CSS selectors to remove before conversion to Markdown. Applied after - * includeSelectors. Exclusion takes precedence: an element matching both is - * removed. Examples: "nav", "footer", ".ad-banner", "[aria-hidden=true]". - */ - excludeSelectors?: Array | null; - - /** - * Optional outbound HTTP headers forwarded only to the target URL, sent as - * deep-object query params such as headers[X-Custom]=value. When provided, caching - * is bypassed: the result is neither read from nor written to cache. - */ - headers?: { [key: string]: string }; - - /** - * When true, the contents of iframes are rendered to Markdown. - */ - includeFrames?: boolean; - - /** - * When true, the response also includes an `html` field with the page HTML the - * Markdown was converted from — the same body the Scrape HTML endpoint returns for - * the equivalent request. - */ - includeHTML?: boolean; - - /** - * Include image references in Markdown output - */ - includeImages?: boolean; - - /** - * Preserve hyperlinks in Markdown output + * Blocklist — drop results from these domains. Example: ["pinterest.com", + * "reddit.com"]. */ - includeLinks?: boolean; + excludeDomains?: Array; /** - * CSS selectors. When provided, only matching HTML subtrees (and their - * descendants) are kept before conversion to Markdown. When omitted, the entire - * document is kept. Examples: "article.main", "#content", "[role=main]". + * Restrict results to content published within this window. */ - includeSelectors?: Array | null; + freshness?: 'last_24_hours' | 'last_week' | 'last_month' | 'last_year'; /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * Allowlist — only return results from these domains. Example: ["arxiv.org", + * "github.com"]. */ - maxAgeMs?: number | null; + includeDomains?: Array; /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * Inline Markdown scraping for each result. Set `enabled: true` to activate. */ - pdf?: WebWebScrapeMdParams.Pdf; + markdownOptions?: WebSearchParams.MarkdownOptions; /** - * When true, waits briefly for CSS and transition animations to settle before - * converting to Markdown. Defaults to false. This adds a bit of latency in - * exchange for more stable output on animated pages. + * Number of results to request and return (10–100). Defaults to 10. */ - settleAnimations?: boolean; + numResults?: number; /** - * Shorten base64-encoded image data in the Markdown output + * Expand the query into multiple parallel variants for broader recall. */ - shortenBase64Images?: boolean; + queryFanout?: boolean; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. */ tags?: Array; @@ -6564,21 +3071,7 @@ export interface WebWebScrapeMdParams { * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded * timeoutOpts object. */ - timeoutOpts?: WebWebScrapeMdParams.TimeoutOpts; - - /** - * Extract only the main content of the page, excluding headers, footers, sidebars, - * and navigation - */ - useMainContentOnly?: boolean; - - /** - * Optional browser wait time in milliseconds after initial page load before - * converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). When combined - * with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 - * ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. - */ - waitForMs?: number | null; + timeoutOpts?: WebSearchParams.TimeoutOpts; /** * Set to enabled to bypass shared caches and omit request and response content @@ -6590,84 +3083,108 @@ export interface WebWebScrapeMdParams { zdr?: 'enabled' | 'disabled'; } -export namespace WebWebScrapeMdParams { +export namespace WebSearchParams { /** - * Pause for a fixed number of milliseconds before continuing to the next action. + * Inline Markdown scraping for each result. Set `enabled: true` to activate. */ - export interface WebScrapeWaitAction { - do: 'wait'; + export interface MarkdownOptions { + /** + * Scrape each result to Markdown. Off by default to keep search cheap and fast. + */ + enabled?: boolean; - timeMs: number; - } + /** + * Render iframe contents into the Markdown. + */ + includeFrames?: boolean; - /** - * Resolve and perform one natural-language browser action. - */ - export interface WebScrapePerformAction { - action: string; + /** + * Emit image references in the Markdown. + */ + includeImages?: boolean; - do: 'perform'; - } + /** + * Keep hyperlinks in the Markdown. + */ + includeLinks?: boolean; - /** - * Scroll the page or a selected scrollable container, waiting adaptively for - * content and dimensions to settle after each iteration. - */ - export interface WebScrapeScrollAction { - do: 'scroll'; + /** + * Cache TTL in ms for scraped Markdown keyed by URL + options. Default 1 day, max + * 30 days. Set to 0 to force a fresh scrape. + */ + maxAgeMs?: number; /** - * Pixels per scroll, one visible viewport, or the current scroll boundary. - * Defaults to viewport. + * PDF handling. Use start/end to bound text extraction and OCR to a page range. */ - amount?: number | 'viewport' | 'max'; + pdf?: MarkdownOptions.Pdf; /** - * CSS selector for the first matching scroll container. Defaults to the page. + * Truncate inline base64 image payloads to keep responses small. */ - container?: string; + shortenBase64Images?: boolean; /** - * Direction to scroll. Defaults to down. + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - direction?: 'up' | 'down' | 'left' | 'right'; + timeoutOpts?: MarkdownOptions.TimeoutOpts; /** - * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop - * changing. Defaults to 1. + * Strip nav, header, footer, and sidebar — keep only the primary article content. */ - maxScrolls?: number; - } + useMainContentOnly?: boolean; - /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. - */ - export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Extra wait after page load before rendering, in ms (0–30000). Useful for + * JS-heavy pages. */ - end?: number; + waitForMs?: number; + } + export namespace MarkdownOptions { /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. When false, no OCR runs. + * PDF handling. Use start/end to bound text extraction and OCR to a page range. */ - ocr?: boolean; + export interface Pdf { + /** + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. + */ + end?: number; + + /** + * Parse PDF URLs. When false, PDF results are skipped with WEBSITE_ACCESS_ERROR. + */ + shouldParse?: boolean; - /** - * When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and - * a 400 PDF_SKIPPED is returned. - */ - shouldParse?: boolean; + /** + * First PDF page to parse (1-based, inclusive). Defaults to page 1. + */ + start?: number; + } /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - start?: number; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 5000. + */ + behavior?: 'fail' | 'return-partial'; + } } /** @@ -6685,30 +3202,17 @@ export namespace WebWebScrapeMdParams { * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. + * not cached as complete results. */ behavior?: 'fail' | 'return-partial'; } } -export interface WebWebScrapeScreenshotParams { - url: string; - - /** - * Optional parameter for comprehensive popup cleanup. If 'true', the browser - * dismisses detected cookie/consent UI and clears other detected obstructive - * popups and overlays before capture. If 'false' or not provided, this parameter - * requests no cleanup; handleCookiePopup can still request cookie/consent handling - * independently. - */ - clearPopups?: boolean; - +export interface WebWebCrawlMdParams { /** - * Optional parameter to choose the site's visual theme in the screenshot. Use - * 'light' or 'dark' when the site offers both appearances. + * The starting URL for the crawl (must include http:// or https:// protocol) */ - colorScheme?: 'light' | 'dark'; + url: string; /** * Fetch the target page through a residential proxy in this country (ISO 3166-1 @@ -6921,190 +3425,158 @@ export interface WebWebScrapeScreenshotParams { | 'zw'; /** - * Optional parameter to determine screenshot type. If 'true', takes a full page - * screenshot capturing all content. If 'false' or not provided, takes a viewport - * screenshot (standard browser view). + * CSS selectors to remove before each crawled page is converted to Markdown. + * Applied after includeSelectors. Exclusion takes precedence: an element matching + * both is removed. Examples: "nav", "footer", ".ad-banner", "[aria-hidden=true]". */ - fullScreenshot?: 'true' | 'false'; + excludeSelectors?: Array; /** - * Optional parameter to control cookie/consent popup handling. If 'true', we - * dismiss cookie banner before capture. If 'false' or not provided, captures the - * page without that step. + * When true, follow links on subdomains of the starting URL's domain (e.g. + * docs.example.com when starting from example.com). www and apex are always + * treated as equivalent. */ - handleCookiePopup?: boolean; + followSubdomains?: boolean; /** - * Optional outbound HTTP headers, using the same JSON object or deep-object query - * format as other scrape endpoints (for example headers[Authorization]=Bearer - * token). Headers are scoped to the target origin during capture. For domain/page - * requests, discovery receives no custom headers and only pages on the resolved - * origin are eligible. Non-empty headers bypass screenshot caching and return an - * in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted - * headers. + * When true, the contents of iframes are rendered to Markdown for each crawled + * page. */ - headers?: { [key: string]: string }; + includeFrames?: boolean; /** - * Return a cached screenshot if a prior screenshot for the same parameters exists - * and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh. + * Include image references in the Markdown output */ - maxAgeMs?: number | null; + includeImages?: boolean; /** - * Optional vertical scroll offset in pixels for capturing a long page in - * viewport-sized chunks. When provided, the full page is captured once and the - * returned image is the viewport-sized slice that begins at this Y offset (e.g. - * request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page - * top to bottom). The final slice may be shorter than the viewport height. Takes - * precedence over fullScreenshot. Max: 100000. + * Preserve hyperlinks in the Markdown output */ - scrollOffset?: number | null; + includeLinks?: boolean; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * CSS selectors. When provided, only matching HTML subtrees (and their + * descendants) are kept before each crawled page is converted to Markdown. When + * omitted, the entire document is kept. Examples: "article.main", "#content", + * "[role=main]". */ - tags?: Array; + includeSelectors?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Return a cached result if a prior scrape for the same parameters exists and is + * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when + * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. */ - timeoutOpts?: WebWebScrapeScreenshotParams.TimeoutOpts; + maxAgeMs?: number; /** - * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. + * Maximum link depth from the starting URL (0 = only the starting page) */ - viewport?: WebWebScrapeScreenshotParams.Viewport; + maxDepth?: number; /** - * Optional browser wait time in milliseconds after initial page load before taking - * the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when - * omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at - * least waitForMs + 10000 ms; a shorter deadline is rejected with 400 - * TIMEOUT_TOO_SHORT_FOR_WAIT. + * Maximum number of pages to crawl. Hard cap: 500. */ - waitForMs?: number | null; + maxPages?: number; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * PDF parsing controls. Use start/end to limit text extraction and embedded-image + * detection/OCR to an inclusive 1-based page range. */ - zdr?: 'enabled' | 'disabled'; -} + pdf?: WebWebCrawlMdParams.Pdf; -export namespace WebWebScrapeScreenshotParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * When true, waits briefly for CSS and transition animations to settle before + * extracting each crawled page. Defaults to false. This adds a bit of latency in + * exchange for more stable output on animated pages. */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. - */ - behavior?: 'fail' | 'return-partial'; - } + settleAnimations?: boolean; /** - * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. + * Truncate base64-encoded image data in the Markdown output */ - export interface Viewport { - /** - * Viewport height in pixels. - */ - height?: number; - - /** - * Viewport width in pixels. - */ - width?: number; - } -} + shortenBase64Images?: boolean; -export interface WebWebScrapeSitemapParams { /** - * Domain to build a sitemap for + * Soft time budget for the crawl in milliseconds. After each scrape, the crawler + * checks the elapsed time and, if exceeded, returns the pages collected so far + * instead of continuing. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 + * (80s). */ - domain: string; + stopAfterMs?: number; /** - * Optional outbound HTTP headers forwarded only to the target URL, sent as - * deep-object query params such as headers[X-Custom]=value. When provided, caching - * is bypassed: the result is neither read from nor written to cache. + * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. */ - headers?: { [key: string]: string }; + tags?: Array; /** - * When true, discover and include public pages and sitemaps on subdomains of the - * requested domain. Defaults to false. + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - includeSubdomains?: boolean; + timeoutOpts?: WebWebCrawlMdParams.TimeoutOpts; /** - * Maximum number of links to return from the sitemap crawl. Defaults to 10,000. - * Minimum is 1, maximum is 100,000. + * Regex pattern. Only URLs matching this pattern will be followed and scraped. An + * automatic prefix scope in the form ^ follows a redirect of the + * starting page. */ - maxLinks?: number; + urlRegex?: string; /** - * Optional search phrase. When provided, the crawled sitemap is filtered to the - * pages whose URLs are about that phrase, most relevant first, and the request - * costs 2 credits instead of 1. + * Extract only the main content, stripping headers, footers, sidebars, and + * navigation */ - search?: string; + useMainContentOnly?: boolean; /** - * Optional explicit sitemap URL. When provided, exactly this sitemap is crawled - * instead of discovering the domain's sitemaps. + * Browser wait time in milliseconds after initial page load for each crawled page. + * Defaults to 3500 (3.5 seconds). Min: 0. Max: 30000 (30 seconds). */ - sitemapUrl?: string; + waitForMs?: number; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Requires zero data retention to be enabled for your + * organization (contact support@context.dev), otherwise the request fails with + * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. */ - tags?: Array; + zdr?: 'enabled' | 'disabled'; +} +export namespace WebWebCrawlMdParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * PDF parsing controls. Use start/end to limit text extraction and embedded-image + * detection/OCR to an inclusive 1-based page range. */ - timeoutOpts?: WebWebScrapeSitemapParams.TimeoutOpts; + export interface Pdf { + /** + * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. + * Must be greater than or equal to start when both are provided. + */ + end?: number; - /** - * Optional RE2-compatible regex pattern. Only URLs matching this pattern are - * returned and counted against maxLinks. - */ - urlRegex?: string; + /** + * When true, OCR the selected PDF pages that have no usable text layer (scans), + * replacing each recovered page's text with the OCR result while pages with a real + * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top + * of the base request cost. + */ + ocr?: boolean; - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} + /** + * When true, PDF pages are fetched and parsed. When false, PDF pages are skipped + * entirely (not included in results and not counted as failures). + */ + shouldParse?: boolean; + + /** + * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + */ + start?: number; + } -export namespace WebWebScrapeSitemapParams { /** * Optional request deadline and behavior on timeout. For GET requests, use * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded @@ -7129,34 +3601,20 @@ export namespace WebWebScrapeSitemapParams { export declare namespace Web { export { type WebAnswersResponse as WebAnswersResponse, - type WebExtractResponse as WebExtractResponse, type WebExtractCompetitorsResponse as WebExtractCompetitorsResponse, - type WebExtractFontsResponse as WebExtractFontsResponse, type WebExtractStyleguideResponse as WebExtractStyleguideResponse, + type WebMapURLsResponse as WebMapURLsResponse, type WebScrapeResponse as WebScrapeResponse, type WebScreenshotResponse as WebScreenshotResponse, type WebSearchResponse as WebSearchResponse, type WebWebCrawlMdResponse as WebWebCrawlMdResponse, - type WebWebScrapeBytesResponse as WebWebScrapeBytesResponse, - type WebWebScrapeHTMLResponse as WebWebScrapeHTMLResponse, - type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, - type WebWebScrapeMdResponse as WebWebScrapeMdResponse, - type WebWebScrapeScreenshotResponse as WebWebScrapeScreenshotResponse, - type WebWebScrapeSitemapResponse as WebWebScrapeSitemapResponse, type WebAnswersParams as WebAnswersParams, - type WebExtractParams as WebExtractParams, type WebExtractCompetitorsParams as WebExtractCompetitorsParams, - type WebExtractFontsParams as WebExtractFontsParams, type WebExtractStyleguideParams as WebExtractStyleguideParams, + type WebMapURLsParams as WebMapURLsParams, type WebScrapeParams as WebScrapeParams, type WebScreenshotParams as WebScreenshotParams, type WebSearchParams as WebSearchParams, type WebWebCrawlMdParams as WebWebCrawlMdParams, - type WebWebScrapeBytesParams as WebWebScrapeBytesParams, - type WebWebScrapeHTMLParams as WebWebScrapeHTMLParams, - type WebWebScrapeImagesParams as WebWebScrapeImagesParams, - type WebWebScrapeMdParams as WebWebScrapeMdParams, - type WebWebScrapeScreenshotParams as WebWebScrapeScreenshotParams, - type WebWebScrapeSitemapParams as WebWebScrapeSitemapParams, }; } diff --git a/tests/api-resources/ai.test.ts b/tests/api-resources/ai.test.ts deleted file mode 100644 index dc2492b4..00000000 --- a/tests/api-resources/ai.test.ts +++ /dev/null @@ -1,56 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import ContextDev from 'context.dev'; - -const client = new ContextDev({ - apiKey: 'My API Key', - baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', -}); - -describe('resource ai', () => { - // Mock server tests are disabled - test.skip('extractProduct: only required params', async () => { - const responsePromise = client.ai.extractProduct({ url: 'https://example.com' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('extractProduct: required and optional params', async () => { - const response = await client.ai.extractProduct({ - url: 'https://example.com', - maxAgeMs: 0, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, - zdr: 'enabled', - }); - }); - - // Mock server tests are disabled - test.skip('extractProducts: only required params', async () => { - const responsePromise = client.ai.extractProducts({ domain: 'domain' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('extractProducts: required and optional params', async () => { - const response = await client.ai.extractProducts({ - domain: 'domain', - maxAgeMs: 0, - maxProducts: 1, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, - }); - }); -}); diff --git a/tests/api-resources/brand.test.ts b/tests/api-resources/brand.test.ts index b92d3c70..f1c14028 100644 --- a/tests/api-resources/brand.test.ts +++ b/tests/api-resources/brand.test.ts @@ -33,29 +33,6 @@ describe('resource brand', () => { }); }); - // Mock server tests are disabled - test.skip('retrieveSimplified: only required params', async () => { - const responsePromise = client.brand.retrieveSimplified({ domain: 'xxx' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('retrieveSimplified: required and optional params', async () => { - const response = await client.brand.retrieveSimplified({ - domain: 'xxx', - maxAgeMs: 0, - tags: ['production', 'team-alpha'], - theme: 'light', - timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, - }); - }); - // Mock server tests are disabled test.skip('search: only required params', async () => { const responsePromise = client.brand.search({ query: 'x' }); diff --git a/tests/api-resources/monitors.test.ts b/tests/api-resources/monitors.test.ts index 11777b0d..d93ec765 100644 --- a/tests/api-resources/monitors.test.ts +++ b/tests/api-resources/monitors.test.ts @@ -286,6 +286,35 @@ describe('resource monitors', () => { expect(dataAndResponse.response).toBe(rawResponse); }); + // Mock server tests are disabled + test.skip('retrieveRun: only required params', async () => { + const responsePromise = client.monitors.retrieveRun('run_123', { monitor_id: 'mon_123' }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('retrieveRun: required and optional params', async () => { + const response = await client.monitors.retrieveRun('run_123', { monitor_id: 'mon_123' }); + }); + + // Mock server tests are disabled + test.skip('rotateWebhookSecret', async () => { + const responsePromise = client.monitors.rotateWebhookSecret('mon_123'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + // Mock server tests are disabled test.skip('run', async () => { const responsePromise = client.monitors.run('mon_123'); diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 6990f8bf..9d3ed311 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -34,58 +34,6 @@ describe('resource web', () => { }); }); - // Mock server tests are disabled - test.skip('extract: only required params', async () => { - const responsePromise = client.web.extract({ - schema: { - type: 'bar', - properties: 'bar', - required: 'bar', - additionalProperties: 'bar', - }, - url: 'https://example.com', - }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('extract: required and optional params', async () => { - const response = await client.web.extract({ - schema: { - type: 'bar', - properties: 'bar', - required: 'bar', - additionalProperties: 'bar', - }, - url: 'https://example.com', - actions: [{ do: 'wait', timeMs: 0 }], - factCheck: true, - followSubdomains: true, - includeFrames: true, - instructions: 'instructions', - maxAgeMs: 0, - maxDepth: 0, - maxPages: 1, - pdf: { - end: 1, - shouldParse: true, - start: 1, - }, - settleAnimations: true, - stopAfterMs: 10000, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, - waitForMs: 0, - zdr: 'enabled', - }); - }); - // Mock server tests are disabled test.skip('extractCompetitors: only required params', async () => { const responsePromise = client.web.extractCompetitors({ domain: 'xxx' }); @@ -110,8 +58,8 @@ describe('resource web', () => { }); // Mock server tests are disabled - test.skip('extractFonts', async () => { - const responsePromise = client.web.extractFonts(); + test.skip('extractStyleguide', async () => { + const responsePromise = client.web.extractStyleguide(); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -122,16 +70,18 @@ describe('resource web', () => { }); // Mock server tests are disabled - test.skip('extractFonts: request options and params are passed correctly', async () => { + test.skip('extractStyleguide: request options and params are passed correctly', async () => { // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error await expect( - client.web.extractFonts( + client.web.extractStyleguide( { + colorScheme: 'light', directUrl: 'https://example.com', domain: 'xxx', maxAgeMs: 0, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1, behavior: 'fail' }, + zdr: 'enabled', }, { path: '/_stainless_unknown_path' }, ), @@ -139,8 +89,8 @@ describe('resource web', () => { }); // Mock server tests are disabled - test.skip('extractStyleguide', async () => { - const responsePromise = client.web.extractStyleguide(); + test.skip('mapUrls: only required params', async () => { + const responsePromise = client.web.mapUrls({ domain: 'xxx' }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -151,22 +101,19 @@ describe('resource web', () => { }); // Mock server tests are disabled - test.skip('extractStyleguide: request options and params are passed correctly', async () => { - // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error - await expect( - client.web.extractStyleguide( - { - colorScheme: 'light', - directUrl: 'https://example.com', - domain: 'xxx', - maxAgeMs: 0, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1, behavior: 'fail' }, - zdr: 'enabled', - }, - { path: '/_stainless_unknown_path' }, - ), - ).rejects.toThrow(ContextDev.NotFoundError); + test.skip('mapUrls: required and optional params', async () => { + const response = await client.web.mapUrls({ + domain: 'xxx', + headers: { foo: 'J!' }, + includeSubdomains: true, + maxLinks: 1, + search: 'help center and troubleshooting articles', + sitemapUrl: 'https://example.com', + tags: ['production', 'team-alpha'], + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, + urlRegex: '^https?://[^/]+/blog/', + zdr: 'enabled', + }); }); // Mock server tests are disabled @@ -237,7 +184,7 @@ describe('resource web', () => { waitFor: 500, }, tags: ['production', 'team-alpha'], - timeoutMs: 1, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, zdr: 'enabled', }); }); @@ -369,205 +316,4 @@ describe('resource web', () => { zdr: 'enabled', }); }); - - // Mock server tests are disabled - test.skip('webScrapeBytes: only required params', async () => { - const responsePromise = client.web.webScrapeBytes({ url: 'https://example.com' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('webScrapeBytes: required and optional params', async () => { - const response = await client.web.webScrapeBytes({ - url: 'https://example.com', - country: 'de', - headers: { foo: 'J!' }, - maxAgeMs: 0, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1, behavior: 'fail' }, - waitForMs: 0, - zdr: 'enabled', - }); - }); - - // Mock server tests are disabled - test.skip('webScrapeHTML: only required params', async () => { - const responsePromise = client.web.webScrapeHTML({ url: 'https://example.com' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('webScrapeHTML: required and optional params', async () => { - const response = await client.web.webScrapeHTML({ - url: 'https://example.com', - actions: [{ do: 'wait', timeMs: 0 }], - country: 'de', - excludeSelectors: ['x'], - extractRules: { foo: 'x' }, - headers: { foo: 'J!' }, - includeFrames: true, - includeSelectors: ['x'], - maxAgeMs: 0, - pdf: { - end: 1, - ocr: true, - shouldParse: true, - start: 1, - }, - settleAnimations: true, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1, behavior: 'fail' }, - useMainContentOnly: true, - waitForMs: 0, - zdr: 'enabled', - }); - }); - - // Mock server tests are disabled - test.skip('webScrapeImages: only required params', async () => { - const responsePromise = client.web.webScrapeImages({ url: 'https://example.com' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('webScrapeImages: required and optional params', async () => { - const response = await client.web.webScrapeImages({ - url: 'https://example.com', - actions: [{ do: 'wait', timeMs: 0 }], - country: 'de', - dedupe: true, - enrichment: { - classification: true, - hostedUrl: true, - maxTimePerMs: 1, - resolution: true, - }, - headers: { foo: 'J!' }, - maxAgeMs: 0, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1, behavior: 'fail' }, - waitForMs: 0, - zdr: 'enabled', - }); - }); - - // Mock server tests are disabled - test.skip('webScrapeMd: only required params', async () => { - const responsePromise = client.web.webScrapeMd({ url: 'https://example.com' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('webScrapeMd: required and optional params', async () => { - const response = await client.web.webScrapeMd({ - url: 'https://example.com', - actions: [{ do: 'wait', timeMs: 0 }], - country: 'de', - excludeSelectors: ['x'], - headers: { foo: 'J!' }, - includeFrames: true, - includeHTML: true, - includeImages: true, - includeLinks: true, - includeSelectors: ['x'], - maxAgeMs: 0, - pdf: { - end: 1, - ocr: true, - shouldParse: true, - start: 1, - }, - settleAnimations: true, - shortenBase64Images: true, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1, behavior: 'fail' }, - useMainContentOnly: true, - waitForMs: 0, - zdr: 'enabled', - }); - }); - - // Mock server tests are disabled - test.skip('webScrapeScreenshot: only required params', async () => { - const responsePromise = client.web.webScrapeScreenshot({ url: 'https://example.com' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('webScrapeScreenshot: required and optional params', async () => { - const response = await client.web.webScrapeScreenshot({ - url: 'https://example.com', - clearPopups: true, - colorScheme: 'light', - country: 'de', - fullScreenshot: 'true', - handleCookiePopup: true, - headers: { foo: 'J!' }, - maxAgeMs: 0, - scrollOffset: 0, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1, behavior: 'fail' }, - viewport: { height: 240, width: 240 }, - waitForMs: 0, - zdr: 'enabled', - }); - }); - - // Mock server tests are disabled - test.skip('webScrapeSitemap: only required params', async () => { - const responsePromise = client.web.webScrapeSitemap({ domain: 'xxx' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('webScrapeSitemap: required and optional params', async () => { - const response = await client.web.webScrapeSitemap({ - domain: 'xxx', - headers: { foo: 'J!' }, - includeSubdomains: true, - maxLinks: 1, - search: 'help center and troubleshooting articles', - sitemapUrl: 'https://example.com', - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1, behavior: 'fail' }, - urlRegex: '^https?://[^/]+/blog/', - zdr: 'enabled', - }); - }); }); From 3ded9dc0f8665d46c239d03eb1d7f85661699a5a Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 22 Sep 2026 06:30:02 +0000 Subject: [PATCH 067/232] seal --- .stats.yml | 2 +- api.md | 36 +- src/client.ts | 63 +- src/resources/ai.ts | 615 --- src/resources/brand.ts | 317 -- src/resources/index.ts | 30 +- src/resources/monitors.ts | 494 +++ src/resources/web.ts | 5530 +++++--------------------- tests/api-resources/ai.test.ts | 56 - tests/api-resources/brand.test.ts | 23 - tests/api-resources/monitors.test.ts | 29 + tests/api-resources/web.test.ts | 298 +- 12 files changed, 1561 insertions(+), 5932 deletions(-) delete mode 100644 src/resources/ai.ts delete mode 100644 tests/api-resources/ai.test.ts diff --git a/.stats.yml b/.stats.yml index c550abf3..48f88c43 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 51 +configured_endpoints: 43 diff --git a/api.md b/api.md index ec2596eb..c9330f41 100644 --- a/api.md +++ b/api.md @@ -13,63 +13,35 @@ Methods: Types: - WebAnswersResponse -- WebExtractResponse - WebExtractCompetitorsResponse -- WebExtractFontsResponse - WebExtractStyleguideResponse +- WebMapURLsResponse - WebScrapeResponse - WebScreenshotResponse - WebSearchResponse - WebWebCrawlMdResponse -- WebWebScrapeBytesResponse -- WebWebScrapeHTMLResponse -- WebWebScrapeImagesResponse -- WebWebScrapeMdResponse -- WebWebScrapeScreenshotResponse -- WebWebScrapeSitemapResponse Methods: - client.web.answers({ ...params }) -> WebAnswersResponse -- client.web.extract({ ...params }) -> WebExtractResponse - client.web.extractCompetitors({ ...params }) -> WebExtractCompetitorsResponse -- client.web.extractFonts({ ...params }) -> WebExtractFontsResponse - client.web.extractStyleguide({ ...params }) -> WebExtractStyleguideResponse +- client.web.mapUrls({ ...params }) -> WebMapURLsResponse - client.web.scrape({ ...params }) -> WebScrapeResponse - client.web.screenshot({ ...params }) -> WebScreenshotResponse - client.web.search({ ...params }) -> WebSearchResponse - client.web.webCrawlMd({ ...params }) -> WebWebCrawlMdResponse -- client.web.webScrapeBytes({ ...params }) -> WebWebScrapeBytesResponse -- client.web.webScrapeHTML({ ...params }) -> WebWebScrapeHTMLResponse -- client.web.webScrapeImages({ ...params }) -> WebWebScrapeImagesResponse -- client.web.webScrapeMd({ ...params }) -> WebWebScrapeMdResponse -- client.web.webScrapeScreenshot({ ...params }) -> WebWebScrapeScreenshotResponse -- client.web.webScrapeSitemap({ ...params }) -> WebWebScrapeSitemapResponse - -# AI - -Types: - -- AIExtractProductResponse -- AIExtractProductsResponse - -Methods: - -- client.ai.extractProduct({ ...params }) -> AIExtractProductResponse -- client.ai.extractProducts({ ...params }) -> AIExtractProductsResponse # Brand Types: - BrandRetrieveResponse -- BrandRetrieveSimplifiedResponse - BrandSearchResponse Methods: - client.brand.retrieve({ ...params }) -> BrandRetrieveResponse -- client.brand.retrieveSimplified({ ...params }) -> BrandRetrieveSimplifiedResponse - client.brand.search({ ...params }) -> BrandSearchResponse # Industry @@ -111,6 +83,8 @@ Types: - MonitorListChangesResponse - MonitorListRunsResponse - MonitorRetrieveChangeResponse +- MonitorRetrieveRunResponse +- MonitorRotateWebhookSecretResponse - MonitorRunResponse Methods: @@ -127,6 +101,8 @@ Methods: - client.monitors.listChanges(monitorID, { ...params }) -> MonitorListChangesResponse - client.monitors.listRuns(monitorID, { ...params }) -> MonitorListRunsResponse - client.monitors.retrieveChange(changeID) -> MonitorRetrieveChangeResponse +- client.monitors.retrieveRun(runID, { ...params }) -> MonitorRetrieveRunResponse +- client.monitors.rotateWebhookSecret(monitorID) -> MonitorRotateWebhookSecretResponse - client.monitors.run(monitorID) -> MonitorRunResponse # Batch diff --git a/src/client.ts b/src/client.ts index b8568076..d76ce6da 100644 --- a/src/client.ts +++ b/src/client.ts @@ -17,13 +17,6 @@ import * as Errors from './core/error'; import * as Uploads from './core/uploads'; import * as API from './resources/index'; import { APIPromise } from './core/api-promise'; -import { - AI, - AIExtractProductParams, - AIExtractProductResponse, - AIExtractProductsParams, - AIExtractProductsResponse, -} from './resources/ai'; import { Batch, BatchCancelResponse, @@ -44,8 +37,6 @@ import { Brand, BrandRetrieveParams, BrandRetrieveResponse, - BrandRetrieveSimplifiedParams, - BrandRetrieveSimplifiedResponse, BrandSearchParams, BrandSearchResponse, } from './resources/brand'; @@ -76,6 +67,9 @@ import { MonitorListRunsResponse, MonitorRetrieveChangeResponse, MonitorRetrieveResponse, + MonitorRetrieveRunParams, + MonitorRetrieveRunResponse, + MonitorRotateWebhookSecretResponse, MonitorRunResponse, MonitorUpdateParams, MonitorUpdateResponse, @@ -92,12 +86,10 @@ import { WebAnswersResponse, WebExtractCompetitorsParams, WebExtractCompetitorsResponse, - WebExtractFontsParams, - WebExtractFontsResponse, - WebExtractParams, - WebExtractResponse, WebExtractStyleguideParams, WebExtractStyleguideResponse, + WebMapURLsParams, + WebMapURLsResponse, WebScrapeParams, WebScrapeResponse, WebScreenshotParams, @@ -106,18 +98,6 @@ import { WebSearchResponse, WebWebCrawlMdParams, WebWebCrawlMdResponse, - WebWebScrapeBytesParams, - WebWebScrapeBytesResponse, - WebWebScrapeHTMLParams, - WebWebScrapeHTMLResponse, - WebWebScrapeImagesParams, - WebWebScrapeImagesResponse, - WebWebScrapeMdParams, - WebWebScrapeMdResponse, - WebWebScrapeScreenshotParams, - WebWebScrapeScreenshotResponse, - WebWebScrapeSitemapParams, - WebWebScrapeSitemapResponse, } from './resources/web'; import { RetryConfig, Webhooks } from './resources/webhooks/webhooks'; import { type Fetch } from './internal/builtin-types'; @@ -839,7 +819,6 @@ export class ContextDev { parse: API.Parse = new API.Parse(this); web: API.Web = new API.Web(this); - ai: API.AI = new API.AI(this); brand: API.Brand = new API.Brand(this); industry: API.Industry = new API.Industry(this); utility: API.Utility = new API.Utility(this); @@ -865,7 +844,6 @@ export class ContextDev { ContextDev.Parse = Parse; ContextDev.Web = Web; -ContextDev.AI = AI; ContextDev.Brand = Brand; ContextDev.Industry = Industry; ContextDev.Utility = Utility; @@ -888,52 +866,28 @@ export declare namespace ContextDev { export { Web as Web, type WebAnswersResponse as WebAnswersResponse, - type WebExtractResponse as WebExtractResponse, type WebExtractCompetitorsResponse as WebExtractCompetitorsResponse, - type WebExtractFontsResponse as WebExtractFontsResponse, type WebExtractStyleguideResponse as WebExtractStyleguideResponse, + type WebMapURLsResponse as WebMapURLsResponse, type WebScrapeResponse as WebScrapeResponse, type WebScreenshotResponse as WebScreenshotResponse, type WebSearchResponse as WebSearchResponse, type WebWebCrawlMdResponse as WebWebCrawlMdResponse, - type WebWebScrapeBytesResponse as WebWebScrapeBytesResponse, - type WebWebScrapeHTMLResponse as WebWebScrapeHTMLResponse, - type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, - type WebWebScrapeMdResponse as WebWebScrapeMdResponse, - type WebWebScrapeScreenshotResponse as WebWebScrapeScreenshotResponse, - type WebWebScrapeSitemapResponse as WebWebScrapeSitemapResponse, type WebAnswersParams as WebAnswersParams, - type WebExtractParams as WebExtractParams, type WebExtractCompetitorsParams as WebExtractCompetitorsParams, - type WebExtractFontsParams as WebExtractFontsParams, type WebExtractStyleguideParams as WebExtractStyleguideParams, + type WebMapURLsParams as WebMapURLsParams, type WebScrapeParams as WebScrapeParams, type WebScreenshotParams as WebScreenshotParams, type WebSearchParams as WebSearchParams, type WebWebCrawlMdParams as WebWebCrawlMdParams, - type WebWebScrapeBytesParams as WebWebScrapeBytesParams, - type WebWebScrapeHTMLParams as WebWebScrapeHTMLParams, - type WebWebScrapeImagesParams as WebWebScrapeImagesParams, - type WebWebScrapeMdParams as WebWebScrapeMdParams, - type WebWebScrapeScreenshotParams as WebWebScrapeScreenshotParams, - type WebWebScrapeSitemapParams as WebWebScrapeSitemapParams, - }; - - export { - AI as AI, - type AIExtractProductResponse as AIExtractProductResponse, - type AIExtractProductsResponse as AIExtractProductsResponse, - type AIExtractProductParams as AIExtractProductParams, - type AIExtractProductsParams as AIExtractProductsParams, }; export { Brand as Brand, type BrandRetrieveResponse as BrandRetrieveResponse, - type BrandRetrieveSimplifiedResponse as BrandRetrieveSimplifiedResponse, type BrandSearchResponse as BrandSearchResponse, type BrandRetrieveParams as BrandRetrieveParams, - type BrandRetrieveSimplifiedParams as BrandRetrieveSimplifiedParams, type BrandSearchParams as BrandSearchParams, }; @@ -966,6 +920,8 @@ export declare namespace ContextDev { type MonitorListChangesResponse as MonitorListChangesResponse, type MonitorListRunsResponse as MonitorListRunsResponse, type MonitorRetrieveChangeResponse as MonitorRetrieveChangeResponse, + type MonitorRetrieveRunResponse as MonitorRetrieveRunResponse, + type MonitorRotateWebhookSecretResponse as MonitorRotateWebhookSecretResponse, type MonitorRunResponse as MonitorRunResponse, type MonitorCreateParams as MonitorCreateParams, type MonitorUpdateParams as MonitorUpdateParams, @@ -975,6 +931,7 @@ export declare namespace ContextDev { type MonitorListAccountRunsParams as MonitorListAccountRunsParams, type MonitorListChangesParams as MonitorListChangesParams, type MonitorListRunsParams as MonitorListRunsParams, + type MonitorRetrieveRunParams as MonitorRetrieveRunParams, }; export { diff --git a/src/resources/ai.ts b/src/resources/ai.ts deleted file mode 100644 index 079505f4..00000000 --- a/src/resources/ai.ts +++ /dev/null @@ -1,615 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import { APIResource } from '../core/resource'; -import { APIPromise } from '../core/api-promise'; -import { RequestOptions } from '../internal/request-options'; - -export class AI extends APIResource { - /** - * Given a single URL, determines if it is a product page and extracts the product - * information. - * - * @example - * ```ts - * const response = await client.ai.extractProduct({ - * url: 'https://example.com', - * }); - * ``` - */ - extractProduct( - body: AIExtractProductParams, - options?: RequestOptions, - ): APIPromise { - return this._client.post('/brand/ai/product', { body, ...options }); - } - - /** - * Extract product information from a brand's website. We will analyze the website - * and return a list of products with details such as name, description, image, - * pricing, features, and more. - * - * @example - * ```ts - * const response = await client.ai.extractProducts({ - * domain: 'domain', - * }); - * ``` - */ - extractProducts( - body: AIExtractProductsParams, - options?: RequestOptions, - ): APIPromise { - return this._client.post('/brand/ai/products', { body, ...options }); - } -} - -export interface AIExtractProductResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: AIExtractProductResponse.CacheMetadata; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Whether the given URL is a product detail page - */ - is_product_page?: boolean; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: AIExtractProductResponse.KeyMetadata; - - /** - * True when the timeout ended processing and this response contains only usable - * results completed so far. Unfinished results are omitted. - */ - partial?: boolean; - - /** - * The detected ecommerce platform, or null if not a product page - */ - platform?: 'amazon' | 'tiktok_shop' | 'etsy' | 'generic' | null; - - /** - * The extracted product data, or null if not a product page - */ - product?: AIExtractProductResponse.Product | null; -} - -export namespace AIExtractProductResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } - - /** - * The extracted product data, or null if not a product page - */ - export interface Product { - /** - * Description of the product - */ - description: string; - - /** - * List of product features - */ - features: Array; - - /** - * URLs to product images on the page (up to 7) - */ - images: Array; - - /** - * Name of the product - */ - name: string; - - /** - * Stock Keeping Unit (product identifier). Null if no identifier is found. - */ - sku: string | null; - - /** - * Tags associated with the product - */ - tags: Array; - - /** - * Target audience for the product (array of strings) - */ - target_audience: Array; - - /** - * Normalized stock or ordering availability - */ - availability?: - | 'in_stock' - | 'out_of_stock' - | 'limited_availability' - | 'preorder' - | 'backorder' - | 'made_to_order' - | 'discontinued' - | null; - - /** - * Billing frequency for the product - */ - billing_frequency?: 'monthly' | 'yearly' | 'one_time' | 'usage_based' | null; - - /** - * Category of the product - */ - category?: string | null; - - /** - * Currency code for the price (e.g., USD, EUR) - */ - currency?: string | null; - - /** - * Dimension statements shown for the product, preserving labels, values, and units - */ - dimensions?: Array; - - /** - * URL to the product image - */ - image_url?: string | null; - - /** - * Price of the product - */ - price?: number | null; - - /** - * Pricing model for the product - */ - pricing_model?: 'per_seat' | 'flat' | 'tiered' | 'freemium' | 'custom' | null; - - /** - * Original or regular price before a displayed discount - */ - regular_price?: number | null; - - /** - * URL to the product page - */ - url?: string | null; - - /** - * Product variations, such as different colors or sizes, with their attributes and - * images. Empty if none are found. May not include every variation offered by the - * store. - */ - variants?: Array; - } - - export namespace Product { - export interface Variant { - /** - * Explicit variant attributes such as color, size, material, pattern and - * properties declared by page. - */ - attributes: { [key: string]: string }; - - /** - * Original source image URLs explicitly attached to this variant. - */ - images: Array; - - sku: string | null; - - /** - * Variant or offer URL when provided by the source. May be shared by variants. - */ - url: string | null; - } - } -} - -export interface AIExtractProductsResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: AIExtractProductsResponse.CacheMetadata; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: AIExtractProductsResponse.KeyMetadata; - - /** - * True when timeoutOpts.behavior=return-partial returned the usable results - * collected before the deadline. Partial collections are not cached as complete - * results. - */ - partial?: boolean; - - /** - * Array of products extracted from the website - */ - products?: Array; -} - -export namespace AIExtractProductsResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } - - export interface Product { - /** - * Description of the product - */ - description: string; - - /** - * List of product features - */ - features: Array; - - /** - * URLs to product images on the page (up to 7) - */ - images: Array; - - /** - * Name of the product - */ - name: string; - - /** - * Stock Keeping Unit (product identifier). Null if no identifier is found. - */ - sku: string | null; - - /** - * Tags associated with the product - */ - tags: Array; - - /** - * Target audience for the product (array of strings) - */ - target_audience: Array; - - /** - * Normalized stock or ordering availability - */ - availability?: - | 'in_stock' - | 'out_of_stock' - | 'limited_availability' - | 'preorder' - | 'backorder' - | 'made_to_order' - | 'discontinued' - | null; - - /** - * Billing frequency for the product - */ - billing_frequency?: 'monthly' | 'yearly' | 'one_time' | 'usage_based' | null; - - /** - * Category of the product - */ - category?: string | null; - - /** - * Currency code for the price (e.g., USD, EUR) - */ - currency?: string | null; - - /** - * Dimension statements shown for the product, preserving labels, values, and units - */ - dimensions?: Array; - - /** - * URL to the product image - */ - image_url?: string | null; - - /** - * Price of the product - */ - price?: number | null; - - /** - * Pricing model for the product - */ - pricing_model?: 'per_seat' | 'flat' | 'tiered' | 'freemium' | 'custom' | null; - - /** - * Original or regular price before a displayed discount - */ - regular_price?: number | null; - - /** - * URL to the product page - */ - url?: string | null; - - /** - * Product variations, such as different colors or sizes, with their attributes and - * images. Empty if none are found. May not include every variation offered by the - * store. - */ - variants?: Array; - } - - export namespace Product { - export interface Variant { - /** - * Explicit variant attributes such as color, size, material, pattern and - * properties declared by page. - */ - attributes: { [key: string]: string }; - - /** - * Original source image URLs explicitly attached to this variant. - */ - images: Array; - - sku: string | null; - - /** - * Variant or offer URL when provided by the source. May be shared by variants. - */ - url: string | null; - } - } -} - -export interface AIExtractProductParams { - /** - * The product page URL to extract product data from. - */ - url: string; - - /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 7 days (604800000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. - */ - maxAgeMs?: number; - - /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: AIExtractProductParams.TimeoutOpts; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace AIExtractProductParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export type AIExtractProductsParams = AIExtractProductsParams.ByDomain | AIExtractProductsParams.ByDirectURL; - -export declare namespace AIExtractProductsParams { - export interface ByDomain { - /** - * The domain name to analyze. - */ - domain: string; - - /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 7 days (604800000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. - */ - maxAgeMs?: number; - - /** - * Maximum number of products to extract. - */ - maxProducts?: number; - - /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: ByDomain.TimeoutOpts; - } - - export namespace ByDomain { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } - } - - export interface ByDirectURL { - /** - * A specific URL to use directly as the starting point for extraction without - * domain resolution. - */ - directUrl: string; - - /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 7 days (604800000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. - */ - maxAgeMs?: number; - - /** - * Maximum number of products to extract. - */ - maxProducts?: number; - - /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: ByDirectURL.TimeoutOpts; - } - - export namespace ByDirectURL { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } - } -} - -export declare namespace AI { - export { - type AIExtractProductResponse as AIExtractProductResponse, - type AIExtractProductsResponse as AIExtractProductsResponse, - type AIExtractProductParams as AIExtractProductParams, - type AIExtractProductsParams as AIExtractProductsParams, - }; -} diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 11e94515..28b9c457 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -24,25 +24,6 @@ export class Brand extends APIResource { return this._client.post('/brand/retrieve', { body, ...options }); } - /** - * Returns a simplified version of brand data containing only essential - * information: domain, title, colors, logos, and backdrops. Optimized for faster - * responses and reduced data transfer. - * - * @example - * ```ts - * const response = await client.brand.retrieveSimplified({ - * domain: 'xxx', - * }); - * ``` - */ - retrieveSimplified( - query: BrandRetrieveSimplifiedParams, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/brand/retrieve-simplified', { query, ...options }); - } - /** * Search indexed brands by name or domain * @@ -906,247 +887,6 @@ export namespace BrandRetrieveResponse { } } -export interface BrandRetrieveSimplifiedResponse { - /** - * Simplified brand information - */ - brand: BrandRetrieveSimplifiedResponse.Brand; - - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: BrandRetrieveSimplifiedResponse.CacheMetadata; - - /** - * HTTP status code of the response - */ - code: number; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Status of the response, e.g., 'ok' - */ - status: string; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: BrandRetrieveSimplifiedResponse.KeyMetadata; - - /** - * True when the timeout ended processing and only completed brand data is - * returned. - */ - partial?: boolean; -} - -export namespace BrandRetrieveSimplifiedResponse { - /** - * Simplified brand information - */ - export interface Brand { - /** - * An array of backdrop images for the brand - */ - backdrops?: Array; - - /** - * An array of brand colors - */ - colors?: Array; - - /** - * The domain name of the brand - */ - domain?: string; - - /** - * An array of logos associated with the brand - */ - logos?: Array; - - /** - * The title or name of the brand - */ - title?: string; - } - - export namespace Brand { - export interface Backdrop { - /** - * Array of colors in the backdrop image - */ - colors?: Array; - - /** - * Resolution of the backdrop image - */ - resolution?: Backdrop.Resolution; - - /** - * URL of the backdrop image - */ - url?: string; - } - - export namespace Backdrop { - export interface Color { - /** - * Color in hexadecimal format - */ - hex?: string; - - /** - * Name of the color - */ - name?: string; - } - - /** - * Resolution of the backdrop image - */ - export interface Resolution { - /** - * Aspect ratio of the image (width/height) - */ - aspect_ratio?: number; - - /** - * Height of the image in pixels - */ - height?: number; - - /** - * Width of the image in pixels - */ - width?: number; - } - } - - export interface Color { - /** - * Color in hexadecimal format - */ - hex?: string; - - /** - * Name of the color - */ - name?: string; - - /** - * Where the color was observed: 'site' colors come from the website's own theme - * signals (rendered page colors, manifest, theme-color meta), 'logo' colors from - * logo image pixels. - */ - source?: 'site' | 'logo'; - } - - export interface Logo { - /** - * Array of colors in the logo - */ - colors?: Array; - - /** - * Indicates when this logo is best used: 'light' = best for light mode, 'dark' = - * best for dark mode, 'has_opaque_background' = can be used for either as image - * has its own background - */ - mode?: 'light' | 'dark' | 'has_opaque_background'; - - /** - * Resolution of the logo image - */ - resolution?: Logo.Resolution; - - /** - * Type of the logo based on resolution (e.g., 'icon', 'logo') - */ - type?: 'icon' | 'logo'; - - /** - * CDN hosted url of the logo (ready for display) - */ - url?: string; - } - - export namespace Logo { - export interface Color { - /** - * Color in hexadecimal format - */ - hex?: string; - - /** - * Name of the color - */ - name?: string; - } - - /** - * Resolution of the logo image - */ - export interface Resolution { - /** - * Aspect ratio of the image (width/height) - */ - aspect_ratio?: number; - - /** - * Height of the image in pixels - */ - height?: number; - - /** - * Width of the image in pixels - */ - width?: number; - } - } - } - - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - export interface BrandSearchResponse { /** * Unique id of this API call, also sent in the X-Request-Id response header. Quote @@ -2210,61 +1950,6 @@ export declare namespace BrandRetrieveParams { } } -export interface BrandRetrieveSimplifiedParams { - /** - * Domain name to retrieve simplified brand data for - */ - domain: string; - - /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. - */ - maxAgeMs?: number | null; - - /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. - */ - tags?: Array; - - /** - * Optional theme preference used when selecting brand assets. - */ - theme?: 'light' | 'dark'; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: BrandRetrieveSimplifiedParams.TimeoutOpts; -} - -export namespace BrandRetrieveSimplifiedParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } -} - export interface BrandSearchParams { /** * Search term, matched against the fields selected by queryBy (e.g. 'nike', @@ -2300,10 +1985,8 @@ export interface BrandSearchParams { export declare namespace Brand { export { type BrandRetrieveResponse as BrandRetrieveResponse, - type BrandRetrieveSimplifiedResponse as BrandRetrieveSimplifiedResponse, type BrandSearchResponse as BrandSearchResponse, type BrandRetrieveParams as BrandRetrieveParams, - type BrandRetrieveSimplifiedParams as BrandRetrieveSimplifiedParams, type BrandSearchParams as BrandSearchParams, }; } diff --git a/src/resources/index.ts b/src/resources/index.ts index 3628f91f..17ccfefe 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -1,12 +1,5 @@ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. -export { - AI, - type AIExtractProductResponse, - type AIExtractProductsResponse, - type AIExtractProductParams, - type AIExtractProductsParams, -} from './ai'; export { Batch, type PageErrorCount, @@ -26,10 +19,8 @@ export { export { Brand, type BrandRetrieveResponse, - type BrandRetrieveSimplifiedResponse, type BrandSearchResponse, type BrandRetrieveParams, - type BrandRetrieveSimplifiedParams, type BrandSearchParams, } from './brand'; export { @@ -55,6 +46,8 @@ export { type MonitorListChangesResponse, type MonitorListRunsResponse, type MonitorRetrieveChangeResponse, + type MonitorRetrieveRunResponse, + type MonitorRotateWebhookSecretResponse, type MonitorRunResponse, type MonitorCreateParams, type MonitorUpdateParams, @@ -64,6 +57,7 @@ export { type MonitorListAccountRunsParams, type MonitorListChangesParams, type MonitorListRunsParams, + type MonitorRetrieveRunParams, } from './monitors'; export { News, type NewsSearchResponse, type NewsSearchParams } from './news'; export { Parse, type ParseHandleResponse, type ParseHandleParams } from './parse'; @@ -72,34 +66,20 @@ export { Utility, type UtilityPrefetchResponse, type UtilityPrefetchParams } fro export { Web, type WebAnswersResponse, - type WebExtractResponse, type WebExtractCompetitorsResponse, - type WebExtractFontsResponse, type WebExtractStyleguideResponse, + type WebMapURLsResponse, type WebScrapeResponse, type WebScreenshotResponse, type WebSearchResponse, type WebWebCrawlMdResponse, - type WebWebScrapeBytesResponse, - type WebWebScrapeHTMLResponse, - type WebWebScrapeImagesResponse, - type WebWebScrapeMdResponse, - type WebWebScrapeScreenshotResponse, - type WebWebScrapeSitemapResponse, type WebAnswersParams, - type WebExtractParams, type WebExtractCompetitorsParams, - type WebExtractFontsParams, type WebExtractStyleguideParams, + type WebMapURLsParams, type WebScrapeParams, type WebScreenshotParams, type WebSearchParams, type WebWebCrawlMdParams, - type WebWebScrapeBytesParams, - type WebWebScrapeHTMLParams, - type WebWebScrapeImagesParams, - type WebWebScrapeMdParams, - type WebWebScrapeScreenshotParams, - type WebWebScrapeSitemapParams, } from './web'; export { Webhooks, type RetryConfig } from './webhooks/webhooks'; diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index ab847006..b54dd5bb 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -210,6 +210,46 @@ export class Monitors extends APIResource { return this._client.get(path`/monitors/changes/${changeID}`, options); } + /** + * Fetches one run for a monitor, including lifecycle status, timing, credits + * charged, and any detected change. + * + * @example + * ```ts + * const response = await client.monitors.retrieveRun( + * 'run_123', + * { monitor_id: 'mon_123' }, + * ); + * ``` + */ + retrieveRun( + runID: string, + params: MonitorRetrieveRunParams, + options?: RequestOptions, + ): APIPromise { + const { monitor_id } = params; + return this._client.get(path`/monitors/${monitor_id}/runs/${runID}`, options); + } + + /** + * Generates a new signing secret for the monitor's webhook and returns the updated + * monitor (including the new `webhook.secret`). The previous secret stops signing + * deliveries immediately, so update your endpoint before rotating. + * + * @example + * ```ts + * const response = await client.monitors.rotateWebhookSecret( + * 'mon_123', + * ); + * ``` + */ + rotateWebhookSecret( + monitorID: string, + options?: RequestOptions, + ): APIPromise { + return this._client.post(path`/monitors/${monitorID}/webhook/rotate-secret`, options); + } + /** * Triggers an immediate run of the monitor outside its normal schedule. The run is * queued and processed asynchronously. @@ -2200,6 +2240,453 @@ export namespace MonitorRetrieveChangeResponse { } } +export interface MonitorRetrieveRunResponse { + id: string; + + /** + * True when this run established the monitor's initial baseline; baseline runs + * perform no change detection. + */ + baseline_created: boolean; + + change_detected: boolean; + + change_detection_type: 'exact' | 'semantic'; + + /** + * Credits charged for this run (0 for skipped/failed runs). + */ + credits_charged: number; + + monitor_id: string; + + /** + * The first run after monitor creation is a baseline run. + */ + run_type: 'baseline' | 'scheduled'; + + /** + * Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` + * (insufficient credits, monitor paused, or superseded by a concurrent run). + */ + status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; + + target_type: 'page' | 'sitemap' | 'extract'; + + change_id?: string | null; + + completed_at?: string | null; + + error?: MonitorRetrieveRunResponse.Error | null; + + /** + * Why a skipped run never executed; null unless status is `skipped`. + */ + skip_reason?: 'insufficient_credits' | 'monitor_paused' | 'superseded' | null; + + started_at?: string | null; + + /** + * All webhook deliveries attempted by this run — one per subscribed event that + * fired. Omitted when no webhook was attempted, including runs created before + * event selection was added. + */ + webhook_deliveries?: Array; + + /** + * @deprecated Deprecated: use `webhook_deliveries`, which records every attempt + * now that a run can deliver multiple events. Omitted when no webhook was + * attempted, including historical runs created before delivery tracking was added. + */ + webhook_delivery?: WebhookDelivery; + + /** + * Webhook delivery IDs for this run. + */ + webhook_delivery_ids?: Array; +} + +export namespace MonitorRetrieveRunResponse { + export interface Error { + code: string; + + message: string; + } +} + +/** + * A web monitor. `mode` is the constant `web`; behavior is described by `target` + * (page/sitemap/extract) and `change_detection` (exact/semantic). + */ +export interface MonitorRotateWebhookSecretResponse { + id: string; + + /** + * Discriminated union describing how changes are detected. + */ + change_detection: + | MonitorRotateWebhookSecretResponse.MonitorsExactChangeDetection + | MonitorRotateWebhookSecretResponse.MonitorsSemanticChangeDetection; + + created_at: string; + + /** + * Top-level monitor category. Always `web` today; the concrete behavior is + * described by `target` and `change_detection`. + */ + mode: 'web'; + + name: string; + + /** + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + schedule: MonitorRotateWebhookSecretResponse.Schedule; + + /** + * Monitor lifecycle status. `failed` means the most recent run failed (see the + * monitor's `last_error`); failed monitors keep running on schedule and flip back + * to `active` on the next successful run. Monitors are auto-`paused` after + * repeated consecutive failures or insufficient-credit skips; resume by PATCHing + * status to `active`. + */ + status: 'active' | 'paused' | 'failed'; + + /** + * Discriminated union describing what the monitor watches. + */ + target: + | MonitorRotateWebhookSecretResponse.MonitorsPageTarget + | MonitorRotateWebhookSecretResponse.MonitorsSitemapTarget + | MonitorRotateWebhookSecretResponse.MonitorsExtractTarget; + + updated_at: string; + + /** + * Current baseline: the last observed value the monitor compares new snapshots + * against. Its shape follows `target.type` (page/sitemap/extract). Only populated + * on GET /monitors/{monitor_id}; null until the first baseline run completes (and + * after a target or change_detection update, which resets the baseline). + */ + baseline?: + | MonitorRotateWebhookSecretResponse.MonitorsPageBaseline + | MonitorRotateWebhookSecretResponse.MonitorsSitemapBaseline + | MonitorRotateWebhookSecretResponse.MonitorsExtractBaseline + | null; + + last_change_at?: string | null; + + /** + * Error from the most recent failed run; null when the last run succeeded. + */ + last_error?: MonitorRotateWebhookSecretResponse.LastError | null; + + last_run_at?: string | null; + + /** + * When the next scheduled run is due. + */ + next_run_at?: string | null; + + /** + * User-defined tags for grouping and filtering monitors and their changes. + * Duplicates are removed. + */ + tags?: Array; + + webhook?: MonitorRotateWebhookSecretResponse.Webhook | null; + + /** + * Present while webhook deliveries are failing consecutively; null when deliveries + * are healthy or no webhook is configured. Cleared on the next successful delivery + * and when the webhook URL changes. + */ + webhook_failure?: MonitorRotateWebhookSecretResponse.WebhookFailure | null; +} + +export namespace MonitorRotateWebhookSecretResponse { + /** + * Detect exact changes. For page targets, this means visible text diffs. For + * sitemap targets, this means URL additions and removals. + */ + export interface MonitorsExactChangeDetection { + type: 'exact'; + } + + /** + * Detect meaning-level changes to page content, ignoring cosmetic or + * instruction-irrelevant differences. Which changes are meaningful is judged + * against the page or extract target's `instructions` (and an extract target's + * `schema`, when provided). + */ + export interface MonitorsSemanticChangeDetection { + type: 'semantic'; + + confidence_threshold?: number; + } + + /** + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + export interface Schedule { + /** + * Number of units between runs. The resulting interval (frequency × unit) must be + * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; + * maximum 365 when unit is days). + */ + frequency: number; + + type: 'interval'; + + unit: 'minutes' | 'hours' | 'days'; + } + + /** + * Watch a single web page. Exact detection reports visible-text diffs; semantic + * detection judges confirmed stable diffs against `instructions`. + */ + export interface MonitorsPageTarget { + type: 'page'; + + url: string; + + /** + * CSS selectors for HTML regions to remove before text extraction. Applied after + * include_selectors; exclusion takes precedence when an element matches both. Omit + * or pass an empty array to apply no explicit exclusions. Changing these selectors + * creates a new baseline. + */ + exclude_selectors?: Array; + + /** + * CSS selectors defining the HTML regions to monitor. Matching subtrees are + * combined in document order before text extraction, instead of automatic + * main-content selection. Omit or pass an empty array to use automatic + * main-content extraction. If the filtered page has no usable text, the run fails + * without replacing the baseline. Changing these selectors creates a new baseline. + */ + include_selectors?: Array; + + /** + * Plain-language goal describing which page changes matter. When provided without + * change_detection, semantic detection is inferred. + */ + instructions?: string; + + /** + * Normalize whitespace before comparing or analyzing text. + */ + normalize_whitespace?: boolean; + } + + /** + * Watch a sitemap for URL additions and removals. Crawled URLs are normalized + * (lowercased host, no trailing slash/fragment) and scoped to the monitored site + * and its subdomains before comparison. On a detected difference the sitemap is + * re-fetched within the same run and only URLs both observations agree on are + * reported, suppressing transient crawl flaps. + */ + export interface MonitorsSitemapTarget { + type: 'sitemap'; + + /** + * Sitemap URL to monitor. + */ + url: string; + + /** + * URL path patterns to exclude (max 50). + */ + exclude?: Array; + + /** + * URL path patterns to include (max 50). + */ + include?: Array; + + /** + * Maximum number of sitemap URLs to track (capped at 10,000). + */ + max_urls?: number; + } + + /** + * Watch the monitor-relevant pages of a site for meaningful changes. A crawl + * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to + * track; each run re-checks exactly those pages, and confirmed content changes are + * judged for relevance against the monitor's `instructions` (and `schema`, when + * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + */ + export interface MonitorsExtractTarget { + /** + * Natural-language instructions guiding which pages and facts to track and which + * changes to report. + */ + instructions: string; + + type: 'extract'; + + /** + * Root URL to extract structured data from. + */ + url: string; + + follow_subdomains?: boolean; + + /** + * Optional maximum link depth from the starting URL (0 = only the starting page). + */ + max_depth?: number; + + /** + * Maximum number of pages to track. + */ + max_pages?: number; + + /** + * JSON Schema describing the data you care about. It is used three ways: it guides + * which pages are selected for tracking, it gives the change judge extra context + * on which changes matter (alongside `instructions`), and it defines the shape of + * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most + * about once a day). It is not a response format for changes: change events and + * webhook payloads always contain diffs, summaries, and evidence excerpts — never + * data in this schema's shape. If omitted, a default summary + key-points schema + * is used. + */ + schema?: { [key: string]: unknown }; + } + + /** + * Current baseline of a `page` monitor: the visible page text as last observed. + */ + export interface MonitorsPageBaseline { + /** + * When this baseline was last captured or replaced. + */ + captured_at: string; + + /** + * The page's visible text as last observed. + */ + text: string; + } + + /** + * Current baseline of a `sitemap` monitor: the normalized URL set as last + * observed. + */ + export interface MonitorsSitemapBaseline { + /** + * When this baseline was last captured or replaced. + */ + captured_at: string; + + /** + * Number of URLs in the baseline. + */ + url_count: number; + + /** + * The sitemap URLs as last observed (sorted, normalized). + */ + urls: Array; + } + + /** + * Current baseline of an `extract` monitor: the pages it tracks and the structured + * data as last extracted. + */ + export interface MonitorsExtractBaseline { + /** + * When this baseline was last captured or replaced. + */ + captured_at: string; + + /** + * The extracted structured data, matching the monitor's extraction schema (same + * shape as the /web/extract endpoint's `data`). Refreshed when the monitor + * re-discovers its page set (at most about once a day); `null` when no extraction + * has been captured yet. + */ + data: unknown; + + /** + * The page URLs the monitor tracks and analyzes for changes. + */ + urls_analyzed: Array; + } + + /** + * Error from the most recent failed run; null when the last run succeeded. + */ + export interface LastError { + code: string; + + message: string; + } + + export interface Webhook { + /** + * Webhook URL events are delivered to. Slack incoming webhook URLs are + * automatically formatted as Slack messages. + */ + url: string; + + /** + * Events delivered to this endpoint. `change.detected` fires only when a run + * detects a change; `run.completed` fires on every completed run — including runs + * that detected no change — and embeds the change when one was detected. Defaults + * to `["change.detected"]` when omitted. + */ + events?: Array<'change.detected' | 'run.completed'>; + + /** + * Webhook retry settings. Use {} for the default schedule. + */ + retry?: WebhooksAPI.RetryConfig; + + /** + * Signing secret used to verify webhook authenticity. Omitted unless the API key + * has monitors:write permission or full access. Each delivery includes an + * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over + * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time + * compare and reject stale timestamps to prevent replay. Generated by the API; + * cannot be set by clients. + */ + secret?: string; + } + + /** + * Present while webhook deliveries are failing consecutively; null when deliveries + * are healthy or no webhook is configured. Cleared on the next successful delivery + * and when the webhook URL changes. + */ + export interface WebhookFailure { + /** + * Number of consecutive delivery attempts that did not succeed. + */ + consecutive_failures: number; + + last_failed_at: string; + + /** + * Human-readable description of the most recent failure. + */ + last_message: string; + + /** + * Outcome of the most recent failed delivery. rejected means a non-2xx response; + * failed means no HTTP response was received; skipped_unsafe_url means the URL + * failed the public-endpoint safety check. + */ + last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; + } +} + export interface MonitorRunResponse { monitor_id: string; @@ -2815,6 +3302,10 @@ export interface MonitorListRunsParams { status?: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; } +export interface MonitorRetrieveRunParams { + monitor_id: string; +} + export declare namespace Monitors { export { type WebhookDelivery as WebhookDelivery, @@ -2830,6 +3321,8 @@ export declare namespace Monitors { type MonitorListChangesResponse as MonitorListChangesResponse, type MonitorListRunsResponse as MonitorListRunsResponse, type MonitorRetrieveChangeResponse as MonitorRetrieveChangeResponse, + type MonitorRetrieveRunResponse as MonitorRetrieveRunResponse, + type MonitorRotateWebhookSecretResponse as MonitorRotateWebhookSecretResponse, type MonitorRunResponse as MonitorRunResponse, type MonitorCreateParams as MonitorCreateParams, type MonitorUpdateParams as MonitorUpdateParams, @@ -2839,5 +3332,6 @@ export declare namespace Monitors { type MonitorListAccountRunsParams as MonitorListAccountRunsParams, type MonitorListChangesParams as MonitorListChangesParams, type MonitorListRunsParams as MonitorListRunsParams, + type MonitorRetrieveRunParams as MonitorRetrieveRunParams, }; } diff --git a/src/resources/web.ts b/src/resources/web.ts index 35b85abf..227beb57 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -28,27 +28,6 @@ export class Web extends APIResource { return this._client.post('/web/answers', { body, ...options }); } - /** - * Crawl a website, use the provided JSON Schema and instructions to prioritize - * relevant internal links, and extract structured data from the selected pages. - * - * @example - * ```ts - * const response = await client.web.extract({ - * schema: { - * type: 'bar', - * properties: 'bar', - * required: 'bar', - * additionalProperties: 'bar', - * }, - * url: 'https://example.com', - * }); - * ``` - */ - extract(body: WebExtractParams, options?: RequestOptions): APIPromise { - return this._client.post('/web/extract', { body, ...options }); - } - /** * Analyze a company's landing page and web search evidence to return direct * competitors for the same product or market. @@ -68,35 +47,40 @@ export class Web extends APIResource { } /** - * Scrape font information from a website including font families, usage - * statistics, fallbacks, and element/word counts. + * Extract a comprehensive design system from a website including colors, + * typography, spacing, shadows, and UI components. * * @example * ```ts - * const response = await client.web.extractFonts(); + * const response = await client.web.extractStyleguide(); * ``` */ - extractFonts( - query: WebExtractFontsParams | null | undefined = {}, + extractStyleguide( + query: WebExtractStyleguideParams | null | undefined = {}, options?: RequestOptions, - ): APIPromise { - return this._client.get('/web/fonts', { query, ...options }); + ): APIPromise { + return this._client.get('/web/styleguide', { query, ...options }); } /** - * Extract a comprehensive design system from a website including colors, - * typography, spacing, shadows, and UI components. + * Discovers URLs using the same sitemap crawl, filters, and limits as + * /web/scrape/sitemap. Each URL includes its available title, description, + * keywords, and language. URLs without stored enrichment are returned immediately + * with only the URL and queued for background HTML scraping, so later requests can + * include their metadata. Responses are never cached as a whole; every request + * reads the current per-URL enrichment. Zero data retention and credential-bearing + * discovery requests return URLs without reading or storing shared enrichment or + * queuing background scrapes. Costs 1 credit, or 2 credits with search. * * @example * ```ts - * const response = await client.web.extractStyleguide(); + * const response = await client.web.mapUrls({ + * domain: 'xxx', + * }); * ``` */ - extractStyleguide( - query: WebExtractStyleguideParams | null | undefined = {}, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/web/styleguide', { query, ...options }); + mapUrls(query: WebMapURLsParams, options?: RequestOptions): APIPromise { + return this._client.get('/web/urls', { query, ...options }); } /** @@ -162,172 +146,6 @@ export class Web extends APIResource { webCrawlMd(body: WebWebCrawlMdParams, options?: RequestOptions): APIPromise { return this._client.post('/web/crawl', { body, ...options }); } - - /** - * Downloads a resource and returns its bytes as base64. Without waitForMs, returns - * the original HTTP response without image conversion, text extraction, or - * character-encoding changes. HTTP compression is decoded before base64 encoding. - * Supply waitForMs to render HTML with JavaScript in the browser and return the - * resulting HTML as UTF-8 bytes after the wait. Non-HTML resources, including - * images and PDFs, keep their original bytes and do not incur a browser wait. - * Follows public redirects and retries failed downloads through ISP and - * residential proxies, with a direct fallback. When country is specified, only a - * residential proxy in that country is used. Supply headers such as Referer for - * images that require a referring page. Cached results are reused according to - * maxAgeMs (default: 1 day; maximum: 30 days). Set maxAgeMs=0 to fetch fresh and - * refresh the cache. Cache identity includes the exact URL, country, waitForMs, - * and normalized outbound headers. Credential-bearing headers and zero data - * retention bypass cache reads and writes. cache_metadata reports hit, miss, or - * zdr and the cached result age in milliseconds. Maximum decoded resource size: 20 - * MiB (20971520 bytes), before base64 encoding. Successful requests cost 1 credit; - * errors are not billed. - * - * @example - * ```ts - * const response = await client.web.webScrapeBytes({ - * url: 'https://example.com', - * }); - * ``` - */ - webScrapeBytes( - query: WebWebScrapeBytesParams, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/web/scrape/bytes', { query, ...options }); - } - - /** - * Scrapes the given URL and returns the HTML content of the page. Optional - * extractRules return deterministic structured data in extracted using CSS - * selectors, attributes, lists, and nested rules, without an LLM or additional - * credits. Rules run on the returned HTML after selector and main-content - * filtering. Send extractRules as a JSON-encoded query parameter. The base request - * costs 1 credit; requests with browser actions cost 2 credits. A request that - * hits its timeoutOpts.milliseconds deadline fails with 408 and is not billed, - * unless timeoutOpts.behavior=return-partial is set — then the page as rendered so - * far is returned with `finalDOMState: "still-loading"` and billed at the base - * cost of 1 credit. - * - * @example - * ```ts - * const response = await client.web.webScrapeHTML({ - * url: 'https://example.com', - * }); - * ``` - */ - webScrapeHTML( - query: WebWebScrapeHTMLParams, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/web/scrape/html', { query, ...options }); - } - - /** - * Extract image assets from a web page, including standard URLs, inline SVGs, data - * URIs, responsive image sources, metadata, CSS backgrounds, video posters, and - * embeds. The base request costs 1 credit, or 2 credits with browser actions. When - * enrichment is enabled, the entire call costs 5 credits, including requests that - * also use actions. - * - * @example - * ```ts - * const response = await client.web.webScrapeImages({ - * url: 'https://example.com', - * }); - * ``` - */ - webScrapeImages( - query: WebWebScrapeImagesParams, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/web/scrape/images', { query, ...options }); - } - - /** - * Scrapes the given URL into LLM usable Markdown. Inspect key_metadata on JSON - * responses from a recognized API key; use error_code to distinguish stable - * failure categories. - * - * ### YouTube - * - * YouTube URLs return the video or channel itself rather than the surrounding - * player and navigation chrome. A URL addressing a single video (`/watch`, - * `youtu.be`, `/shorts`, `/embed`, `/live`) returns its title, channel, duration, - * view count, keywords, full description, and the transcript when the video has - * captions that can be retrieved; videos without captions return everything except - * the transcript. A channel URL (`/channel/UC…`, `/@handle`, `/c/…`, `/user/…`) - * returns its name, handle, subscriber count, video count, and full description. - * When `includeImages=true`, video responses also include the thumbnail and - * channel responses include the avatar. Costs the same as any other scrape. - * - * ### Billing & errors - * - * | HTTP status | Billed? | Meaning | - * | ----------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - * | 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing. A partial result (`finalDOMState: "still-loading"`, only with timeoutOpts.behavior=return-partial) is billed at the base 1 credit with no OCR or actions surcharge | - * | 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds | - * | 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code | - * | 404 | Yes — 1 credit, or 2 credits with actions | Target page returned or fingerprinted as not found | - * | 408 | No | Request timed out. With timeoutOpts.behavior=return-partial this only happens when nothing usable had rendered by the deadline | - * | 413 | No | Target content exceeds the maximum supported size (20 MB) | - * | 415 | No | Unsupported content type | - * | 429 | No | Per-minute rate limit exceeded; honor Retry-After | - * | 500 | No | Internal error | - * - * @example - * ```ts - * const response = await client.web.webScrapeMd({ - * url: 'https://example.com', - * }); - * ``` - */ - webScrapeMd(query: WebWebScrapeMdParams, options?: RequestOptions): APIPromise { - return this._client.get('/web/scrape/markdown', { query, ...options }); - } - - /** - * Capture the given HTTP or HTTPS URL with configurable viewport, full-page - * capture, wait time, popup handling, theme, scroll offset, cache age, country, - * and request timeout. Defaults to a 1920x1080 viewport, a 3-second wait, and a - * cache age of 1 day. With timeoutOpts.behavior=return-partial, a screenshot of - * the page rendered so far may be returned; inspect finalDOMState to identify an - * incomplete render. Successful requests cost 1 credit; errors are not billed. - * - * @example - * ```ts - * const response = await client.web.webScrapeScreenshot({ - * url: 'https://example.com', - * }); - * ``` - */ - webScrapeScreenshot( - query: WebWebScrapeScreenshotParams, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/web/scrape/screenshot', { query, ...options }); - } - - /** - * Crawl an entire website's sitemap and return all discovered page URLs. Set - * `includeSubdomains=true` to also discover public pages and sitemaps on child - * hosts such as `docs.example.com` or `brand.example.com`. Pass `search` to have - * the discovered URLs filtered down to the pages about a phrase (for example - * `pricing and plans` or `api authentication docs`), most relevant first — a - * searched crawl scans the whole sitemap and costs 2 credits instead of 1. - * - * @example - * ```ts - * const response = await client.web.webScrapeSitemap({ - * domain: 'xxx', - * }); - * ``` - */ - webScrapeSitemap( - query: WebWebScrapeSitemapParams, - options?: RequestOptions, - ): APIPromise { - return this._client.get('/web/scrape/sitemap', { query, ...options }); - } } export interface WebAnswersResponse { @@ -371,137 +189,6 @@ export namespace WebAnswersResponse { } } -export interface WebExtractResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: WebExtractResponse.CacheMetadata; - - /** - * Extracted data matching the request schema - */ - data: { [key: string]: unknown }; - - metadata: WebExtractResponse.Metadata; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Status of the response, e.g., 'ok' - */ - status: string; - - /** - * The starting URL that was analyzed - */ - url: string; - - /** - * List of URLs whose Markdown was used for extraction - */ - urls_analyzed: Array; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: WebExtractResponse.KeyMetadata; - - /** - * True when the timeout ended processing and this response contains only usable - * results completed so far. Unfinished results are omitted. - */ - partial?: boolean; -} - -export namespace WebExtractResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - export interface Metadata { - maxCrawlDepth: number; - - /** - * Number of crawled pages excluded because they were anti-bot challenges, error - * pages, or parked-domain placeholders. - */ - numBlocked: number; - - numFailed: number; - - numSkipped: number; - - numSucceeded: number; - - numUrls: number; - - /** - * One verified outcome per requested browser action, in request order. - */ - actionsApplied?: Array; - } - - export namespace Metadata { - export interface ActionsApplied { - instruction: string; - - /** - * Applied means the requested page state was visibly verified. Failed means it was - * not verified. Skipped means it was not attempted. - */ - status: 'applied' | 'failed' | 'skipped'; - - /** - * Visible page evidence used to verify an applied action. - */ - completionEvidence?: string; - - durationMs?: number; - - error?: string; - - method?: string; - - targetDescription?: string; - } - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - export interface WebExtractCompetitorsResponse { /** * Direct competitors ordered by relevance and confidence. @@ -615,28 +302,13 @@ export namespace WebExtractCompetitorsResponse { } } -export interface WebExtractFontsResponse { +export interface WebExtractStyleguideResponse { /** * Cache outcome for this response. Composite responses are hits only when every * cache-controlled fetch contributing to the output was a hit; age_ms is the * oldest contributing hit. */ - cache_metadata: WebExtractFontsResponse.CacheMetadata; - - /** - * HTTP status code, e.g., 200 - */ - code: number; - - /** - * The normalized domain that was processed - */ - domain: string; - - /** - * Array of font usage information - */ - fonts: Array; + cache_metadata: WebExtractStyleguideResponse.CacheMetadata; /** * Unique id of this API call, also sent in the X-Request-Id response header. Quote @@ -645,9 +317,14 @@ export interface WebExtractFontsResponse { request_id: string; /** - * Status of the response, e.g., 'ok' + * HTTP status code */ - status: string; + code?: number; + + /** + * The normalized domain that was processed + */ + domain?: string; /** * How complete the returned content is. `loaded` means the page finished the waits @@ -659,19 +336,22 @@ export interface WebExtractFontsResponse { finalDOMState?: 'loaded' | 'still-loading'; /** - * Font assets keyed by family name as it appears in the fonts array (non-generic - * names only). Clients match entries in fonts to pick a file URL from files. - * Omitted when no families resolve to Google or custom @font-face URLs. + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: WebExtractStyleguideResponse.KeyMetadata; + + /** + * Status of the response, e.g., 'ok' */ - fontLinks?: { [key: string]: WebExtractFontsResponse.FontLinks }; + status?: string; /** - * Credit usage, included whenever a valid API key is provided. + * Comprehensive styleguide data extracted from the website */ - key_metadata?: WebExtractFontsResponse.KeyMetadata; + styleguide?: WebExtractStyleguideResponse.Styleguide; } -export namespace WebExtractFontsResponse { +export namespace WebExtractStyleguideResponse { /** * Cache outcome for this response. Composite responses are hits only when every * cache-controlled fetch contributing to the output was a hit; age_ms is the @@ -690,190 +370,46 @@ export namespace WebExtractFontsResponse { status: 'hit' | 'miss' | 'zdr'; } - export interface Font { + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { /** - * Array of fallback font families + * Credits used by this request. */ - fallbacks: Array; + credits_consumed: number; /** - * Font family name + * Credits remaining for your organization. */ - font: string; + credits_remaining: number; + } + /** + * Comprehensive styleguide data extracted from the website + */ + export interface Styleguide { /** - * Number of elements using this font + * Primary colors used on the website */ - num_elements: number; + colors: Styleguide.Colors; /** - * Number of words using this font + * UI component styles */ - num_words: number; + components: Styleguide.Components; /** - * Percentage of elements using this font + * Spacing system used on the website */ - percent_elements: number; + elementSpacing: Styleguide.ElementSpacing; /** - * Percentage of words using this font + * Font assets keyed by family name as it appears in fontFamily/fontFallbacks + * (non-generic names only). Clients match typography.fontFamily / fontWeight or + * button styles to pick a file URL from files. */ - percent_words: number; - - /** - * Array of CSS selectors or element types where this font is used - */ - uses: Array; - } - - export interface FontLinks { - /** - * Upright font files keyed by weight string (e.g. "400" for regular, "500", - * "700"). Values are absolute URLs. - */ - files: { [key: string]: string }; - - type: 'google' | 'custom'; - - /** - * Google Fonts category when type is google (e.g. sans-serif, serif, monospace, - * display, handwriting). Omitted for custom fonts when unknown. - */ - category?: string; - - /** - * Present when type is custom: human-readable name derived from the fontLinks key - * (strip build/hash suffixes, split camelCase / PascalCase, normalize separators). - * Google entries omit this. - */ - displayName?: string; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - -export interface WebExtractStyleguideResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: WebExtractStyleguideResponse.CacheMetadata; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * HTTP status code - */ - code?: number; - - /** - * The normalized domain that was processed - */ - domain?: string; - - /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. - */ - finalDOMState?: 'loaded' | 'still-loading'; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: WebExtractStyleguideResponse.KeyMetadata; - - /** - * Status of the response, e.g., 'ok' - */ - status?: string; - - /** - * Comprehensive styleguide data extracted from the website - */ - styleguide?: WebExtractStyleguideResponse.Styleguide; -} - -export namespace WebExtractStyleguideResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } - - /** - * Comprehensive styleguide data extracted from the website - */ - export interface Styleguide { - /** - * Primary colors used on the website - */ - colors: Styleguide.Colors; - - /** - * UI component styles - */ - components: Styleguide.Components; - - /** - * Spacing system used on the website - */ - elementSpacing: Styleguide.ElementSpacing; - - /** - * Font assets keyed by family name as it appears in fontFamily/fontFallbacks - * (non-generic names only). Clients match typography.fontFamily / fontWeight or - * button styles to pick a file URL from files. - */ - fontLinks: { [key: string]: Styleguide.FontLinks }; + fontLinks: { [key: string]: Styleguide.FontLinks }; /** * The primary color mode of the website design @@ -1339,6 +875,56 @@ export namespace WebExtractStyleguideResponse { } } +export interface WebMapURLsResponse { + domain: string; + + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + + success: true; + + urls: Array; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: WebMapURLsResponse.KeyMetadata; + + partial?: boolean; +} + +export namespace WebMapURLsResponse { + export interface URL { + url: string; + + description?: string; + + keywords?: Array; + + language?: string; + + title?: string; + } + + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + export interface WebScrapeResponse { /** * Original HTTP response body. Waiting, actions, and content filters never change @@ -1394,6 +980,12 @@ export interface WebScrapeResponse { */ url: string; + /** + * Present when return-partial captures a page that is still loading or returns + * images before image processing finishes. Partial responses are not cached. + */ + isPartial?: true; + /** * Credit usage, included whenever a valid API key is provided. */ @@ -2157,3705 +1749,650 @@ export namespace WebWebCrawlMdResponse { } } -export interface WebWebScrapeBytesResponse { +export interface WebAnswersParams { /** - * Base64-encoded resource bytes, without a data URI prefix. Decode this field to - * recover the downloaded file. + * What to research and answer, in plain language. Naming a domain in the task (for + * example "pricing on context.dev") makes the agent read that site before it + * searches. */ - bytes: string; + task: string; /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * An example object with placeholder values (for example {"pricing_page_url": "", + * "plans": [{"name": "", "price": 0}]}). Object keys and value types are + * preserved; unknown values may be null. Empty arrays accept any JSON items. + * Defaults to {"result": ""}. Maximum 8 levels, 500 values, and 16000 characters. */ - cache_metadata: WebWebScrapeBytesResponse.CacheMetadata; + json_format?: { [key: string]: unknown }; /** - * Number of decoded resource bytes, before base64 encoding. + * Research level: fast uses a smaller model and research budget for 10 credits; + * ultra uses deeper reasoning and research for 100 credits. Defaults to ultra. + * Only successful requests consume credits. */ - contentLength: number; + mode?: 'fast' | 'ultra'; /** - * The Content-Type returned by the origin, including any charset. Defaults to - * application/octet-stream when absent. + * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. */ - contentType: string; - - encoding: 'base64'; + tags?: Array; /** - * The resource URL after redirects. + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - finalUrl: string; + timeoutOpts?: WebAnswersParams.TimeoutOpts; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ - request_id: string; + zdr?: 'enabled' | 'disabled'; +} +export namespace WebAnswersParams { /** - * HTTP status returned by the origin. + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - statusCode: number; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; - success: true; + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. + */ + behavior?: 'fail' | 'return-partial'; + } +} +export interface WebExtractCompetitorsParams { /** - * The requested resource URL. + * Company domain to analyze, such as `stripe.com`. Full http(s) URLs are accepted + * and normalized to their domain. */ - url: string; + domain: string; /** - * Credit usage, included whenever a valid API key is provided. + * Exact number of direct competitors to return. Defaults to 5. */ - key_metadata?: WebWebScrapeBytesResponse.KeyMetadata; -} + numCompetitors?: number; -export namespace WebWebScrapeBytesResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; + tags?: Array; - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: WebExtractCompetitorsParams.TimeoutOpts; /** - * Credit usage, included whenever a valid API key is provided. + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ - export interface KeyMetadata { + zdr?: 'enabled' | 'disabled'; +} + +export namespace WebExtractCompetitorsParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { /** - * Credits used by this request. + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). */ - credits_consumed: number; + milliseconds: number; /** - * Credits remaining for your organization. + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. */ - credits_remaining: number; + behavior?: 'fail' | 'return-partial'; } } -export interface WebWebScrapeHTMLResponse { +export interface WebExtractStyleguideParams { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Optional browser color scheme to emulate for websites that respond to + * prefers-color-scheme. This value is part of the styleguide cache key. */ - cache_metadata: WebWebScrapeHTMLResponse.CacheMetadata; + colorScheme?: 'light' | 'dark'; /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. + * A specific URL to fetch the styleguide from directly, bypassing domain + * resolution (e.g., 'https://example.com/design-system'). When provided, the + * styleguide is extracted from this exact URL. You must provide either 'domain' or + * 'directUrl', but not both. */ - finalDOMState: 'loaded' | 'still-loading'; + directUrl?: string; /** - * The scraped content of the page. For normal pages this is the raw HTML. When the - * page is a sitemap or feed served behind an XSL stylesheet (which browsers render - * into HTML), this is the underlying XML instead — see the `type` field. + * Domain name to extract styleguide from (e.g., 'example.com', 'google.com'). The + * domain will be automatically normalized and validated. You must provide either + * 'domain' or 'directUrl', but not both. */ - html: string; + domain?: string; /** - * Metadata extracted from the scraped page HTML. + * Maximum age in milliseconds for cached brand data before the API performs a hard + * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard + * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) + * are clamped to 1 year. */ - metadata: WebWebScrapeHTMLResponse.Metadata; + maxAgeMs?: number | null; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ - request_id: string; + tags?: Array; /** - * Indicates success + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - success: true; + timeoutOpts?: WebExtractStyleguideParams.TimeoutOpts; /** - * Detected content type of the returned `html` field. Sitemaps and feeds are - * surfaced as `xml`; ordinary pages are `html`. Excel workbooks are surfaced as - * `xlsx`/`xls` with the extracted sheets as HTML tables; PowerPoint presentations - * are surfaced as `pptx`/`ppt` with the extracted slides as HTML. + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. */ - type: - | 'html' - | 'xml' - | 'json' - | 'text' - | 'csv' - | 'markdown' - | 'svg' - | 'pdf' - | 'docx' - | 'doc' - | 'xlsx' - | 'xls' - | 'pptx' - | 'ppt'; + zdr?: 'enabled' | 'disabled'; +} +export namespace WebExtractStyleguideParams { /** - * The URL that was scraped + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - url: string; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 5000. + */ + behavior?: 'fail' | 'return-partial'; + } +} +export interface WebMapURLsParams { /** - * One verified outcome per requested browser action, in request order. + * Domain to build a sitemap for */ - actionsApplied?: Array; + domain: string; /** - * True when an action was applied but the returned content could not be refreshed - * afterward. + * Optional outbound HTTP headers forwarded only to the target URL, sent as + * deep-object query params such as headers[X-Custom]=value. When provided, caching + * is bypassed: the result is neither read from nor written to cache. */ - actionsHtmlStale?: boolean; + headers?: { [key: string]: string }; /** - * Present only when extractRules is supplied. Keys match the requested fields. - * Values are normalized text, raw attribute strings, outer HTML, nested objects, - * or lists. Missing items are null; lists with no matches are empty. Rules run on - * the returned HTML after filtering. + * When true, discover and include public pages and sitemaps on subdomains of the + * requested domain. Defaults to false. */ - extracted?: { [key: string]: string | unknown | Array | null }; + includeSubdomains?: boolean; /** - * Credit usage, included whenever a valid API key is provided. + * Maximum number of links to return from the sitemap crawl. Defaults to 10,000. + * Minimum is 1, maximum is 100,000. */ - key_metadata?: WebWebScrapeHTMLResponse.KeyMetadata; -} + maxLinks?: number; -export namespace WebWebScrapeHTMLResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Optional search phrase. When provided, the crawled sitemap is filtered to the + * pages whose URLs are about that phrase, most relevant first, and the request + * costs 2 credits instead of 1. */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; + search?: string; - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } + /** + * Optional explicit sitemap URL. When provided, exactly this sitemap is crawled + * instead of discovering the domain's sitemaps. + */ + sitemapUrl?: string; /** - * Metadata extracted from the scraped page HTML. + * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 + * characters. */ - export interface Metadata { - /** - * Final URL scraped after redirects or scraper fallback, when known. Falls back to - * sourceUrl when unavailable. - */ - finalUrl: string; + tags?: Array; - /** - * Original URL requested by the caller. - */ - sourceUrl: string; + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + timeoutOpts?: WebMapURLsParams.TimeoutOpts; - /** - * Additional non-social meta tags not promoted to top-level metadata fields. - */ - additionalMeta?: { [key: string]: string | Array }; + /** + * Optional RE2-compatible regex pattern. Only URLs matching this pattern are + * returned and counted against maxLinks. + */ + urlRegex?: string; - /** - * Resolved alternate links from link rel=alternate tags. - */ - alternates?: Array; + /** + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Asset uploads are skipped, so hosted image URLs are + * omitted. Requires zero data retention to be enabled for your organization + * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. + * Successful ZDR responses include X-Context-ZDR: true. + */ + zdr?: 'enabled' | 'disabled'; +} +export namespace WebMapURLsParams { + /** + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. + */ + export interface TimeoutOpts { /** - * Author metadata, when present. + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). */ - author?: string; + milliseconds: number; /** - * Resolved canonical URL, when present. + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. */ - canonicalUrl?: string; + behavior?: 'fail' | 'return-partial'; + } +} - /** - * Best description extracted from standard, Open Graph, or Twitter metadata. - */ - description?: string; +export interface WebScrapeParams { + /** + * Outputs to return. Enable at least one; omitted formats are false. + */ + formats: WebScrapeParams.Formats; - /** - * Resolved favicon URL, when present. - */ - favicon?: string; + /** + * The URL to scrape. + */ + url: string; - /** - * Page headings (h1–h6) in document order, extracted from the unfiltered document. - * Capped at the first 500 headings. Omitted when the page has none. - */ - headings?: Array; + /** + * Image options. Requires formats.images: true. + */ + imageParams?: WebScrapeParams.ImageParams; - /** - * Primary resolved preview image from Open Graph, Twitter, or image metadata. - */ - image?: string; + /** + * Markdown options. Requires formats.markdown: true. + */ + markdownParams?: WebScrapeParams.MarkdownParams; - /** - * JSON-LD structured data blocks parsed from the page. - */ - jsonLd?: Array<{ [key: string]: unknown }>; + /** + * Maximum age of each cached output. Defaults to 1 day; 0 fetches fresh and + * updates the requested outputs. Compatible outputs are shared with the individual + * scrape endpoints. Image results with hosted files refresh after 23 hours; other + * outputs retain their own freshness. + */ + maxAgeMs?: number; - /** - * Keywords extracted from the page's keywords meta tag. - */ - keywords?: Array; - - /** - * Language extracted from html lang or language meta tags. - */ - language?: string; - - /** - * Modified timestamp/date from page metadata, when present. - */ - modifiedTime?: string; - - /** - * Open Graph metadata with the og: prefix removed and keys camel-cased. - */ - openGraph?: { [key: string]: string | Array }; - - /** - * Published timestamp/date from page metadata, when present. - */ - publishedTime?: string; - - /** - * Robots meta directive, when present. - */ - robots?: string; - - /** - * Site or application name from page metadata. - */ - siteName?: string; - - /** - * Best title extracted from the page. - */ - title?: string; - - /** - * Twitter card metadata with the twitter: prefix removed and keys camel-cased. - */ - twitter?: { [key: string]: string | Array }; - } - - export namespace Metadata { - export interface Alternate { - /** - * Resolved alternate URL. - */ - href: string; - - /** - * Language or locale for the alternate URL, when present. - */ - hreflang?: string; - - /** - * Alternate resource title, when present. - */ - title?: string; - - /** - * Alternate resource MIME type, when present. - */ - type?: string; - } - - export interface Heading { - /** - * Heading level, 1–6 (from h1–h6). - */ - level: number; - - /** - * Heading text with whitespace collapsed, truncated to 1000 characters. - */ - text: string; - } - } - - export interface ActionsApplied { - instruction: string; - - /** - * Applied means the requested page state was visibly verified. Failed means it was - * not verified. Skipped means it was not attempted. - */ - status: 'applied' | 'failed' | 'skipped'; - - /** - * Visible page evidence used to verify an applied action. - */ - completionEvidence?: string; - - durationMs?: number; - - error?: string; - - method?: string; - - targetDescription?: string; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - -export interface WebWebScrapeImagesResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: WebWebScrapeImagesResponse.CacheMetadata; - - /** - * Images found on the page. - */ - images: Array; + /** + * Required when formats.parse is true. + */ + parseParams?: WebScrapeParams.ParseParams; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Always true on success. - */ - success: true; - - /** - * Page URL that was scraped. + * Screenshot options. Requires formats.screenshot: true. */ - url: string; + screenshotParams?: WebScrapeParams.ScreenshotParams; /** - * One verified outcome per requested browser action, in request order. + * Shared browser and content settings. Content filters leave screenshots and + * original bytes unchanged. */ - actionsApplied?: Array; + sharedParams?: WebScrapeParams.SharedParams; /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. + * Labels for tracking request usage. Not retained when zdr is enabled. */ - finalDOMState?: 'loaded' | 'still-loading'; + tags?: Array; /** - * Credit usage, included whenever a valid API key is provided. + * Total deadline, including navigation, actions, waiting, and all outputs. + * Defaults to 60000 milliseconds with behavior fail. Use return-partial to capture + * the current page state and return captured images if image processing cannot + * finish before the deadline; these responses set isPartial and are not cached. + * Every requested format must still be available. Fixed waits must fit before a + * response reserve of up to 5000 milliseconds (at most one quarter of the timeout) + * when using return-partial. */ - key_metadata?: WebWebScrapeImagesResponse.KeyMetadata; + timeoutOpts?: WebScrapeParams.TimeoutOpts; /** - * True when the deadline interrupted rendering or image enrichment. Partial - * results are billed at the base request cost, without enrichment or actions - * surcharges. + * Zero data retention. Bypasses caches and uploads; excludes request/response + * content and tags from logs. Must be enabled for your organization. */ - partial?: boolean; + zdr?: 'enabled' | 'disabled'; } -export namespace WebWebScrapeImagesResponse { +export namespace WebScrapeParams { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Outputs to return. Enable at least one; omitted formats are false. */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - export interface Image { - /** - * Image alt text, or null when unavailable. - */ - alt: string | null; - - /** - * Where the image was found. - */ - element: 'img' | 'svg' | 'link' | 'source' | 'video' | 'css' | 'object' | 'meta' | 'background'; - - /** - * Original image value: URL, inline SVG or HTML, or base64 data URI. - */ - src: string; - - /** - * Format of src. - */ - type: 'url' | 'html' | 'base64'; - + export interface Formats { /** - * Requested metadata for images that could be processed. + * The original HTTP response body. */ - enrichment?: Image.Enrichment; - } + bytes?: boolean; - export namespace Image { /** - * Requested metadata for images that could be processed. + * Rendered HTML. */ - export interface Enrichment { - /** - * Image height in pixels, when measured. - */ - height?: number; - - /** - * Detected MIME type, when hosted. - */ - mimetype?: string; - - /** - * Visual asset category, when classified. - */ - type?: 'photography' | 'illustration' | 'logo' | 'wordmark' | 'icon' | 'pattern' | 'graphic' | 'other'; - - /** - * Brand.dev CDN URL, when hosted. - */ - url?: string; - - /** - * Image width in pixels, when measured. - */ - width?: number; - } - } - - export interface ActionsApplied { - instruction: string; + html?: boolean; /** - * Applied means the requested page state was visibly verified. Failed means it was - * not verified. Skipped means it was not attempted. + * Images found on the page. */ - status: 'applied' | 'failed' | 'skipped'; + images?: boolean; /** - * Visible page evidence used to verify an applied action. + * Page content as Markdown. */ - completionEvidence?: string; - - durationMs?: number; - - error?: string; - - method?: string; - - targetDescription?: string; - } + markdown?: boolean; - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { /** - * Credits used by this request. + * Fields selected by parseParams.rules. */ - credits_consumed: number; + parse?: boolean; /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - -export interface WebWebScrapeMdResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: WebWebScrapeMdResponse.CacheMetadata; - - /** - * UTF-8 byte length of the returned Markdown. Use 0 to identify an empty result - * and compare small values against your workload's minimum useful-content - * threshold. - */ - contentLength: number; - - /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. - */ - finalDOMState: 'loaded' | 'still-loading'; - - /** - * Page content converted to GitHub Flavored Markdown - */ - markdown: string; - - /** - * Metadata extracted from the scraped page HTML. - */ - metadata: WebWebScrapeMdResponse.Metadata; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Indicates success - */ - success: true; - - /** - * The URL that was scraped - */ - url: string; - - /** - * One verified outcome per requested browser action, in request order. - */ - actionsApplied?: Array; - - /** - * True when an action was applied but the returned content could not be refreshed - * afterward. - */ - actionsHtmlStale?: boolean; - - /** - * Only present when includeHTML=true: the page HTML the Markdown was converted - * from — the same body the Scrape HTML endpoint returns for the equivalent - * request. - */ - html?: string; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: WebWebScrapeMdResponse.KeyMetadata; -} - -export namespace WebWebScrapeMdResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - /** - * Metadata extracted from the scraped page HTML. - */ - export interface Metadata { - /** - * Final URL scraped after redirects or scraper fallback, when known. Falls back to - * sourceUrl when unavailable. - */ - finalUrl: string; - - /** - * Original URL requested by the caller. - */ - sourceUrl: string; - - /** - * Additional non-social meta tags not promoted to top-level metadata fields. - */ - additionalMeta?: { [key: string]: string | Array }; - - /** - * Resolved alternate links from link rel=alternate tags. - */ - alternates?: Array; - - /** - * Author metadata, when present. - */ - author?: string; - - /** - * Resolved canonical URL, when present. - */ - canonicalUrl?: string; - - /** - * Best description extracted from standard, Open Graph, or Twitter metadata. - */ - description?: string; - - /** - * Resolved favicon URL, when present. - */ - favicon?: string; - - /** - * Page headings (h1–h6) in document order, extracted from the unfiltered document. - * Capped at the first 500 headings. Omitted when the page has none. - */ - headings?: Array; - - /** - * Primary resolved preview image from Open Graph, Twitter, or image metadata. - */ - image?: string; - - /** - * JSON-LD structured data blocks parsed from the page. - */ - jsonLd?: Array<{ [key: string]: unknown }>; - - /** - * Keywords extracted from the page's keywords meta tag. - */ - keywords?: Array; - - /** - * Language extracted from html lang or language meta tags. - */ - language?: string; - - /** - * Modified timestamp/date from page metadata, when present. - */ - modifiedTime?: string; - - /** - * Open Graph metadata with the og: prefix removed and keys camel-cased. - */ - openGraph?: { [key: string]: string | Array }; - - /** - * Published timestamp/date from page metadata, when present. - */ - publishedTime?: string; - - /** - * Robots meta directive, when present. - */ - robots?: string; - - /** - * Site or application name from page metadata. - */ - siteName?: string; - - /** - * Best title extracted from the page. - */ - title?: string; - - /** - * Twitter card metadata with the twitter: prefix removed and keys camel-cased. - */ - twitter?: { [key: string]: string | Array }; - } - - export namespace Metadata { - export interface Alternate { - /** - * Resolved alternate URL. - */ - href: string; - - /** - * Language or locale for the alternate URL, when present. - */ - hreflang?: string; - - /** - * Alternate resource title, when present. - */ - title?: string; - - /** - * Alternate resource MIME type, when present. - */ - type?: string; - } - - export interface Heading { - /** - * Heading level, 1–6 (from h1–h6). - */ - level: number; - - /** - * Heading text with whitespace collapsed, truncated to 1000 characters. - */ - text: string; - } - } - - export interface ActionsApplied { - instruction: string; - - /** - * Applied means the requested page state was visibly verified. Failed means it was - * not verified. Skipped means it was not attempted. - */ - status: 'applied' | 'failed' | 'skipped'; - - /** - * Visible page evidence used to verify an applied action. - */ - completionEvidence?: string; - - durationMs?: number; - - error?: string; - - method?: string; - - targetDescription?: string; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - -export interface WebWebScrapeScreenshotResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - cache_metadata: WebWebScrapeScreenshotResponse.CacheMetadata; - - /** - * Height of the returned image in pixels. - */ - height: number; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Public image URL for standard requests, or an in-memory data URL when ZDR or - * non-empty custom headers are supplied. - */ - screenshot: string; - - /** - * The requested page URL. - */ - url: string; - - /** - * Width of the returned image in pixels. - */ - width: number; - - /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. - */ - finalDOMState?: 'loaded' | 'still-loading'; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: WebWebScrapeScreenshotResponse.KeyMetadata; -} - -export namespace WebWebScrapeScreenshotResponse { - /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; - - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - -export interface WebWebScrapeSitemapResponse { - /** - * The normalized domain that was crawled - */ - domain: string; - - /** - * Metadata about the sitemap crawl operation - */ - meta: WebWebScrapeSitemapResponse.Meta; - - /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. - */ - request_id: string; - - /** - * Indicates success - */ - success: true; - - /** - * Discovered page URLs from the sitemap, up to `maxLinks`. When `search` is set - * these are only the matching pages, most relevant first. - */ - urls: Array; - - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: WebWebScrapeSitemapResponse.KeyMetadata; - - /** - * True when timeoutOpts.behavior=return-partial returned the usable results - * collected before the deadline. Partial collections are not cached as complete - * results. - */ - partial?: boolean; -} - -export namespace WebWebScrapeSitemapResponse { - /** - * Metadata about the sitemap crawl operation - */ - export interface Meta { - /** - * Number of errors encountered during crawling - */ - errors: number; - - /** - * Total number of sitemap files discovered - */ - sitemapsDiscovered: number; - - /** - * Number of sitemap files successfully fetched and parsed - */ - sitemapsFetched: number; - - /** - * Number of sitemap files skipped (due to errors, timeouts, or limits) - */ - sitemapsSkipped: number; - } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} - -export interface WebAnswersParams { - /** - * What to research and answer, in plain language. Naming a domain in the task (for - * example "pricing on context.dev") makes the agent read that site before it - * searches. - */ - task: string; - - /** - * An example object with placeholder values (for example {"pricing_page_url": "", - * "plans": [{"name": "", "price": 0}]}). Object keys and value types are - * preserved; unknown values may be null. Empty arrays accept any JSON items. - * Defaults to {"result": ""}. Maximum 8 levels, 500 values, and 16000 characters. - */ - json_format?: { [key: string]: unknown }; - - /** - * Research level: fast uses a smaller model and research budget for 10 credits; - * ultra uses deeper reasoning and research for 100 credits. Defaults to ultra. - * Only successful requests consume credits. - */ - mode?: 'fast' | 'ultra'; - - /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebAnswersParams.TimeoutOpts; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebAnswersParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export interface WebExtractParams { - /** - * JSON Schema for the returned data object. Image fields such as `image_urls` or - * `product_photos` automatically make page image references available to - * extraction, so product data and photos can be returned in one call. TypeScript - * Zod users can pass a JSON Schema generated from a Zod object; Python users can - * pass the equivalent JSON Schema object. - */ - schema: { [key: string]: unknown }; - - /** - * The starting website URL to crawl and extract from. Must include http:// or - * https://. - */ - url: string; - - /** - * Optional browser actions executed in order on the requested page after it loads, - * before links are discovered or additional pages are crawled. Requires a paid - * plan. When actions are provided and stopAfterMs is omitted, the crawl budget - * defaults to 110000 ms. - */ - actions?: Array< - | WebExtractParams.WebScrapeWaitAction - | WebExtractParams.WebScrapePerformAction - | WebExtractParams.WebScrapeScrollAction - >; - - /** - * When true, every returned value must be grounded in facts stated on the page; - * fields that cannot be supported by the page are returned as null/empty. When - * false (default), the model may make reasonable inferences and derivations from - * the page content (e.g. ideal customer, competitor analysis, recommendations) - * while keeping verifiable specifics (names, quotes, URLs, dates, metrics) - * faithful to the source. - */ - factCheck?: boolean; - - /** - * When true, follow links on subdomains of the starting URL's domain. - */ - followSubdomains?: boolean; - - /** - * When true, iframe contents are included in Markdown before extraction. - */ - includeFrames?: boolean; - - /** - * Optional extraction guidance, such as which facts to prioritize or how to - * interpret fields in the schema. - */ - instructions?: string; - - /** - * Return cached scrape results if a prior scrape for the same parameters is - * younger than this many milliseconds. Defaults to 7 days (604800000 ms). - */ - maxAgeMs?: number; - - /** - * Optional maximum link depth from the starting URL (0 = only the starting page). - * If omitted, there is no crawl depth limit. - */ - maxDepth?: number; - - /** - * Maximum number of pages to analyze for extraction. Hard cap: 50. Defaults to 5. - */ - maxPages?: number; - - pdf?: WebExtractParams.Pdf; - - /** - * When true, waits briefly for CSS and transition animations to settle before - * extracting each crawled page. Defaults to false. This adds a bit of latency in - * exchange for more stable output on animated pages. - */ - settleAnimations?: boolean; - - /** - * Soft time budget for the crawl in milliseconds. Min: 10000 (10s). Max: 110000 - * (110s). Defaults to 80000 (80s), or 110000 (110s) when browser actions are - * provided. - */ - stopAfterMs?: number; - - /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebExtractParams.TimeoutOpts; - - /** - * Optional browser wait time in milliseconds after initial page load for each - * crawled page. - */ - waitForMs?: number; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebExtractParams { - /** - * Pause for a fixed number of milliseconds before continuing to the next action. - */ - export interface WebScrapeWaitAction { - do: 'wait'; - - timeMs: number; - } - - /** - * Resolve and perform one natural-language browser action. - */ - export interface WebScrapePerformAction { - action: string; - - do: 'perform'; - } - - /** - * Scroll the page or a selected scrollable container, waiting adaptively for - * content and dimensions to settle after each iteration. - */ - export interface WebScrapeScrollAction { - do: 'scroll'; - - /** - * Pixels per scroll, one visible viewport, or the current scroll boundary. - * Defaults to viewport. - */ - amount?: number | 'viewport' | 'max'; - - /** - * CSS selector for the first matching scroll container. Defaults to the page. - */ - container?: string; - - /** - * Direction to scroll. Defaults to down. - */ - direction?: 'up' | 'down' | 'left' | 'right'; - - /** - * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop - * changing. Defaults to 1. - */ - maxScrolls?: number; - } - - export interface Pdf { - /** - * Last 1-based PDF page to parse. Must be greater than or equal to start when both - * are provided. - */ - end?: number; - - /** - * When true, PDF pages are fetched and parsed. When false, PDF pages are skipped. - */ - shouldParse?: boolean; - - /** - * First 1-based PDF page to parse. - */ - start?: number; - } - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export interface WebExtractCompetitorsParams { - /** - * Company domain to analyze, such as `stripe.com`. Full http(s) URLs are accepted - * and normalized to their domain. - */ - domain: string; - - /** - * Exact number of direct competitors to return. Defaults to 5. - */ - numCompetitors?: number; - - /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebExtractCompetitorsParams.TimeoutOpts; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebExtractCompetitorsParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export interface WebExtractFontsParams { - /** - * A specific URL to fetch fonts from directly, bypassing domain resolution (e.g., - * 'https://example.com/design-system'). When provided, fonts are extracted from - * this exact URL. You must provide either 'domain' or 'directUrl', but not both. - */ - directUrl?: string; - - /** - * Domain name to extract fonts from (e.g., 'example.com', 'google.com'). The - * domain will be automatically normalized and validated. You must provide either - * 'domain' or 'directUrl', but not both. - */ - domain?: string; - - /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. - */ - maxAgeMs?: number | null; - - /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebExtractFontsParams.TimeoutOpts; -} - -export namespace WebExtractFontsParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export interface WebExtractStyleguideParams { - /** - * Optional browser color scheme to emulate for websites that respond to - * prefers-color-scheme. This value is part of the styleguide cache key. - */ - colorScheme?: 'light' | 'dark'; - - /** - * A specific URL to fetch the styleguide from directly, bypassing domain - * resolution (e.g., 'https://example.com/design-system'). When provided, the - * styleguide is extracted from this exact URL. You must provide either 'domain' or - * 'directUrl', but not both. - */ - directUrl?: string; - - /** - * Domain name to extract styleguide from (e.g., 'example.com', 'google.com'). The - * domain will be automatically normalized and validated. You must provide either - * 'domain' or 'directUrl', but not both. - */ - domain?: string; - - /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. - */ - maxAgeMs?: number | null; - - /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebExtractStyleguideParams.TimeoutOpts; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebExtractStyleguideParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export interface WebScrapeParams { - /** - * Outputs to return. Enable at least one; omitted formats are false. - */ - formats: WebScrapeParams.Formats; - - /** - * The URL to scrape. - */ - url: string; - - /** - * Image options. Requires formats.images: true. - */ - imageParams?: WebScrapeParams.ImageParams; - - /** - * Markdown options. Requires formats.markdown: true. - */ - markdownParams?: WebScrapeParams.MarkdownParams; - - /** - * Maximum age of each cached output. Defaults to 1 day; 0 fetches fresh and - * updates the requested outputs. Compatible outputs are shared with the individual - * scrape endpoints. Image results with hosted files refresh after 23 hours; other - * outputs retain their own freshness. - */ - maxAgeMs?: number; - - /** - * Required when formats.parse is true. - */ - parseParams?: WebScrapeParams.ParseParams; - - /** - * Screenshot options. Requires formats.screenshot: true. - */ - screenshotParams?: WebScrapeParams.ScreenshotParams; - - /** - * Shared browser and content settings. Content filters leave screenshots and - * original bytes unchanged. - */ - sharedParams?: WebScrapeParams.SharedParams; - - /** - * Labels for tracking request usage. Not retained when zdr is enabled. - */ - tags?: Array; - - /** - * Total deadline, including navigation, actions, waiting, and all outputs. - */ - timeoutMs?: number; - - /** - * Zero data retention. Bypasses caches and uploads; excludes request/response - * content and tags from logs. Must be enabled for your organization. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebScrapeParams { - /** - * Outputs to return. Enable at least one; omitted formats are false. - */ - export interface Formats { - /** - * The original HTTP response body. - */ - bytes?: boolean; - - /** - * Rendered HTML. - */ - html?: boolean; - - /** - * Images found on the page. - */ - images?: boolean; - - /** - * Page content as Markdown. - */ - markdown?: boolean; - - /** - * Fields selected by parseParams.rules. - */ - parse?: boolean; - - /** - * An inline image of the page. - */ - screenshot?: boolean; - } - - /** - * Image options. Requires formats.images: true. - */ - export interface ImageParams { - /** - * For visual duplicates, keep the largest image. - */ - dedupe?: 'none' | 'visual'; - - /** - * Add dimensions, a visual category, or a hosted file URL. - */ - enrich?: Array<'dimensions' | 'classification' | 'file'>; - } - - /** - * Markdown options. Requires formats.markdown: true. - */ - export interface MarkdownParams { - includeImages?: boolean; - - includeLinks?: boolean; - - /** - * Base64 images use placeholders by default. Requires includeImages: true. - */ - inlineImages?: 'placeholder' | 'preserve'; - } - - /** - * Required when formats.parse is true. - */ - export interface ParseParams { - /** - * Map field names to CSS selectors or rules. Missing items return null; missing - * lists return []. - */ - rules: { [key: string]: string | ParseParams.UnionMember1 }; - } - - export namespace ParseParams { - export interface UnionMember1 { - selector: string; - - output?: 'text' | 'html' | string | unknown; - - type?: 'item' | 'list'; - } - } - - /** - * Screenshot options. Requires formats.screenshot: true. - */ - export interface ScreenshotParams { - /** - * Viewport, full page, one visible element, or a rectangle. Maximum 40 megapixels. - */ - area?: 'viewport' | 'fullPage' | ScreenshotParams.Element | ScreenshotParams.Rectangle; - - format?: 'png' | 'jpeg' | 'webp'; - } - - export namespace ScreenshotParams { - export interface Element { - /** - * Must match one visible element. - */ - selector: string; - } - - /** - * Pixels from the document origin. - */ - export interface Rectangle { - height: number; - - width: number; - - x: number; - - y: number; - } - } - - /** - * Shared browser and content settings. Content filters leave screenshots and - * original bytes unchanged. - */ - export interface SharedParams { - /** - * Run in order before capture. A failed action fails the request. Bypasses - * caching. - */ - actions?: Array; - - /** - * Supported two-letter country code, case-insensitive. Applies to every output, - * including image downloads. - */ - country?: string; - - /** - * Dismiss cookie banners by accepting cookies before actions. - */ - dismissCookies?: boolean; - - /** - * Dismiss other popups before actions. - */ - dismissPopups?: boolean; - - /** - * Remove matching content. Exclusions win. - */ - excludeSelectors?: Array; - - /** - * Headers for the target origin. Requests with custom headers bypass caching. - */ - headers?: { [key: string]: string }; - - /** - * Include iframe content in extraction. Screenshots show visible frames - * regardless. - */ - includeFrames?: boolean; - - /** - * Keep matching content after mainContentOnly. - */ - includeSelectors?: Array; - - /** - * Keep only main content in HTML, Markdown, images, and parsed fields. - */ - mainContentOnly?: boolean; - - /** - * Document parsing options. - */ - parsers?: SharedParams.Parsers; - - /** - * Settle animations before capture. Defaults to true with screenshots, otherwise - * false. - */ - settleAnimations?: boolean; - - /** - * Override the browser color scheme. - */ - theme?: 'light' | 'dark'; - - /** - * Browser dimensions in pixels. - */ - viewport?: SharedParams.Viewport; - - /** - * After actions, wait this many milliseconds or until a CSS selector is visible. - * Defaults to 500 ms, or 2000 ms with frames or an XML URL. Set 0 to skip. - */ - waitFor?: number | string; - } - - export namespace SharedParams { - export interface Perform { - action: string; - - type: 'perform'; - } - - export interface Scroll { - type: 'scroll'; - - amount?: number | 'viewport' | 'max'; - - direction?: 'down' | 'up' | 'left' | 'right'; - - maxScrolls?: number; - - /** - * Scroll this container. Omit to scroll the page. - */ - selector?: string; - } - - export interface Wait { - milliseconds: number; - - type: 'wait'; - } - - export interface WaitFor { - selector: string; - - type: 'waitFor'; - } - - /** - * Document parsing options. - */ - export interface Parsers { - /** - * PDF text options for HTML, Markdown, and parsed fields. - */ - pdf?: Parsers.Pdf; - } - - export namespace Parsers { - /** - * PDF text options for HTML, Markdown, and parsed fields. - */ - export interface Pdf { - /** - * Last page to parse. Must be at least startPage. - */ - endPage?: number; - - /** - * Read text from scanned pages. - */ - ocr?: 'off' | 'auto'; - - /** - * First page to parse, starting at 1. - */ - startPage?: number; - } - } - - /** - * Browser dimensions in pixels. - */ - export interface Viewport { - height?: number; - - width?: number; - } - } -} - -export interface WebScreenshotParams { - /** - * Optional parameter for comprehensive popup cleanup. If 'true', the browser - * dismisses detected cookie/consent UI and clears other detected obstructive - * popups and overlays before capture. If 'false' or not provided, this parameter - * requests no cleanup; handleCookiePopup can still request cookie/consent handling - * independently. - */ - clearPopups?: boolean; - - /** - * Optional parameter to choose the site's visual theme in the screenshot. Use - * 'light' or 'dark' when the site offers both appearances. - */ - colorScheme?: 'light' | 'dark'; - - /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). - */ - country?: - | 'ad' - | 'ae' - | 'af' - | 'ag' - | 'ai' - | 'al' - | 'am' - | 'ao' - | 'ar' - | 'at' - | 'au' - | 'aw' - | 'az' - | 'ba' - | 'bb' - | 'bd' - | 'be' - | 'bf' - | 'bg' - | 'bh' - | 'bi' - | 'bj' - | 'bm' - | 'bn' - | 'bo' - | 'bq' - | 'br' - | 'bs' - | 'bw' - | 'by' - | 'bz' - | 'ca' - | 'cd' - | 'cf' - | 'cg' - | 'ch' - | 'ci' - | 'cl' - | 'cm' - | 'cn' - | 'co' - | 'cr' - | 'cv' - | 'cw' - | 'cy' - | 'cz' - | 'de' - | 'dj' - | 'dk' - | 'dm' - | 'do' - | 'dz' - | 'ec' - | 'ee' - | 'eg' - | 'es' - | 'et' - | 'fi' - | 'fj' - | 'fr' - | 'ga' - | 'gb' - | 'gd' - | 'ge' - | 'gf' - | 'gg' - | 'gh' - | 'gm' - | 'gn' - | 'gp' - | 'gq' - | 'gr' - | 'gt' - | 'gu' - | 'gw' - | 'gy' - | 'hk' - | 'hn' - | 'hr' - | 'ht' - | 'hu' - | 'id' - | 'ie' - | 'il' - | 'im' - | 'in' - | 'iq' - | 'ir' - | 'is' - | 'it' - | 'je' - | 'jm' - | 'jo' - | 'jp' - | 'ke' - | 'kg' - | 'kh' - | 'kn' - | 'kr' - | 'kw' - | 'ky' - | 'kz' - | 'la' - | 'lb' - | 'lc' - | 'lk' - | 'lr' - | 'ls' - | 'lt' - | 'lu' - | 'lv' - | 'ly' - | 'ma' - | 'mc' - | 'md' - | 'me' - | 'mf' - | 'mg' - | 'mk' - | 'ml' - | 'mm' - | 'mn' - | 'mo' - | 'mq' - | 'mr' - | 'mt' - | 'mu' - | 'mv' - | 'mw' - | 'mx' - | 'my' - | 'mz' - | 'na' - | 'nc' - | 'ne' - | 'ng' - | 'ni' - | 'nl' - | 'no' - | 'np' - | 'nz' - | 'om' - | 'pa' - | 'pe' - | 'pf' - | 'pg' - | 'ph' - | 'pk' - | 'pl' - | 'pr' - | 'ps' - | 'pt' - | 'py' - | 'qa' - | 're' - | 'ro' - | 'rs' - | 'ru' - | 'rw' - | 'sa' - | 'sc' - | 'sd' - | 'se' - | 'sg' - | 'si' - | 'sk' - | 'sl' - | 'sm' - | 'sn' - | 'so' - | 'sr' - | 'ss' - | 'st' - | 'sv' - | 'sx' - | 'sy' - | 'sz' - | 'tc' - | 'td' - | 'tg' - | 'th' - | 'tj' - | 'tl' - | 'tm' - | 'tn' - | 'tr' - | 'tt' - | 'tw' - | 'tz' - | 'ua' - | 'ug' - | 'us' - | 'uy' - | 'uz' - | 'vc' - | 've' - | 'vg' - | 'vi' - | 'vn' - | 'ye' - | 'yt' - | 'za' - | 'zm' - | 'zw'; - - /** - * A specific URL to screenshot directly, bypassing domain resolution (e.g., - * 'https://example.com/pricing'). When provided, the screenshot is taken of this - * exact URL. You must provide either 'domain' or 'directUrl', but not both. - */ - directUrl?: string; - - /** - * Domain name to take screenshot of (e.g., 'example.com', 'google.com'). The - * domain will be automatically normalized and validated. You must provide either - * 'domain' or 'directUrl', but not both. - */ - domain?: string; - - /** - * Optional parameter to determine screenshot type. If 'true', takes a full page - * screenshot capturing all content. If 'false' or not provided, takes a viewport - * screenshot (standard browser view). - */ - fullScreenshot?: 'true' | 'false'; - - /** - * Optional parameter to control cookie/consent popup handling. If 'true', we - * dismiss cookie banner before capture. If 'false' or not provided, captures the - * page without that step. - */ - handleCookiePopup?: boolean; - - /** - * Optional outbound HTTP headers, using the same JSON object or deep-object query - * format as other scrape endpoints (for example headers[Authorization]=Bearer - * token). Headers are scoped to the target origin during capture. For domain/page - * requests, discovery receives no custom headers and only pages on the resolved - * origin are eligible. Non-empty headers bypass screenshot caching and return an - * in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted - * headers. - */ - headers?: { [key: string]: string }; - - /** - * Return a cached screenshot if a prior screenshot for the same parameters exists - * and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh. - */ - maxAgeMs?: number | null; - - /** - * Optional parameter to specify which page type to screenshot. If provided, the - * system will scrape the domain's links and use heuristics to find the most - * appropriate URL for the specified page type (30 supported languages). If not - * provided, screenshots the main domain landing page. Only applicable when using - * 'domain', not 'directUrl'. - */ - page?: 'login' | 'signup' | 'blog' | 'careers' | 'pricing' | 'terms' | 'privacy' | 'contact'; - - /** - * Optional vertical scroll offset in pixels for capturing a long page in - * viewport-sized chunks. When provided, the full page is captured once and the - * returned image is the viewport-sized slice that begins at this Y offset (e.g. - * request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page - * top to bottom). The final slice may be shorter than the viewport height. Takes - * precedence over fullScreenshot. Max: 100000. - */ - scrollOffset?: number | null; - - /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebScreenshotParams.TimeoutOpts; - - /** - * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. - */ - viewport?: WebScreenshotParams.Viewport; - - /** - * Optional browser wait time in milliseconds after initial page load before taking - * the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when - * omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at - * least waitForMs + 10000 ms; a shorter deadline is rejected with 400 - * TIMEOUT_TOO_SHORT_FOR_WAIT. - */ - waitForMs?: number | null; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebScreenshotParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. - */ - behavior?: 'fail' | 'return-partial'; - } - - /** - * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. - */ - export interface Viewport { - /** - * Viewport height in pixels. - */ - height?: number; - - /** - * Viewport width in pixels. - */ - width?: number; - } -} - -export interface WebSearchParams { - /** - * Search query. Accepts natural language as well as Google-style search operators - * such as `site:`, `-site:`, `inurl:`, `intitle:`, quoted phrases, and `OR`. - */ - query: string; - - /** - * Two-letter ISO 3166-1 alpha-2 country code to localize results to a specific - * country (maps to Google's `gl` parameter). Example: "us", "gb", "de". - */ - country?: - | 'af' - | 'al' - | 'dz' - | 'as' - | 'ad' - | 'ao' - | 'ai' - | 'aq' - | 'ag' - | 'ar' - | 'am' - | 'aw' - | 'au' - | 'at' - | 'az' - | 'bs' - | 'bh' - | 'bd' - | 'bb' - | 'by' - | 'be' - | 'bz' - | 'bj' - | 'bm' - | 'bt' - | 'bo' - | 'ba' - | 'bw' - | 'bv' - | 'br' - | 'io' - | 'bn' - | 'bg' - | 'bf' - | 'bi' - | 'kh' - | 'cm' - | 'ca' - | 'cv' - | 'ky' - | 'cf' - | 'td' - | 'cl' - | 'cn' - | 'cx' - | 'cc' - | 'co' - | 'km' - | 'cg' - | 'cd' - | 'ck' - | 'cr' - | 'ci' - | 'hr' - | 'cu' - | 'cy' - | 'cz' - | 'dk' - | 'dj' - | 'dm' - | 'do' - | 'ec' - | 'eg' - | 'sv' - | 'gq' - | 'er' - | 'ee' - | 'et' - | 'fk' - | 'fo' - | 'fj' - | 'fi' - | 'fr' - | 'gf' - | 'pf' - | 'tf' - | 'ga' - | 'gm' - | 'ge' - | 'de' - | 'gh' - | 'gi' - | 'gr' - | 'gl' - | 'gd' - | 'gp' - | 'gu' - | 'gt' - | 'gn' - | 'gw' - | 'gy' - | 'ht' - | 'hm' - | 'va' - | 'hn' - | 'hk' - | 'hu' - | 'is' - | 'in' - | 'id' - | 'ir' - | 'iq' - | 'ie' - | 'il' - | 'it' - | 'jm' - | 'jp' - | 'jo' - | 'kz' - | 'ke' - | 'ki' - | 'kp' - | 'kr' - | 'kw' - | 'kg' - | 'la' - | 'lv' - | 'lb' - | 'ls' - | 'lr' - | 'ly' - | 'li' - | 'lt' - | 'lu' - | 'mo' - | 'mk' - | 'mg' - | 'mw' - | 'my' - | 'mv' - | 'ml' - | 'mt' - | 'mh' - | 'mq' - | 'mr' - | 'mu' - | 'yt' - | 'mx' - | 'fm' - | 'md' - | 'mc' - | 'mn' - | 'ms' - | 'ma' - | 'mz' - | 'mm' - | 'na' - | 'nr' - | 'np' - | 'nl' - | 'an' - | 'nc' - | 'nz' - | 'ni' - | 'ne' - | 'ng' - | 'nu' - | 'nf' - | 'mp' - | 'no' - | 'om' - | 'pk' - | 'pw' - | 'ps' - | 'pa' - | 'pg' - | 'py' - | 'pe' - | 'ph' - | 'pn' - | 'pl' - | 'pt' - | 'pr' - | 'qa' - | 're' - | 'ro' - | 'ru' - | 'rw' - | 'sh' - | 'kn' - | 'lc' - | 'pm' - | 'vc' - | 'ws' - | 'sm' - | 'st' - | 'sa' - | 'sn' - | 'rs' - | 'sc' - | 'sl' - | 'sg' - | 'sk' - | 'si' - | 'sb' - | 'so' - | 'za' - | 'gs' - | 'es' - | 'lk' - | 'sd' - | 'sr' - | 'sj' - | 'sz' - | 'se' - | 'ch' - | 'sy' - | 'tw' - | 'tj' - | 'tz' - | 'th' - | 'tl' - | 'tg' - | 'tk' - | 'to' - | 'tt' - | 'tn' - | 'tr' - | 'tm' - | 'tc' - | 'tv' - | 'ug' - | 'ua' - | 'ae' - | 'gb' - | 'us' - | 'um' - | 'uy' - | 'uz' - | 'vu' - | 've' - | 'vn' - | 'vg' - | 'vi' - | 'wf' - | 'eh' - | 'ye' - | 'zm' - | 'zw'; - - /** - * Blocklist — drop results from these domains. Example: ["pinterest.com", - * "reddit.com"]. - */ - excludeDomains?: Array; - - /** - * Restrict results to content published within this window. - */ - freshness?: 'last_24_hours' | 'last_week' | 'last_month' | 'last_year'; - - /** - * Allowlist — only return results from these domains. Example: ["arxiv.org", - * "github.com"]. - */ - includeDomains?: Array; - - /** - * Inline Markdown scraping for each result. Set `enabled: true` to activate. - */ - markdownOptions?: WebSearchParams.MarkdownOptions; - - /** - * Number of results to request and return (10–100). Defaults to 10. - */ - numResults?: number; - - /** - * Expand the query into multiple parallel variants for broader recall. - */ - queryFanout?: boolean; - - /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebSearchParams.TimeoutOpts; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebSearchParams { - /** - * Inline Markdown scraping for each result. Set `enabled: true` to activate. - */ - export interface MarkdownOptions { - /** - * Scrape each result to Markdown. Off by default to keep search cheap and fast. - */ - enabled?: boolean; - - /** - * Render iframe contents into the Markdown. - */ - includeFrames?: boolean; - - /** - * Emit image references in the Markdown. - */ - includeImages?: boolean; - - /** - * Keep hyperlinks in the Markdown. - */ - includeLinks?: boolean; - - /** - * Cache TTL in ms for scraped Markdown keyed by URL + options. Default 1 day, max - * 30 days. Set to 0 to force a fresh scrape. - */ - maxAgeMs?: number; - - /** - * PDF handling. Use start/end to bound text extraction and OCR to a page range. - */ - pdf?: MarkdownOptions.Pdf; - - /** - * Truncate inline base64 image payloads to keep responses small. - */ - shortenBase64Images?: boolean; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: MarkdownOptions.TimeoutOpts; - - /** - * Strip nav, header, footer, and sidebar — keep only the primary article content. - */ - useMainContentOnly?: boolean; - - /** - * Extra wait after page load before rendering, in ms (0–30000). Useful for - * JS-heavy pages. - */ - waitForMs?: number; - } - - export namespace MarkdownOptions { - /** - * PDF handling. Use start/end to bound text extraction and OCR to a page range. - */ - export interface Pdf { - /** - * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must - * be >= start. - */ - end?: number; - - /** - * Parse PDF URLs. When false, PDF results are skipped with WEBSITE_ACCESS_ERROR. - */ - shouldParse?: boolean; - - /** - * First PDF page to parse (1-based, inclusive). Defaults to page 1. - */ - start?: number; - } - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. - */ - behavior?: 'fail' | 'return-partial'; - } - } - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export interface WebWebCrawlMdParams { - /** - * The starting URL for the crawl (must include http:// or https:// protocol) - */ - url: string; - - /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). - */ - country?: - | 'ad' - | 'ae' - | 'af' - | 'ag' - | 'ai' - | 'al' - | 'am' - | 'ao' - | 'ar' - | 'at' - | 'au' - | 'aw' - | 'az' - | 'ba' - | 'bb' - | 'bd' - | 'be' - | 'bf' - | 'bg' - | 'bh' - | 'bi' - | 'bj' - | 'bm' - | 'bn' - | 'bo' - | 'bq' - | 'br' - | 'bs' - | 'bw' - | 'by' - | 'bz' - | 'ca' - | 'cd' - | 'cf' - | 'cg' - | 'ch' - | 'ci' - | 'cl' - | 'cm' - | 'cn' - | 'co' - | 'cr' - | 'cv' - | 'cw' - | 'cy' - | 'cz' - | 'de' - | 'dj' - | 'dk' - | 'dm' - | 'do' - | 'dz' - | 'ec' - | 'ee' - | 'eg' - | 'es' - | 'et' - | 'fi' - | 'fj' - | 'fr' - | 'ga' - | 'gb' - | 'gd' - | 'ge' - | 'gf' - | 'gg' - | 'gh' - | 'gm' - | 'gn' - | 'gp' - | 'gq' - | 'gr' - | 'gt' - | 'gu' - | 'gw' - | 'gy' - | 'hk' - | 'hn' - | 'hr' - | 'ht' - | 'hu' - | 'id' - | 'ie' - | 'il' - | 'im' - | 'in' - | 'iq' - | 'ir' - | 'is' - | 'it' - | 'je' - | 'jm' - | 'jo' - | 'jp' - | 'ke' - | 'kg' - | 'kh' - | 'kn' - | 'kr' - | 'kw' - | 'ky' - | 'kz' - | 'la' - | 'lb' - | 'lc' - | 'lk' - | 'lr' - | 'ls' - | 'lt' - | 'lu' - | 'lv' - | 'ly' - | 'ma' - | 'mc' - | 'md' - | 'me' - | 'mf' - | 'mg' - | 'mk' - | 'ml' - | 'mm' - | 'mn' - | 'mo' - | 'mq' - | 'mr' - | 'mt' - | 'mu' - | 'mv' - | 'mw' - | 'mx' - | 'my' - | 'mz' - | 'na' - | 'nc' - | 'ne' - | 'ng' - | 'ni' - | 'nl' - | 'no' - | 'np' - | 'nz' - | 'om' - | 'pa' - | 'pe' - | 'pf' - | 'pg' - | 'ph' - | 'pk' - | 'pl' - | 'pr' - | 'ps' - | 'pt' - | 'py' - | 'qa' - | 're' - | 'ro' - | 'rs' - | 'ru' - | 'rw' - | 'sa' - | 'sc' - | 'sd' - | 'se' - | 'sg' - | 'si' - | 'sk' - | 'sl' - | 'sm' - | 'sn' - | 'so' - | 'sr' - | 'ss' - | 'st' - | 'sv' - | 'sx' - | 'sy' - | 'sz' - | 'tc' - | 'td' - | 'tg' - | 'th' - | 'tj' - | 'tl' - | 'tm' - | 'tn' - | 'tr' - | 'tt' - | 'tw' - | 'tz' - | 'ua' - | 'ug' - | 'us' - | 'uy' - | 'uz' - | 'vc' - | 've' - | 'vg' - | 'vi' - | 'vn' - | 'ye' - | 'yt' - | 'za' - | 'zm' - | 'zw'; - - /** - * CSS selectors to remove before each crawled page is converted to Markdown. - * Applied after includeSelectors. Exclusion takes precedence: an element matching - * both is removed. Examples: "nav", "footer", ".ad-banner", "[aria-hidden=true]". - */ - excludeSelectors?: Array; - - /** - * When true, follow links on subdomains of the starting URL's domain (e.g. - * docs.example.com when starting from example.com). www and apex are always - * treated as equivalent. - */ - followSubdomains?: boolean; - - /** - * When true, the contents of iframes are rendered to Markdown for each crawled - * page. - */ - includeFrames?: boolean; - - /** - * Include image references in the Markdown output - */ - includeImages?: boolean; - - /** - * Preserve hyperlinks in the Markdown output - */ - includeLinks?: boolean; - - /** - * CSS selectors. When provided, only matching HTML subtrees (and their - * descendants) are kept before each crawled page is converted to Markdown. When - * omitted, the entire document is kept. Examples: "article.main", "#content", - * "[role=main]". - */ - includeSelectors?: Array; - - /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. - */ - maxAgeMs?: number; - - /** - * Maximum link depth from the starting URL (0 = only the starting page) - */ - maxDepth?: number; - - /** - * Maximum number of pages to crawl. Hard cap: 500. - */ - maxPages?: number; - - /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. - */ - pdf?: WebWebCrawlMdParams.Pdf; - - /** - * When true, waits briefly for CSS and transition animations to settle before - * extracting each crawled page. Defaults to false. This adds a bit of latency in - * exchange for more stable output on animated pages. - */ - settleAnimations?: boolean; - - /** - * Truncate base64-encoded image data in the Markdown output - */ - shortenBase64Images?: boolean; - - /** - * Soft time budget for the crawl in milliseconds. After each scrape, the crawler - * checks the elapsed time and, if exceeded, returns the pages collected so far - * instead of continuing. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 - * (80s). - */ - stopAfterMs?: number; - - /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebWebCrawlMdParams.TimeoutOpts; - - /** - * Regex pattern. Only URLs matching this pattern will be followed and scraped. An - * automatic prefix scope in the form ^ follows a redirect of the - * starting page. - */ - urlRegex?: string; - - /** - * Extract only the main content, stripping headers, footers, sidebars, and - * navigation - */ - useMainContentOnly?: boolean; - - /** - * Browser wait time in milliseconds after initial page load for each crawled page. - * Defaults to 3500 (3.5 seconds). Min: 0. Max: 30000 (30 seconds). - */ - waitForMs?: number; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebWebCrawlMdParams { - /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. - */ - export interface Pdf { - /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. - */ - end?: number; - - /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. - */ - ocr?: boolean; - - /** - * When true, PDF pages are fetched and parsed. When false, PDF pages are skipped - * entirely (not included in results and not counted as failures). - */ - shouldParse?: boolean; - - /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. - */ - start?: number; - } - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. - */ - behavior?: 'fail' | 'return-partial'; - } -} - -export interface WebWebScrapeBytesParams { - /** - * Full HTTP(S) URL of the resource to download, such as an image, PDF, or page. - */ - url: string; - - /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). - */ - country?: - | 'ad' - | 'ae' - | 'af' - | 'ag' - | 'ai' - | 'al' - | 'am' - | 'ao' - | 'ar' - | 'at' - | 'au' - | 'aw' - | 'az' - | 'ba' - | 'bb' - | 'bd' - | 'be' - | 'bf' - | 'bg' - | 'bh' - | 'bi' - | 'bj' - | 'bm' - | 'bn' - | 'bo' - | 'bq' - | 'br' - | 'bs' - | 'bw' - | 'by' - | 'bz' - | 'ca' - | 'cd' - | 'cf' - | 'cg' - | 'ch' - | 'ci' - | 'cl' - | 'cm' - | 'cn' - | 'co' - | 'cr' - | 'cv' - | 'cw' - | 'cy' - | 'cz' - | 'de' - | 'dj' - | 'dk' - | 'dm' - | 'do' - | 'dz' - | 'ec' - | 'ee' - | 'eg' - | 'es' - | 'et' - | 'fi' - | 'fj' - | 'fr' - | 'ga' - | 'gb' - | 'gd' - | 'ge' - | 'gf' - | 'gg' - | 'gh' - | 'gm' - | 'gn' - | 'gp' - | 'gq' - | 'gr' - | 'gt' - | 'gu' - | 'gw' - | 'gy' - | 'hk' - | 'hn' - | 'hr' - | 'ht' - | 'hu' - | 'id' - | 'ie' - | 'il' - | 'im' - | 'in' - | 'iq' - | 'ir' - | 'is' - | 'it' - | 'je' - | 'jm' - | 'jo' - | 'jp' - | 'ke' - | 'kg' - | 'kh' - | 'kn' - | 'kr' - | 'kw' - | 'ky' - | 'kz' - | 'la' - | 'lb' - | 'lc' - | 'lk' - | 'lr' - | 'ls' - | 'lt' - | 'lu' - | 'lv' - | 'ly' - | 'ma' - | 'mc' - | 'md' - | 'me' - | 'mf' - | 'mg' - | 'mk' - | 'ml' - | 'mm' - | 'mn' - | 'mo' - | 'mq' - | 'mr' - | 'mt' - | 'mu' - | 'mv' - | 'mw' - | 'mx' - | 'my' - | 'mz' - | 'na' - | 'nc' - | 'ne' - | 'ng' - | 'ni' - | 'nl' - | 'no' - | 'np' - | 'nz' - | 'om' - | 'pa' - | 'pe' - | 'pf' - | 'pg' - | 'ph' - | 'pk' - | 'pl' - | 'pr' - | 'ps' - | 'pt' - | 'py' - | 'qa' - | 're' - | 'ro' - | 'rs' - | 'ru' - | 'rw' - | 'sa' - | 'sc' - | 'sd' - | 'se' - | 'sg' - | 'si' - | 'sk' - | 'sl' - | 'sm' - | 'sn' - | 'so' - | 'sr' - | 'ss' - | 'st' - | 'sv' - | 'sx' - | 'sy' - | 'sz' - | 'tc' - | 'td' - | 'tg' - | 'th' - | 'tj' - | 'tl' - | 'tm' - | 'tn' - | 'tr' - | 'tt' - | 'tw' - | 'tz' - | 'ua' - | 'ug' - | 'us' - | 'uy' - | 'uz' - | 'vc' - | 've' - | 'vg' - | 'vi' - | 'vn' - | 'ye' - | 'yt' - | 'za' - | 'zm' - | 'zw'; - - /** - * Optional outbound HTTP headers, such as Referer, Cookie, or Authorization. Send - * as a JSON object or deep-object query params such as - * headers[Referer]=https://example.com/. Host, Content-Length, and hop-by-hop - * transport headers are rejected. Authorization and cookies are removed when a - * redirect changes origin. Credential-bearing headers bypass cache reads and - * writes; other headers are included in the cache key. - */ - headers?: { [key: string]: string }; - - /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. - */ - maxAgeMs?: number | null; - - /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. - */ - tags?: Array; - - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebWebScrapeBytesParams.TimeoutOpts; - - /** - * Optional browser wait time after initial page load, in milliseconds (0–30000; 0 - * uses 500). When supplied, HTML is rendered with JavaScript and returned as UTF-8 - * bytes. Other resources keep their original bytes without a browser wait. Omit to - * download the original HTTP response. When combined with timeoutOpts, - * timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter - * deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. - */ - waitForMs?: number | null; - - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} - -export namespace WebWebScrapeBytesParams { - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. This endpoint supports "fail": return 408 - * REQUEST_TIMEOUT without charging credits. - */ - behavior?: 'fail'; - } -} - -export interface WebWebScrapeHTMLParams { - /** - * Full URL to scrape (must include http:// or https:// protocol) - */ - url: string; - - /** - * Optional browser actions executed in array order after the page loads and before - * content is captured. Requires a paid plan. Send a JSON array in the query - * parameter. Maximum: 5 actions. - */ - actions?: Array< - | WebWebScrapeHTMLParams.WebScrapeWaitAction - | WebWebScrapeHTMLParams.WebScrapePerformAction - | WebWebScrapeHTMLParams.WebScrapeScrollAction - > | null; - - /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). - */ - country?: - | 'ad' - | 'ae' - | 'af' - | 'ag' - | 'ai' - | 'al' - | 'am' - | 'ao' - | 'ar' - | 'at' - | 'au' - | 'aw' - | 'az' - | 'ba' - | 'bb' - | 'bd' - | 'be' - | 'bf' - | 'bg' - | 'bh' - | 'bi' - | 'bj' - | 'bm' - | 'bn' - | 'bo' - | 'bq' - | 'br' - | 'bs' - | 'bw' - | 'by' - | 'bz' - | 'ca' - | 'cd' - | 'cf' - | 'cg' - | 'ch' - | 'ci' - | 'cl' - | 'cm' - | 'cn' - | 'co' - | 'cr' - | 'cv' - | 'cw' - | 'cy' - | 'cz' - | 'de' - | 'dj' - | 'dk' - | 'dm' - | 'do' - | 'dz' - | 'ec' - | 'ee' - | 'eg' - | 'es' - | 'et' - | 'fi' - | 'fj' - | 'fr' - | 'ga' - | 'gb' - | 'gd' - | 'ge' - | 'gf' - | 'gg' - | 'gh' - | 'gm' - | 'gn' - | 'gp' - | 'gq' - | 'gr' - | 'gt' - | 'gu' - | 'gw' - | 'gy' - | 'hk' - | 'hn' - | 'hr' - | 'ht' - | 'hu' - | 'id' - | 'ie' - | 'il' - | 'im' - | 'in' - | 'iq' - | 'ir' - | 'is' - | 'it' - | 'je' - | 'jm' - | 'jo' - | 'jp' - | 'ke' - | 'kg' - | 'kh' - | 'kn' - | 'kr' - | 'kw' - | 'ky' - | 'kz' - | 'la' - | 'lb' - | 'lc' - | 'lk' - | 'lr' - | 'ls' - | 'lt' - | 'lu' - | 'lv' - | 'ly' - | 'ma' - | 'mc' - | 'md' - | 'me' - | 'mf' - | 'mg' - | 'mk' - | 'ml' - | 'mm' - | 'mn' - | 'mo' - | 'mq' - | 'mr' - | 'mt' - | 'mu' - | 'mv' - | 'mw' - | 'mx' - | 'my' - | 'mz' - | 'na' - | 'nc' - | 'ne' - | 'ng' - | 'ni' - | 'nl' - | 'no' - | 'np' - | 'nz' - | 'om' - | 'pa' - | 'pe' - | 'pf' - | 'pg' - | 'ph' - | 'pk' - | 'pl' - | 'pr' - | 'ps' - | 'pt' - | 'py' - | 'qa' - | 're' - | 'ro' - | 'rs' - | 'ru' - | 'rw' - | 'sa' - | 'sc' - | 'sd' - | 'se' - | 'sg' - | 'si' - | 'sk' - | 'sl' - | 'sm' - | 'sn' - | 'so' - | 'sr' - | 'ss' - | 'st' - | 'sv' - | 'sx' - | 'sy' - | 'sz' - | 'tc' - | 'td' - | 'tg' - | 'th' - | 'tj' - | 'tl' - | 'tm' - | 'tn' - | 'tr' - | 'tt' - | 'tw' - | 'tz' - | 'ua' - | 'ug' - | 'us' - | 'uy' - | 'uz' - | 'vc' - | 've' - | 'vg' - | 'vi' - | 'vn' - | 'ye' - | 'yt' - | 'za' - | 'zm' - | 'zw'; - - /** - * CSS selectors to remove from the result. Applied after includeSelectors. - * Exclusion takes precedence: an element matching both is removed. Examples: - * "nav", "footer", ".ad-banner", "[aria-hidden=true]". - */ - excludeSelectors?: Array | null; - - /** - * Optional CSS extraction rules applied to the returned HTML after selector and - * main-content filtering. Use selector strings ("h1", "a@href") or objects with - * selector, type (item or list), and output (text, html, @attribute, or nested - * rules). Text whitespace is normalized; html includes the matched element; - * attributes are returned as written. Missing items are null and missing lists are - * empty. CSS only; XPath is not supported. Maximum: 100 fields across 5 levels. - * Send a JSON-encoded string in the extractRules query parameter. - */ - extractRules?: { [key: string]: string | WebWebScrapeHTMLParams.UnionMember1 }; - - /** - * Optional outbound HTTP headers forwarded only to the target URL, sent as - * deep-object query params such as headers[X-Custom]=value. When provided, caching - * is bypassed: the result is neither read from nor written to cache. - */ - headers?: { [key: string]: string }; - - /** - * When true, iframes are rendered inline into the returned HTML. - */ - includeFrames?: boolean; - - /** - * CSS selectors. When provided, only matching subtrees (and their descendants) are - * kept and everything else is dropped. When omitted, the entire document is kept. - * Examples: "article.main", "#content", "[role=main]". - */ - includeSelectors?: Array | null; - - /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. - */ - maxAgeMs?: number | null; + * An inline image of the page. + */ + screenshot?: boolean; + } /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * Image options. Requires formats.images: true. */ - pdf?: WebWebScrapeHTMLParams.Pdf; + export interface ImageParams { + /** + * For visual duplicates, keep the largest image. + */ + dedupe?: 'none' | 'visual'; - /** - * When true, waits briefly for CSS and transition animations to settle before - * extracting HTML. Defaults to false. This adds a bit of latency in exchange for - * more stable output on animated pages. - */ - settleAnimations?: boolean; + /** + * Add dimensions, a visual category, or a hosted file URL. Each image has a + * maximum processing time of 30000 milliseconds, bounded by the remaining request + * deadline. + */ + enrich?: Array<'dimensions' | 'classification' | 'file'>; + } /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Markdown options. Requires formats.markdown: true. */ - tags?: Array; + export interface MarkdownParams { + includeImages?: boolean; - /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. - */ - timeoutOpts?: WebWebScrapeHTMLParams.TimeoutOpts; + includeLinks?: boolean; - /** - * When true, return only the page's main content in the HTML response, excluding - * headers, footers, sidebars, and navigation when detectable. - */ - useMainContentOnly?: boolean; + /** + * Base64 images use placeholders by default. Requires includeImages: true. + */ + inlineImages?: 'placeholder' | 'preserve'; + } /** - * Optional browser wait time in milliseconds after initial page load. Min: 0. Max: - * 30000 (30 seconds). When combined with timeoutOpts, timeoutOpts.milliseconds - * must be at least waitForMs + 10000 ms; a shorter deadline is rejected with 400 - * TIMEOUT_TOO_SHORT_FOR_WAIT. + * Required when formats.parse is true. */ - waitForMs?: number | null; + export interface ParseParams { + /** + * Map field names to CSS selectors or rules. Missing items return null; missing + * lists return []. + */ + rules: { [key: string]: string | ParseParams.UnionMember1 }; + } - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} + export namespace ParseParams { + export interface UnionMember1 { + selector: string; -export namespace WebWebScrapeHTMLParams { - /** - * Pause for a fixed number of milliseconds before continuing to the next action. - */ - export interface WebScrapeWaitAction { - do: 'wait'; + output?: 'text' | 'html' | string | unknown; - timeMs: number; + type?: 'item' | 'list'; + } } /** - * Resolve and perform one natural-language browser action. + * Screenshot options. Requires formats.screenshot: true. */ - export interface WebScrapePerformAction { - action: string; + export interface ScreenshotParams { + /** + * Viewport, full page, one visible element, or a rectangle. Maximum 40 megapixels. + */ + area?: 'viewport' | 'fullPage' | ScreenshotParams.Element | ScreenshotParams.Rectangle; + + format?: 'png' | 'jpeg' | 'webp'; + } + + export namespace ScreenshotParams { + export interface Element { + /** + * Must match one visible element. + */ + selector: string; + } + + /** + * Pixels from the document origin. + */ + export interface Rectangle { + height: number; + + width: number; + + x: number; - do: 'perform'; + y: number; + } } /** - * Scroll the page or a selected scrollable container, waiting adaptively for - * content and dimensions to settle after each iteration. + * Shared browser and content settings. Content filters leave screenshots and + * original bytes unchanged. */ - export interface WebScrapeScrollAction { - do: 'scroll'; + export interface SharedParams { + /** + * Run in order before capture. A failed action fails the request. Bypasses + * caching. + */ + actions?: Array; /** - * Pixels per scroll, one visible viewport, or the current scroll boundary. - * Defaults to viewport. + * Supported two-letter country code, case-insensitive. Applies to every output, + * including image downloads. */ - amount?: number | 'viewport' | 'max'; + country?: string; /** - * CSS selector for the first matching scroll container. Defaults to the page. + * Dismiss cookie banners by accepting cookies before actions. */ - container?: string; + dismissCookies?: boolean; /** - * Direction to scroll. Defaults to down. + * Dismiss other popups before actions. */ - direction?: 'up' | 'down' | 'left' | 'right'; + dismissPopups?: boolean; /** - * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop - * changing. Defaults to 1. + * Remove matching content. Exclusions win. */ - maxScrolls?: number; - } + excludeSelectors?: Array; - export interface UnionMember1 { - selector: string; + /** + * Headers for the target origin. Requests with custom headers bypass caching. + */ + headers?: { [key: string]: string }; - output?: 'text' | 'html' | string | { [key: string]: string | UnionMember1.UnionMember1 }; + /** + * Include iframe content in extraction. Screenshots show visible frames + * regardless. + */ + includeFrames?: boolean; - type?: 'item' | 'list'; - } + /** + * Keep matching content after mainContentOnly. + */ + includeSelectors?: Array; - export namespace UnionMember1 { - export interface UnionMember1 { - selector: string; + /** + * Keep only main content in HTML, Markdown, images, and parsed fields. + */ + mainContentOnly?: boolean; - output?: 'text' | 'html' | string | unknown; + /** + * Document parsing options. + */ + parsers?: SharedParams.Parsers; - type?: 'item' | 'list'; - } - } + /** + * Settle animations before capture. Defaults to true with screenshots, otherwise + * false. + */ + settleAnimations?: boolean; - /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. - */ - export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Override the browser color scheme. */ - end?: number; + theme?: 'light' | 'dark'; /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. When false, no OCR runs. + * Browser dimensions in pixels. */ - ocr?: boolean; + viewport?: SharedParams.Viewport; /** - * When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and - * a 400 PDF_SKIPPED is returned. + * After actions, wait this many milliseconds or until a CSS selector is visible. + * Defaults to 500 ms, or 2000 ms with frames or an XML URL. Set 0 to skip. */ - shouldParse?: boolean; + waitFor?: number | string; + } + + export namespace SharedParams { + export interface Perform { + action: string; + + type: 'perform'; + } + + export interface Scroll { + type: 'scroll'; + + amount?: number | 'viewport' | 'max'; + + direction?: 'down' | 'up' | 'left' | 'right'; + + maxScrolls?: number; + + /** + * Scroll this container. Omit to scroll the page. + */ + selector?: string; + } + + export interface Wait { + milliseconds: number; + + type: 'wait'; + } + + export interface WaitFor { + selector: string; + + type: 'waitFor'; + } /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * Document parsing options. */ - start?: number; + export interface Parsers { + /** + * PDF text options for HTML, Markdown, and parsed fields. + */ + pdf?: Parsers.Pdf; + } + + export namespace Parsers { + /** + * PDF text options for HTML, Markdown, and parsed fields. + */ + export interface Pdf { + /** + * Last page to parse. Must be at least startPage. + */ + endPage?: number; + + /** + * Read text from scanned pages. + */ + ocr?: 'off' | 'auto'; + + /** + * First page to parse, starting at 1. + */ + startPage?: number; + } + } + + /** + * Browser dimensions in pixels. + */ + export interface Viewport { + height?: number; + + width?: number; + } } /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Total deadline, including navigation, actions, waiting, and all outputs. + * Defaults to 60000 milliseconds with behavior fail. Use return-partial to capture + * the current page state and return captured images if image processing cannot + * finish before the deadline; these responses set isPartial and are not cached. + * Every requested format must still be available. Fixed waits must fit before a + * response reserve of up to 5000 milliseconds (at most one quarter of the timeout) + * when using return-partial. */ export interface TimeoutOpts { /** @@ -5874,22 +2411,21 @@ export namespace WebWebScrapeHTMLParams { } } -export interface WebWebScrapeImagesParams { +export interface WebScreenshotParams { /** - * Page URL to inspect. Must include http:// or https://. + * Optional parameter for comprehensive popup cleanup. If 'true', the browser + * dismisses detected cookie/consent UI and clears other detected obstructive + * popups and overlays before capture. If 'false' or not provided, this parameter + * requests no cleanup; handleCookiePopup can still request cookie/consent handling + * independently. */ - url: string; + clearPopups?: boolean; /** - * Optional browser actions executed in array order after the page loads and before - * content is captured. Requires a paid plan. Send a JSON array in the query - * parameter. Maximum: 5 actions. + * Optional parameter to choose the site's visual theme in the screenshot. Use + * 'light' or 'dark' when the site offers both appearances. */ - actions?: Array< - | WebWebScrapeImagesParams.WebScrapeWaitAction - | WebWebScrapeImagesParams.WebScrapePerformAction - | WebWebScrapeImagesParams.WebScrapeScrollAction - > | null; + colorScheme?: 'light' | 'dark'; /** * Fetch the target page through a residential proxy in this country (ISO 3166-1 @@ -6102,32 +2638,70 @@ export interface WebWebScrapeImagesParams { | 'zw'; /** - * When true, visually duplicate images are removed: every image is loaded and - * perceptually hashed, and only the highest-resolution copy of each duplicate - * group is kept. Images that cannot be downloaded or hashed are kept. Default: - * false. + * A specific URL to screenshot directly, bypassing domain resolution (e.g., + * 'https://example.com/pricing'). When provided, the screenshot is taken of this + * exact URL. You must provide either 'domain' or 'directUrl', but not both. */ - dedupe?: boolean; + directUrl?: string; /** - * Optional per-image processing, sent as deep-object query params such as - * enrichment[resolution]=true. + * Domain name to take screenshot of (e.g., 'example.com', 'google.com'). The + * domain will be automatically normalized and validated. You must provide either + * 'domain' or 'directUrl', but not both. */ - enrichment?: WebWebScrapeImagesParams.Enrichment | null; + domain?: string; /** - * Optional outbound HTTP headers forwarded only to the target URL, sent as - * deep-object query params such as headers[X-Custom]=value. When provided, caching - * is bypassed: the result is neither read from nor written to cache. + * Optional parameter to determine screenshot type. If 'true', takes a full page + * screenshot capturing all content. If 'false' or not provided, takes a viewport + * screenshot (standard browser view). + */ + fullScreenshot?: 'true' | 'false'; + + /** + * Optional parameter to control cookie/consent popup handling. If 'true', we + * dismiss cookie banner before capture. If 'false' or not provided, captures the + * page without that step. + */ + handleCookiePopup?: boolean; + + /** + * Optional outbound HTTP headers, using the same JSON object or deep-object query + * format as other scrape endpoints (for example headers[Authorization]=Bearer + * token). Headers are scoped to the target origin during capture. For domain/page + * requests, discovery receives no custom headers and only pages on the resolved + * origin are eligible. Non-empty headers bypass screenshot caching and return an + * in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted + * headers. */ headers?: { [key: string]: string }; /** - * Reuse a cached result this many milliseconds old or newer. Default: 86400000 (1 - * day). Set to 0 to bypass cache. Maximum: 2592000000 (30 days). + * Return a cached screenshot if a prior screenshot for the same parameters exists + * and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when + * omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh. */ maxAgeMs?: number | null; + /** + * Optional parameter to specify which page type to screenshot. If provided, the + * system will scrape the domain's links and use heuristics to find the most + * appropriate URL for the specified page type (30 supported languages). If not + * provided, screenshots the main domain landing page. Only applicable when using + * 'domain', not 'directUrl'. + */ + page?: 'login' | 'signup' | 'blog' | 'careers' | 'pricing' | 'terms' | 'privacy' | 'contact'; + + /** + * Optional vertical scroll offset in pixels for capturing a long page in + * viewport-sized chunks. When provided, the full page is captured once and the + * returned image is the viewport-sized slice that begins at this Y offset (e.g. + * request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page + * top to bottom). The final slice may be shorter than the viewport height. Takes + * precedence over fullScreenshot. Max: 100000. + */ + scrollOffset?: number | null; + /** * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 * characters. @@ -6139,13 +2713,19 @@ export interface WebWebScrapeImagesParams { * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded * timeoutOpts object. */ - timeoutOpts?: WebWebScrapeImagesParams.TimeoutOpts; + timeoutOpts?: WebScreenshotParams.TimeoutOpts; + + /** + * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. + */ + viewport?: WebScreenshotParams.Viewport; /** - * Optional browser wait time in milliseconds after initial page load before - * collecting images. Min: 0. Max: 30000 (30 seconds). When combined with - * timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a - * shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. + * Optional browser wait time in milliseconds after initial page load before taking + * the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when + * omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at + * least waitForMs + 10000 ms; a shorter deadline is rejected with 400 + * TIMEOUT_TOO_SHORT_FOR_WAIT. */ waitForMs?: number | null; @@ -6159,82 +2739,7 @@ export interface WebWebScrapeImagesParams { zdr?: 'enabled' | 'disabled'; } -export namespace WebWebScrapeImagesParams { - /** - * Pause for a fixed number of milliseconds before continuing to the next action. - */ - export interface WebScrapeWaitAction { - do: 'wait'; - - timeMs: number; - } - - /** - * Resolve and perform one natural-language browser action. - */ - export interface WebScrapePerformAction { - action: string; - - do: 'perform'; - } - - /** - * Scroll the page or a selected scrollable container, waiting adaptively for - * content and dimensions to settle after each iteration. - */ - export interface WebScrapeScrollAction { - do: 'scroll'; - - /** - * Pixels per scroll, one visible viewport, or the current scroll boundary. - * Defaults to viewport. - */ - amount?: number | 'viewport' | 'max'; - - /** - * CSS selector for the first matching scroll container. Defaults to the page. - */ - container?: string; - - /** - * Direction to scroll. Defaults to down. - */ - direction?: 'up' | 'down' | 'left' | 'right'; - - /** - * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop - * changing. Defaults to 1. - */ - maxScrolls?: number; - } - - /** - * Optional per-image processing, sent as deep-object query params such as - * enrichment[resolution]=true. - */ - export interface Enrichment { - /** - * Classify each image by visual asset type. - */ - classification?: boolean; - - /** - * Host materializable images on the Brand.dev CDN and return their URL and MIME - * type. Ignored when zero data retention is enabled. - */ - hostedUrl?: boolean; - - /** - * Per-image enrichment timeout in milliseconds. Default: 30000. Maximum: 60000. - */ - maxTimePerMs?: number; - - /** - * Measure image width and height when possible. - */ - resolution?: boolean; - } - +export namespace WebScreenshotParams { /** * Optional request deadline and behavior on timeout. For GET requests, use * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded @@ -6255,307 +2760,309 @@ export namespace WebWebScrapeImagesParams { */ behavior?: 'fail' | 'return-partial'; } -} -export interface WebWebScrapeMdParams { /** - * Full URL to scrape into LLM usable Markdown (must include http:// or https:// - * protocol) + * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. */ - url: string; + export interface Viewport { + /** + * Viewport height in pixels. + */ + height?: number; + + /** + * Viewport width in pixels. + */ + width?: number; + } +} +export interface WebSearchParams { /** - * Optional browser actions executed in array order after the page loads and before - * content is captured. Requires a paid plan. Send a JSON array in the query - * parameter. Maximum: 5 actions. + * Search query. Accepts natural language as well as Google-style search operators + * such as `site:`, `-site:`, `inurl:`, `intitle:`, quoted phrases, and `OR`. */ - actions?: Array< - | WebWebScrapeMdParams.WebScrapeWaitAction - | WebWebScrapeMdParams.WebScrapePerformAction - | WebWebScrapeMdParams.WebScrapeScrollAction - > | null; + query: string; /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). + * Two-letter ISO 3166-1 alpha-2 country code to localize results to a specific + * country (maps to Google's `gl` parameter). Example: "us", "gb", "de". */ country?: - | 'ad' - | 'ae' | 'af' - | 'ag' - | 'ai' | 'al' - | 'am' + | 'dz' + | 'as' + | 'ad' | 'ao' + | 'ai' + | 'aq' + | 'ag' | 'ar' - | 'at' - | 'au' + | 'am' | 'aw' + | 'au' + | 'at' | 'az' - | 'ba' - | 'bb' + | 'bs' + | 'bh' | 'bd' + | 'bb' + | 'by' | 'be' - | 'bf' - | 'bg' - | 'bh' - | 'bi' + | 'bz' | 'bj' | 'bm' - | 'bn' + | 'bt' | 'bo' - | 'bq' - | 'br' - | 'bs' + | 'ba' | 'bw' - | 'by' - | 'bz' + | 'bv' + | 'br' + | 'io' + | 'bn' + | 'bg' + | 'bf' + | 'bi' + | 'kh' + | 'cm' | 'ca' - | 'cd' + | 'cv' + | 'ky' | 'cf' - | 'cg' - | 'ch' - | 'ci' + | 'td' | 'cl' - | 'cm' | 'cn' + | 'cx' + | 'cc' | 'co' + | 'km' + | 'cg' + | 'cd' + | 'ck' | 'cr' - | 'cv' - | 'cw' + | 'ci' + | 'hr' + | 'cu' | 'cy' | 'cz' - | 'de' - | 'dj' | 'dk' + | 'dj' | 'dm' | 'do' - | 'dz' | 'ec' - | 'ee' | 'eg' - | 'es' + | 'sv' + | 'gq' + | 'er' + | 'ee' | 'et' - | 'fi' + | 'fk' + | 'fo' | 'fj' + | 'fi' | 'fr' + | 'gf' + | 'pf' + | 'tf' | 'ga' - | 'gb' - | 'gd' + | 'gm' | 'ge' - | 'gf' - | 'gg' + | 'de' | 'gh' - | 'gm' - | 'gn' - | 'gp' - | 'gq' + | 'gi' | 'gr' - | 'gt' + | 'gl' + | 'gd' + | 'gp' | 'gu' + | 'gt' + | 'gn' | 'gw' | 'gy' - | 'hk' - | 'hn' - | 'hr' | 'ht' + | 'hm' + | 'va' + | 'hn' + | 'hk' | 'hu' + | 'is' + | 'in' | 'id' + | 'ir' + | 'iq' | 'ie' | 'il' - | 'im' - | 'in' - | 'iq' - | 'ir' - | 'is' | 'it' - | 'je' | 'jm' - | 'jo' | 'jp' + | 'jo' + | 'kz' | 'ke' - | 'kg' - | 'kh' - | 'kn' + | 'ki' + | 'kp' | 'kr' | 'kw' - | 'ky' - | 'kz' + | 'kg' | 'la' + | 'lv' | 'lb' - | 'lc' - | 'lk' - | 'lr' | 'ls' + | 'lr' + | 'ly' + | 'li' | 'lt' | 'lu' - | 'lv' - | 'ly' - | 'ma' - | 'mc' - | 'md' - | 'me' - | 'mf' - | 'mg' + | 'mo' | 'mk' + | 'mg' + | 'mw' + | 'my' + | 'mv' | 'ml' - | 'mm' - | 'mn' - | 'mo' + | 'mt' + | 'mh' | 'mq' | 'mr' - | 'mt' | 'mu' - | 'mv' - | 'mw' + | 'yt' | 'mx' - | 'my' + | 'fm' + | 'md' + | 'mc' + | 'mn' + | 'ms' + | 'ma' | 'mz' + | 'mm' | 'na' + | 'nr' + | 'np' + | 'nl' + | 'an' | 'nc' + | 'nz' + | 'ni' | 'ne' | 'ng' - | 'ni' - | 'nl' + | 'nu' + | 'nf' + | 'mp' | 'no' - | 'np' - | 'nz' | 'om' + | 'pk' + | 'pw' + | 'ps' | 'pa' - | 'pe' - | 'pf' | 'pg' + | 'py' + | 'pe' | 'ph' - | 'pk' + | 'pn' | 'pl' - | 'pr' - | 'ps' | 'pt' - | 'py' + | 'pr' | 'qa' | 're' | 'ro' - | 'rs' | 'ru' | 'rw' + | 'sh' + | 'kn' + | 'lc' + | 'pm' + | 'vc' + | 'ws' + | 'sm' + | 'st' | 'sa' + | 'sn' + | 'rs' | 'sc' - | 'sd' - | 'se' + | 'sl' | 'sg' - | 'si' | 'sk' - | 'sl' - | 'sm' - | 'sn' + | 'si' + | 'sb' | 'so' + | 'za' + | 'gs' + | 'es' + | 'lk' + | 'sd' | 'sr' - | 'ss' - | 'st' - | 'sv' - | 'sx' - | 'sy' + | 'sj' | 'sz' - | 'tc' - | 'td' - | 'tg' - | 'th' + | 'se' + | 'ch' + | 'sy' + | 'tw' | 'tj' + | 'tz' + | 'th' | 'tl' - | 'tm' + | 'tg' + | 'tk' + | 'to' + | 'tt' | 'tn' | 'tr' - | 'tt' - | 'tw' - | 'tz' - | 'ua' + | 'tm' + | 'tc' + | 'tv' | 'ug' + | 'ua' + | 'ae' + | 'gb' | 'us' + | 'um' | 'uy' | 'uz' - | 'vc' + | 'vu' | 've' + | 'vn' | 'vg' | 'vi' - | 'vn' + | 'wf' + | 'eh' | 'ye' - | 'yt' - | 'za' | 'zm' | 'zw'; /** - * CSS selectors to remove before conversion to Markdown. Applied after - * includeSelectors. Exclusion takes precedence: an element matching both is - * removed. Examples: "nav", "footer", ".ad-banner", "[aria-hidden=true]". - */ - excludeSelectors?: Array | null; - - /** - * Optional outbound HTTP headers forwarded only to the target URL, sent as - * deep-object query params such as headers[X-Custom]=value. When provided, caching - * is bypassed: the result is neither read from nor written to cache. - */ - headers?: { [key: string]: string }; - - /** - * When true, the contents of iframes are rendered to Markdown. - */ - includeFrames?: boolean; - - /** - * When true, the response also includes an `html` field with the page HTML the - * Markdown was converted from — the same body the Scrape HTML endpoint returns for - * the equivalent request. - */ - includeHTML?: boolean; - - /** - * Include image references in Markdown output - */ - includeImages?: boolean; - - /** - * Preserve hyperlinks in Markdown output + * Blocklist — drop results from these domains. Example: ["pinterest.com", + * "reddit.com"]. */ - includeLinks?: boolean; + excludeDomains?: Array; /** - * CSS selectors. When provided, only matching HTML subtrees (and their - * descendants) are kept before conversion to Markdown. When omitted, the entire - * document is kept. Examples: "article.main", "#content", "[role=main]". + * Restrict results to content published within this window. */ - includeSelectors?: Array | null; + freshness?: 'last_24_hours' | 'last_week' | 'last_month' | 'last_year'; /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * Allowlist — only return results from these domains. Example: ["arxiv.org", + * "github.com"]. */ - maxAgeMs?: number | null; + includeDomains?: Array; /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * Inline Markdown scraping for each result. Set `enabled: true` to activate. */ - pdf?: WebWebScrapeMdParams.Pdf; + markdownOptions?: WebSearchParams.MarkdownOptions; /** - * When true, waits briefly for CSS and transition animations to settle before - * converting to Markdown. Defaults to false. This adds a bit of latency in - * exchange for more stable output on animated pages. + * Number of results to request and return (10–100). Defaults to 10. */ - settleAnimations?: boolean; + numResults?: number; /** - * Shorten base64-encoded image data in the Markdown output + * Expand the query into multiple parallel variants for broader recall. */ - shortenBase64Images?: boolean; + queryFanout?: boolean; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. */ tags?: Array; @@ -6564,21 +3071,7 @@ export interface WebWebScrapeMdParams { * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded * timeoutOpts object. */ - timeoutOpts?: WebWebScrapeMdParams.TimeoutOpts; - - /** - * Extract only the main content of the page, excluding headers, footers, sidebars, - * and navigation - */ - useMainContentOnly?: boolean; - - /** - * Optional browser wait time in milliseconds after initial page load before - * converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). When combined - * with timeoutOpts, timeoutOpts.milliseconds must be at least waitForMs + 10000 - * ms; a shorter deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT. - */ - waitForMs?: number | null; + timeoutOpts?: WebSearchParams.TimeoutOpts; /** * Set to enabled to bypass shared caches and omit request and response content @@ -6590,84 +3083,108 @@ export interface WebWebScrapeMdParams { zdr?: 'enabled' | 'disabled'; } -export namespace WebWebScrapeMdParams { +export namespace WebSearchParams { /** - * Pause for a fixed number of milliseconds before continuing to the next action. + * Inline Markdown scraping for each result. Set `enabled: true` to activate. */ - export interface WebScrapeWaitAction { - do: 'wait'; + export interface MarkdownOptions { + /** + * Scrape each result to Markdown. Off by default to keep search cheap and fast. + */ + enabled?: boolean; - timeMs: number; - } + /** + * Render iframe contents into the Markdown. + */ + includeFrames?: boolean; - /** - * Resolve and perform one natural-language browser action. - */ - export interface WebScrapePerformAction { - action: string; + /** + * Emit image references in the Markdown. + */ + includeImages?: boolean; - do: 'perform'; - } + /** + * Keep hyperlinks in the Markdown. + */ + includeLinks?: boolean; - /** - * Scroll the page or a selected scrollable container, waiting adaptively for - * content and dimensions to settle after each iteration. - */ - export interface WebScrapeScrollAction { - do: 'scroll'; + /** + * Cache TTL in ms for scraped Markdown keyed by URL + options. Default 1 day, max + * 30 days. Set to 0 to force a fresh scrape. + */ + maxAgeMs?: number; /** - * Pixels per scroll, one visible viewport, or the current scroll boundary. - * Defaults to viewport. + * PDF handling. Use start/end to bound text extraction and OCR to a page range. */ - amount?: number | 'viewport' | 'max'; + pdf?: MarkdownOptions.Pdf; /** - * CSS selector for the first matching scroll container. Defaults to the page. + * Truncate inline base64 image payloads to keep responses small. */ - container?: string; + shortenBase64Images?: boolean; /** - * Direction to scroll. Defaults to down. + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - direction?: 'up' | 'down' | 'left' | 'right'; + timeoutOpts?: MarkdownOptions.TimeoutOpts; /** - * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop - * changing. Defaults to 1. + * Strip nav, header, footer, and sidebar — keep only the primary article content. */ - maxScrolls?: number; - } + useMainContentOnly?: boolean; - /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. - */ - export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Extra wait after page load before rendering, in ms (0–30000). Useful for + * JS-heavy pages. */ - end?: number; + waitForMs?: number; + } + export namespace MarkdownOptions { /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. When false, no OCR runs. + * PDF handling. Use start/end to bound text extraction and OCR to a page range. */ - ocr?: boolean; + export interface Pdf { + /** + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. + */ + end?: number; + + /** + * Parse PDF URLs. When false, PDF results are skipped with WEBSITE_ACCESS_ERROR. + */ + shouldParse?: boolean; - /** - * When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and - * a 400 PDF_SKIPPED is returned. - */ - shouldParse?: boolean; + /** + * First PDF page to parse (1-based, inclusive). Defaults to page 1. + */ + start?: number; + } /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - start?: number; + export interface TimeoutOpts { + /** + * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + */ + milliseconds: number; + + /** + * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging + * credits. "return-partial" returns usable results collected so far; if none are + * available, the request still fails without charging credits. Partial results are + * not cached as complete results. "return-partial" requires milliseconds of at + * least 5000. + */ + behavior?: 'fail' | 'return-partial'; + } } /** @@ -6685,30 +3202,17 @@ export namespace WebWebScrapeMdParams { * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging * credits. "return-partial" returns usable results collected so far; if none are * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. + * not cached as complete results. */ behavior?: 'fail' | 'return-partial'; } } -export interface WebWebScrapeScreenshotParams { - url: string; - - /** - * Optional parameter for comprehensive popup cleanup. If 'true', the browser - * dismisses detected cookie/consent UI and clears other detected obstructive - * popups and overlays before capture. If 'false' or not provided, this parameter - * requests no cleanup; handleCookiePopup can still request cookie/consent handling - * independently. - */ - clearPopups?: boolean; - +export interface WebWebCrawlMdParams { /** - * Optional parameter to choose the site's visual theme in the screenshot. Use - * 'light' or 'dark' when the site offers both appearances. + * The starting URL for the crawl (must include http:// or https:// protocol) */ - colorScheme?: 'light' | 'dark'; + url: string; /** * Fetch the target page through a residential proxy in this country (ISO 3166-1 @@ -6921,190 +3425,158 @@ export interface WebWebScrapeScreenshotParams { | 'zw'; /** - * Optional parameter to determine screenshot type. If 'true', takes a full page - * screenshot capturing all content. If 'false' or not provided, takes a viewport - * screenshot (standard browser view). + * CSS selectors to remove before each crawled page is converted to Markdown. + * Applied after includeSelectors. Exclusion takes precedence: an element matching + * both is removed. Examples: "nav", "footer", ".ad-banner", "[aria-hidden=true]". */ - fullScreenshot?: 'true' | 'false'; + excludeSelectors?: Array; /** - * Optional parameter to control cookie/consent popup handling. If 'true', we - * dismiss cookie banner before capture. If 'false' or not provided, captures the - * page without that step. + * When true, follow links on subdomains of the starting URL's domain (e.g. + * docs.example.com when starting from example.com). www and apex are always + * treated as equivalent. */ - handleCookiePopup?: boolean; + followSubdomains?: boolean; /** - * Optional outbound HTTP headers, using the same JSON object or deep-object query - * format as other scrape endpoints (for example headers[Authorization]=Bearer - * token). Headers are scoped to the target origin during capture. For domain/page - * requests, discovery receives no custom headers and only pages on the resolved - * origin are eligible. Non-empty headers bypass screenshot caching and return an - * in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted - * headers. + * When true, the contents of iframes are rendered to Markdown for each crawled + * page. */ - headers?: { [key: string]: string }; + includeFrames?: boolean; /** - * Return a cached screenshot if a prior screenshot for the same parameters exists - * and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh. + * Include image references in the Markdown output */ - maxAgeMs?: number | null; + includeImages?: boolean; /** - * Optional vertical scroll offset in pixels for capturing a long page in - * viewport-sized chunks. When provided, the full page is captured once and the - * returned image is the viewport-sized slice that begins at this Y offset (e.g. - * request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page - * top to bottom). The final slice may be shorter than the viewport height. Takes - * precedence over fullScreenshot. Max: 100000. + * Preserve hyperlinks in the Markdown output */ - scrollOffset?: number | null; + includeLinks?: boolean; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * CSS selectors. When provided, only matching HTML subtrees (and their + * descendants) are kept before each crawled page is converted to Markdown. When + * omitted, the entire document is kept. Examples: "article.main", "#content", + * "[role=main]". */ - tags?: Array; + includeSelectors?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Return a cached result if a prior scrape for the same parameters exists and is + * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when + * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. */ - timeoutOpts?: WebWebScrapeScreenshotParams.TimeoutOpts; + maxAgeMs?: number; /** - * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. + * Maximum link depth from the starting URL (0 = only the starting page) */ - viewport?: WebWebScrapeScreenshotParams.Viewport; + maxDepth?: number; /** - * Optional browser wait time in milliseconds after initial page load before taking - * the screenshot. Min: 0. Max: 30000 (30 seconds). Defaults to 3000 ms when - * omitted. When combined with timeoutOpts, timeoutOpts.milliseconds must be at - * least waitForMs + 10000 ms; a shorter deadline is rejected with 400 - * TIMEOUT_TOO_SHORT_FOR_WAIT. + * Maximum number of pages to crawl. Hard cap: 500. */ - waitForMs?: number | null; + maxPages?: number; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * PDF parsing controls. Use start/end to limit text extraction and embedded-image + * detection/OCR to an inclusive 1-based page range. */ - zdr?: 'enabled' | 'disabled'; -} + pdf?: WebWebCrawlMdParams.Pdf; -export namespace WebWebScrapeScreenshotParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * When true, waits briefly for CSS and transition animations to settle before + * extracting each crawled page. Defaults to false. This adds a bit of latency in + * exchange for more stable output on animated pages. */ - export interface TimeoutOpts { - /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). - */ - milliseconds: number; - - /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. - */ - behavior?: 'fail' | 'return-partial'; - } + settleAnimations?: boolean; /** - * Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. + * Truncate base64-encoded image data in the Markdown output */ - export interface Viewport { - /** - * Viewport height in pixels. - */ - height?: number; - - /** - * Viewport width in pixels. - */ - width?: number; - } -} + shortenBase64Images?: boolean; -export interface WebWebScrapeSitemapParams { /** - * Domain to build a sitemap for + * Soft time budget for the crawl in milliseconds. After each scrape, the crawler + * checks the elapsed time and, if exceeded, returns the pages collected so far + * instead of continuing. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 + * (80s). */ - domain: string; + stopAfterMs?: number; /** - * Optional outbound HTTP headers forwarded only to the target URL, sent as - * deep-object query params such as headers[X-Custom]=value. When provided, caching - * is bypassed: the result is neither read from nor written to cache. + * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. */ - headers?: { [key: string]: string }; + tags?: Array; /** - * When true, discover and include public pages and sitemaps on subdomains of the - * requested domain. Defaults to false. + * Optional request deadline and behavior on timeout. For GET requests, use + * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded + * timeoutOpts object. */ - includeSubdomains?: boolean; + timeoutOpts?: WebWebCrawlMdParams.TimeoutOpts; /** - * Maximum number of links to return from the sitemap crawl. Defaults to 10,000. - * Minimum is 1, maximum is 100,000. + * Regex pattern. Only URLs matching this pattern will be followed and scraped. An + * automatic prefix scope in the form ^ follows a redirect of the + * starting page. */ - maxLinks?: number; + urlRegex?: string; /** - * Optional search phrase. When provided, the crawled sitemap is filtered to the - * pages whose URLs are about that phrase, most relevant first, and the request - * costs 2 credits instead of 1. + * Extract only the main content, stripping headers, footers, sidebars, and + * navigation */ - search?: string; + useMainContentOnly?: boolean; /** - * Optional explicit sitemap URL. When provided, exactly this sitemap is crawled - * instead of discovering the domain's sitemaps. + * Browser wait time in milliseconds after initial page load for each crawled page. + * Defaults to 3500 (3.5 seconds). Min: 0. Max: 30000 (30 seconds). */ - sitemapUrl?: string; + waitForMs?: number; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Set to enabled to bypass shared caches and omit request and response content + * from retained usage logs. Requires zero data retention to be enabled for your + * organization (contact support@context.dev), otherwise the request fails with + * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. */ - tags?: Array; + zdr?: 'enabled' | 'disabled'; +} +export namespace WebWebCrawlMdParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * PDF parsing controls. Use start/end to limit text extraction and embedded-image + * detection/OCR to an inclusive 1-based page range. */ - timeoutOpts?: WebWebScrapeSitemapParams.TimeoutOpts; + export interface Pdf { + /** + * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. + * Must be greater than or equal to start when both are provided. + */ + end?: number; - /** - * Optional RE2-compatible regex pattern. Only URLs matching this pattern are - * returned and counted against maxLinks. - */ - urlRegex?: string; + /** + * When true, OCR the selected PDF pages that have no usable text layer (scans), + * replacing each recovered page's text with the OCR result while pages with a real + * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top + * of the base request cost. + */ + ocr?: boolean; - /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. - */ - zdr?: 'enabled' | 'disabled'; -} + /** + * When true, PDF pages are fetched and parsed. When false, PDF pages are skipped + * entirely (not included in results and not counted as failures). + */ + shouldParse?: boolean; + + /** + * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + */ + start?: number; + } -export namespace WebWebScrapeSitemapParams { /** * Optional request deadline and behavior on timeout. For GET requests, use * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded @@ -7129,34 +3601,20 @@ export namespace WebWebScrapeSitemapParams { export declare namespace Web { export { type WebAnswersResponse as WebAnswersResponse, - type WebExtractResponse as WebExtractResponse, type WebExtractCompetitorsResponse as WebExtractCompetitorsResponse, - type WebExtractFontsResponse as WebExtractFontsResponse, type WebExtractStyleguideResponse as WebExtractStyleguideResponse, + type WebMapURLsResponse as WebMapURLsResponse, type WebScrapeResponse as WebScrapeResponse, type WebScreenshotResponse as WebScreenshotResponse, type WebSearchResponse as WebSearchResponse, type WebWebCrawlMdResponse as WebWebCrawlMdResponse, - type WebWebScrapeBytesResponse as WebWebScrapeBytesResponse, - type WebWebScrapeHTMLResponse as WebWebScrapeHTMLResponse, - type WebWebScrapeImagesResponse as WebWebScrapeImagesResponse, - type WebWebScrapeMdResponse as WebWebScrapeMdResponse, - type WebWebScrapeScreenshotResponse as WebWebScrapeScreenshotResponse, - type WebWebScrapeSitemapResponse as WebWebScrapeSitemapResponse, type WebAnswersParams as WebAnswersParams, - type WebExtractParams as WebExtractParams, type WebExtractCompetitorsParams as WebExtractCompetitorsParams, - type WebExtractFontsParams as WebExtractFontsParams, type WebExtractStyleguideParams as WebExtractStyleguideParams, + type WebMapURLsParams as WebMapURLsParams, type WebScrapeParams as WebScrapeParams, type WebScreenshotParams as WebScreenshotParams, type WebSearchParams as WebSearchParams, type WebWebCrawlMdParams as WebWebCrawlMdParams, - type WebWebScrapeBytesParams as WebWebScrapeBytesParams, - type WebWebScrapeHTMLParams as WebWebScrapeHTMLParams, - type WebWebScrapeImagesParams as WebWebScrapeImagesParams, - type WebWebScrapeMdParams as WebWebScrapeMdParams, - type WebWebScrapeScreenshotParams as WebWebScrapeScreenshotParams, - type WebWebScrapeSitemapParams as WebWebScrapeSitemapParams, }; } diff --git a/tests/api-resources/ai.test.ts b/tests/api-resources/ai.test.ts deleted file mode 100644 index dc2492b4..00000000 --- a/tests/api-resources/ai.test.ts +++ /dev/null @@ -1,56 +0,0 @@ -// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. - -import ContextDev from 'context.dev'; - -const client = new ContextDev({ - apiKey: 'My API Key', - baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', -}); - -describe('resource ai', () => { - // Mock server tests are disabled - test.skip('extractProduct: only required params', async () => { - const responsePromise = client.ai.extractProduct({ url: 'https://example.com' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('extractProduct: required and optional params', async () => { - const response = await client.ai.extractProduct({ - url: 'https://example.com', - maxAgeMs: 0, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, - zdr: 'enabled', - }); - }); - - // Mock server tests are disabled - test.skip('extractProducts: only required params', async () => { - const responsePromise = client.ai.extractProducts({ domain: 'domain' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('extractProducts: required and optional params', async () => { - const response = await client.ai.extractProducts({ - domain: 'domain', - maxAgeMs: 0, - maxProducts: 1, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, - }); - }); -}); diff --git a/tests/api-resources/brand.test.ts b/tests/api-resources/brand.test.ts index b92d3c70..f1c14028 100644 --- a/tests/api-resources/brand.test.ts +++ b/tests/api-resources/brand.test.ts @@ -33,29 +33,6 @@ describe('resource brand', () => { }); }); - // Mock server tests are disabled - test.skip('retrieveSimplified: only required params', async () => { - const responsePromise = client.brand.retrieveSimplified({ domain: 'xxx' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('retrieveSimplified: required and optional params', async () => { - const response = await client.brand.retrieveSimplified({ - domain: 'xxx', - maxAgeMs: 0, - tags: ['production', 'team-alpha'], - theme: 'light', - timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, - }); - }); - // Mock server tests are disabled test.skip('search: only required params', async () => { const responsePromise = client.brand.search({ query: 'x' }); diff --git a/tests/api-resources/monitors.test.ts b/tests/api-resources/monitors.test.ts index 11777b0d..d93ec765 100644 --- a/tests/api-resources/monitors.test.ts +++ b/tests/api-resources/monitors.test.ts @@ -286,6 +286,35 @@ describe('resource monitors', () => { expect(dataAndResponse.response).toBe(rawResponse); }); + // Mock server tests are disabled + test.skip('retrieveRun: only required params', async () => { + const responsePromise = client.monitors.retrieveRun('run_123', { monitor_id: 'mon_123' }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('retrieveRun: required and optional params', async () => { + const response = await client.monitors.retrieveRun('run_123', { monitor_id: 'mon_123' }); + }); + + // Mock server tests are disabled + test.skip('rotateWebhookSecret', async () => { + const responsePromise = client.monitors.rotateWebhookSecret('mon_123'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + // Mock server tests are disabled test.skip('run', async () => { const responsePromise = client.monitors.run('mon_123'); diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 6990f8bf..9d3ed311 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -34,58 +34,6 @@ describe('resource web', () => { }); }); - // Mock server tests are disabled - test.skip('extract: only required params', async () => { - const responsePromise = client.web.extract({ - schema: { - type: 'bar', - properties: 'bar', - required: 'bar', - additionalProperties: 'bar', - }, - url: 'https://example.com', - }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('extract: required and optional params', async () => { - const response = await client.web.extract({ - schema: { - type: 'bar', - properties: 'bar', - required: 'bar', - additionalProperties: 'bar', - }, - url: 'https://example.com', - actions: [{ do: 'wait', timeMs: 0 }], - factCheck: true, - followSubdomains: true, - includeFrames: true, - instructions: 'instructions', - maxAgeMs: 0, - maxDepth: 0, - maxPages: 1, - pdf: { - end: 1, - shouldParse: true, - start: 1, - }, - settleAnimations: true, - stopAfterMs: 10000, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, - waitForMs: 0, - zdr: 'enabled', - }); - }); - // Mock server tests are disabled test.skip('extractCompetitors: only required params', async () => { const responsePromise = client.web.extractCompetitors({ domain: 'xxx' }); @@ -110,8 +58,8 @@ describe('resource web', () => { }); // Mock server tests are disabled - test.skip('extractFonts', async () => { - const responsePromise = client.web.extractFonts(); + test.skip('extractStyleguide', async () => { + const responsePromise = client.web.extractStyleguide(); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -122,16 +70,18 @@ describe('resource web', () => { }); // Mock server tests are disabled - test.skip('extractFonts: request options and params are passed correctly', async () => { + test.skip('extractStyleguide: request options and params are passed correctly', async () => { // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error await expect( - client.web.extractFonts( + client.web.extractStyleguide( { + colorScheme: 'light', directUrl: 'https://example.com', domain: 'xxx', maxAgeMs: 0, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1, behavior: 'fail' }, + zdr: 'enabled', }, { path: '/_stainless_unknown_path' }, ), @@ -139,8 +89,8 @@ describe('resource web', () => { }); // Mock server tests are disabled - test.skip('extractStyleguide', async () => { - const responsePromise = client.web.extractStyleguide(); + test.skip('mapUrls: only required params', async () => { + const responsePromise = client.web.mapUrls({ domain: 'xxx' }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -151,22 +101,19 @@ describe('resource web', () => { }); // Mock server tests are disabled - test.skip('extractStyleguide: request options and params are passed correctly', async () => { - // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error - await expect( - client.web.extractStyleguide( - { - colorScheme: 'light', - directUrl: 'https://example.com', - domain: 'xxx', - maxAgeMs: 0, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1, behavior: 'fail' }, - zdr: 'enabled', - }, - { path: '/_stainless_unknown_path' }, - ), - ).rejects.toThrow(ContextDev.NotFoundError); + test.skip('mapUrls: required and optional params', async () => { + const response = await client.web.mapUrls({ + domain: 'xxx', + headers: { foo: 'J!' }, + includeSubdomains: true, + maxLinks: 1, + search: 'help center and troubleshooting articles', + sitemapUrl: 'https://example.com', + tags: ['production', 'team-alpha'], + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, + urlRegex: '^https?://[^/]+/blog/', + zdr: 'enabled', + }); }); // Mock server tests are disabled @@ -237,7 +184,7 @@ describe('resource web', () => { waitFor: 500, }, tags: ['production', 'team-alpha'], - timeoutMs: 1, + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, zdr: 'enabled', }); }); @@ -369,205 +316,4 @@ describe('resource web', () => { zdr: 'enabled', }); }); - - // Mock server tests are disabled - test.skip('webScrapeBytes: only required params', async () => { - const responsePromise = client.web.webScrapeBytes({ url: 'https://example.com' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('webScrapeBytes: required and optional params', async () => { - const response = await client.web.webScrapeBytes({ - url: 'https://example.com', - country: 'de', - headers: { foo: 'J!' }, - maxAgeMs: 0, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1, behavior: 'fail' }, - waitForMs: 0, - zdr: 'enabled', - }); - }); - - // Mock server tests are disabled - test.skip('webScrapeHTML: only required params', async () => { - const responsePromise = client.web.webScrapeHTML({ url: 'https://example.com' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('webScrapeHTML: required and optional params', async () => { - const response = await client.web.webScrapeHTML({ - url: 'https://example.com', - actions: [{ do: 'wait', timeMs: 0 }], - country: 'de', - excludeSelectors: ['x'], - extractRules: { foo: 'x' }, - headers: { foo: 'J!' }, - includeFrames: true, - includeSelectors: ['x'], - maxAgeMs: 0, - pdf: { - end: 1, - ocr: true, - shouldParse: true, - start: 1, - }, - settleAnimations: true, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1, behavior: 'fail' }, - useMainContentOnly: true, - waitForMs: 0, - zdr: 'enabled', - }); - }); - - // Mock server tests are disabled - test.skip('webScrapeImages: only required params', async () => { - const responsePromise = client.web.webScrapeImages({ url: 'https://example.com' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('webScrapeImages: required and optional params', async () => { - const response = await client.web.webScrapeImages({ - url: 'https://example.com', - actions: [{ do: 'wait', timeMs: 0 }], - country: 'de', - dedupe: true, - enrichment: { - classification: true, - hostedUrl: true, - maxTimePerMs: 1, - resolution: true, - }, - headers: { foo: 'J!' }, - maxAgeMs: 0, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1, behavior: 'fail' }, - waitForMs: 0, - zdr: 'enabled', - }); - }); - - // Mock server tests are disabled - test.skip('webScrapeMd: only required params', async () => { - const responsePromise = client.web.webScrapeMd({ url: 'https://example.com' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('webScrapeMd: required and optional params', async () => { - const response = await client.web.webScrapeMd({ - url: 'https://example.com', - actions: [{ do: 'wait', timeMs: 0 }], - country: 'de', - excludeSelectors: ['x'], - headers: { foo: 'J!' }, - includeFrames: true, - includeHTML: true, - includeImages: true, - includeLinks: true, - includeSelectors: ['x'], - maxAgeMs: 0, - pdf: { - end: 1, - ocr: true, - shouldParse: true, - start: 1, - }, - settleAnimations: true, - shortenBase64Images: true, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1, behavior: 'fail' }, - useMainContentOnly: true, - waitForMs: 0, - zdr: 'enabled', - }); - }); - - // Mock server tests are disabled - test.skip('webScrapeScreenshot: only required params', async () => { - const responsePromise = client.web.webScrapeScreenshot({ url: 'https://example.com' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('webScrapeScreenshot: required and optional params', async () => { - const response = await client.web.webScrapeScreenshot({ - url: 'https://example.com', - clearPopups: true, - colorScheme: 'light', - country: 'de', - fullScreenshot: 'true', - handleCookiePopup: true, - headers: { foo: 'J!' }, - maxAgeMs: 0, - scrollOffset: 0, - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1, behavior: 'fail' }, - viewport: { height: 240, width: 240 }, - waitForMs: 0, - zdr: 'enabled', - }); - }); - - // Mock server tests are disabled - test.skip('webScrapeSitemap: only required params', async () => { - const responsePromise = client.web.webScrapeSitemap({ domain: 'xxx' }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('webScrapeSitemap: required and optional params', async () => { - const response = await client.web.webScrapeSitemap({ - domain: 'xxx', - headers: { foo: 'J!' }, - includeSubdomains: true, - maxLinks: 1, - search: 'help center and troubleshooting articles', - sitemapUrl: 'https://example.com', - tags: ['production', 'team-alpha'], - timeoutOpts: { milliseconds: 1, behavior: 'fail' }, - urlRegex: '^https?://[^/]+/blog/', - zdr: 'enabled', - }); - }); }); From e4413f1561b309fe82b8e6649f12aba9128a4f84 Mon Sep 17 00:00:00 2001 From: contextualbeer Date: Tue, 22 Sep 2026 08:31:53 +0200 Subject: [PATCH 068/232] release: 2.20.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 18 ++++++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 21 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 89652a35..da2177c6 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.19.0" + ".": "2.20.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index b4aea89b..ec426104 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,23 @@ # Changelog +## [2.20.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.19.0...v2.20.0) (2026-09-22) + + +### Features + +* **billing:** charge for 404s and skip fraud accounting ([#1152](https://github.com/context-dot-dev/context-typescript-sdk/issues/1152)) ([b0a4aa5](https://github.com/context-dot-dev/context-typescript-sdk/commit/b0a4aa52533b83f905218d84976494c1dd931d1e)) +* **scrape:** add cache age support to byte downloads ([#1171](https://github.com/context-dot-dev/context-typescript-sdk/issues/1171)) ([477940d](https://github.com/context-dot-dev/context-typescript-sdk/commit/477940dccfff3cf4b2265d56dc7b15c95d232c1a)) +* **scrape:** add unified scrape API ([#1182](https://github.com/context-dot-dev/context-typescript-sdk/issues/1182)) ([3c92f39](https://github.com/context-dot-dev/context-typescript-sdk/commit/3c92f39ccd9d60820af5874e866fcc8058a9f2d5)) +* **scrape:** align timeout options and public SDK methods ([#1207](https://github.com/context-dot-dev/context-typescript-sdk/issues/1207)) ([bb950e7](https://github.com/context-dot-dev/context-typescript-sdk/commit/bb950e714a482b50d540a8abceea92fddf3e6678)) +* **scrape:** support country for image scraping ([#1172](https://github.com/context-dot-dev/context-typescript-sdk/issues/1172)) ([477940d](https://github.com/context-dot-dev/context-typescript-sdk/commit/477940dccfff3cf4b2265d56dc7b15c95d232c1a)) +* **scrape:** support custom screenshot headers ([#1169](https://github.com/context-dot-dev/context-typescript-sdk/issues/1169)) ([bacbc64](https://github.com/context-dot-dev/context-typescript-sdk/commit/bacbc64bb21b56f6c87926729af62731e1cd3e84)) +* **scrape:** support waitForMs for byte downloads ([#1170](https://github.com/context-dot-dev/context-typescript-sdk/issues/1170)) ([47c18a0](https://github.com/context-dot-dev/context-typescript-sdk/commit/47c18a0b11c00a6f697abb99a2e79795736d3143)) + + +### Bug Fixes + +* **scrape:** reuse legacy caches across all output formats ([#1197](https://github.com/context-dot-dev/context-typescript-sdk/issues/1197)) ([57dd03d](https://github.com/context-dot-dev/context-typescript-sdk/commit/57dd03dd18f93840faf239efdaeeca8a8f6fbaec)) + ## [2.19.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.18.1...v2.19.0) (2026-09-18) diff --git a/package.json b/package.json index 062de50a..f8342404 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.19.0", + "version": "2.20.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 3f68f782..d663bb64 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.19.0'; // x-release-please-version +export const VERSION = '2.20.0'; // x-release-please-version From 5b828a6468fc556354e87bfc082970feab23e6bc Mon Sep 17 00:00:00 2001 From: Yahia Bakour Date: Mon, 21 Sep 2026 23:42:01 -0700 Subject: [PATCH 069/232] ci(release): align v3.0.0 metadata and validate release titles The release PR title changed to 3.0.0 while the package metadata remained at 2.20.0. Align the version files and reject release PR title mismatches, including title edits. --- .github/workflows/release-doctor.yml | 8 ++++++++ .release-please-manifest.json | 2 +- CHANGELOG.md | 2 +- package.json | 2 +- src/version.ts | 2 +- 5 files changed, 12 insertions(+), 4 deletions(-) diff --git a/.github/workflows/release-doctor.yml b/.github/workflows/release-doctor.yml index 136b751a..d316b536 100644 --- a/.github/workflows/release-doctor.yml +++ b/.github/workflows/release-doctor.yml @@ -1,6 +1,7 @@ name: Release Doctor on: pull_request: + types: [opened, synchronize, reopened, edited] branches: - main workflow_dispatch: @@ -14,6 +15,13 @@ jobs: steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - name: Verify release title matches package version + if: startsWith(github.head_ref, 'release-please') + env: + RELEASE_TITLE: ${{ github.event.pull_request.title }} + run: | + test "$RELEASE_TITLE" = "release: $(node -p 'require("./package.json").version')" + - name: Check release environment run: | bash ./bin/check-release-environment diff --git a/.release-please-manifest.json b/.release-please-manifest.json index da2177c6..d4f6f299 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.20.0" + ".": "3.0.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index ec426104..05cfd359 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## [2.20.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.19.0...v2.20.0) (2026-09-22) +## [3.0.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.19.0...v3.0.0) (2026-09-22) ### Features diff --git a/package.json b/package.json index f8342404..c05e43db 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.20.0", + "version": "3.0.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index d663bb64..bccd5c23 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.20.0'; // x-release-please-version +export const VERSION = '3.0.0'; // x-release-please-version From 29a01defe68bb7cdb23e94487a2e3674308fe3de Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 22 Sep 2026 09:14:50 +0000 Subject: [PATCH 070/232] seal --- .github/workflows/release-doctor.yml | 8 ++++++++ .release-please-manifest.json | 2 +- CHANGELOG.md | 18 ++++++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 5 files changed, 29 insertions(+), 3 deletions(-) diff --git a/.github/workflows/release-doctor.yml b/.github/workflows/release-doctor.yml index 136b751a..d316b536 100644 --- a/.github/workflows/release-doctor.yml +++ b/.github/workflows/release-doctor.yml @@ -1,6 +1,7 @@ name: Release Doctor on: pull_request: + types: [opened, synchronize, reopened, edited] branches: - main workflow_dispatch: @@ -14,6 +15,13 @@ jobs: steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - name: Verify release title matches package version + if: startsWith(github.head_ref, 'release-please') + env: + RELEASE_TITLE: ${{ github.event.pull_request.title }} + run: | + test "$RELEASE_TITLE" = "release: $(node -p 'require("./package.json").version')" + - name: Check release environment run: | bash ./bin/check-release-environment diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 89652a35..d4f6f299 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.19.0" + ".": "3.0.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index b4aea89b..05cfd359 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,23 @@ # Changelog +## [3.0.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.19.0...v3.0.0) (2026-09-22) + + +### Features + +* **billing:** charge for 404s and skip fraud accounting ([#1152](https://github.com/context-dot-dev/context-typescript-sdk/issues/1152)) ([b0a4aa5](https://github.com/context-dot-dev/context-typescript-sdk/commit/b0a4aa52533b83f905218d84976494c1dd931d1e)) +* **scrape:** add cache age support to byte downloads ([#1171](https://github.com/context-dot-dev/context-typescript-sdk/issues/1171)) ([477940d](https://github.com/context-dot-dev/context-typescript-sdk/commit/477940dccfff3cf4b2265d56dc7b15c95d232c1a)) +* **scrape:** add unified scrape API ([#1182](https://github.com/context-dot-dev/context-typescript-sdk/issues/1182)) ([3c92f39](https://github.com/context-dot-dev/context-typescript-sdk/commit/3c92f39ccd9d60820af5874e866fcc8058a9f2d5)) +* **scrape:** align timeout options and public SDK methods ([#1207](https://github.com/context-dot-dev/context-typescript-sdk/issues/1207)) ([bb950e7](https://github.com/context-dot-dev/context-typescript-sdk/commit/bb950e714a482b50d540a8abceea92fddf3e6678)) +* **scrape:** support country for image scraping ([#1172](https://github.com/context-dot-dev/context-typescript-sdk/issues/1172)) ([477940d](https://github.com/context-dot-dev/context-typescript-sdk/commit/477940dccfff3cf4b2265d56dc7b15c95d232c1a)) +* **scrape:** support custom screenshot headers ([#1169](https://github.com/context-dot-dev/context-typescript-sdk/issues/1169)) ([bacbc64](https://github.com/context-dot-dev/context-typescript-sdk/commit/bacbc64bb21b56f6c87926729af62731e1cd3e84)) +* **scrape:** support waitForMs for byte downloads ([#1170](https://github.com/context-dot-dev/context-typescript-sdk/issues/1170)) ([47c18a0](https://github.com/context-dot-dev/context-typescript-sdk/commit/47c18a0b11c00a6f697abb99a2e79795736d3143)) + + +### Bug Fixes + +* **scrape:** reuse legacy caches across all output formats ([#1197](https://github.com/context-dot-dev/context-typescript-sdk/issues/1197)) ([57dd03d](https://github.com/context-dot-dev/context-typescript-sdk/commit/57dd03dd18f93840faf239efdaeeca8a8f6fbaec)) + ## [2.19.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.18.1...v2.19.0) (2026-09-18) diff --git a/package.json b/package.json index 062de50a..c05e43db 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.19.0", + "version": "3.0.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 3f68f782..bccd5c23 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.19.0'; // x-release-please-version +export const VERSION = '3.0.0'; // x-release-please-version From 7f966761a10434baa0a66aceb24725d227f71b16 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 23 Sep 2026 05:14:14 +0000 Subject: [PATCH 071/232] feat(scrape): add json output format to POST /web/scrape (#1213) Stainless-Generated-From: 8030e3da7fcaf50a299e6d5f53dbf23fb4cc94ac --- src/resources/web.ts | 63 ++++++++++++++++++++++++++++++--- tests/api-resources/web.test.ts | 10 ++++++ 2 files changed, 69 insertions(+), 4 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 227beb57..4d3d1e13 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -86,10 +86,12 @@ export class Web extends APIResource { /** * Reuse cached outputs independently and capture missing formats in one page * visit. Each cache key includes only the settings that affect that output. HTML - * is shared with Markdown and parsed fields. Cached outputs can come from - * different visits within maxAgeMs; use 0 for a fresh capture. HTML-only requests - * use the existing fast acquisition path. One credit per request, including cache - * hits, or two with browser actions; PDF OCR adds one credit per recovered page on + * is shared with Markdown, parsed fields, and JSON extraction. Cached outputs can + * come from different visits within maxAgeMs; use 0 for a fresh capture. HTML-only + * requests use the existing fast acquisition path. One credit per request, + * including cache hits and missing pages, or two with browser actions; JSON + * extraction adds four credits and runs an LLM over the page Markdown on every + * request that has text to extract; PDF OCR adds one credit per recovered page on * fresh extraction. Original response bytes and screenshots are limited to 20 MiB * each, screenshots to 40 megapixels, and the combined browser capture to 60 MiB. * @@ -949,6 +951,14 @@ export interface WebScrapeResponse { */ images: WebScrapeResponse.Images; + /** + * Page data extracted into jsonParams.schema, after shared content filters. Values + * are grounded in the page; optional fields the page does not state are omitted, + * or null when their type allows null. An empty object when the filters leave no + * text. + */ + json: WebScrapeResponse.Json; + /** * Markdown after content filters. */ @@ -1085,6 +1095,18 @@ export namespace WebScrapeResponse { } } + /** + * Page data extracted into jsonParams.schema, after shared content filters. Values + * are grounded in the page; optional fields the page does not state are omitted, + * or null when their type allows null. An empty object when the filters leave no + * text. + */ + export interface Json { + data: { [key: string]: unknown } | null; + + requested: boolean; + } + /** * Markdown after content filters. */ @@ -2054,6 +2076,11 @@ export interface WebScrapeParams { */ imageParams?: WebScrapeParams.ImageParams; + /** + * Required when formats.json is true. + */ + jsonParams?: WebScrapeParams.JsonParams; + /** * Markdown options. Requires formats.markdown: true. */ @@ -2126,6 +2153,14 @@ export namespace WebScrapeParams { */ images?: boolean; + /** + * Page data extracted by an LLM from the page Markdown into jsonParams.schema; + * values carried only in attributes or CSS classes need formats.parse instead. + * Adds four credits when the page has text to extract; when shared content filters + * leave no text the result is an empty object and only the base price applies. + */ + json?: boolean; + /** * Page content as Markdown. */ @@ -2159,6 +2194,26 @@ export namespace WebScrapeParams { enrich?: Array<'dimensions' | 'classification' | 'file'>; } + /** + * Required when formats.json is true. + */ + export interface JsonParams { + /** + * JSON Schema for the returned object. Must describe a top-level object; at most + * 50 KB serialized. Optional fields the page does not state are omitted, or null + * when their type allows null, while required non-nullable fields always receive a + * best-effort value, so prefer nullable or optional fields for data a page may + * omit. Zod users can pass the output of z.toJSONSchema(). + */ + schema: { [key: string]: unknown }; + + /** + * Optional guidance on which facts to prioritize or how to interpret schema + * fields. + */ + instructions?: string; + } + /** * Markdown options. Requires formats.markdown: true. */ diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 9d3ed311..5d169020 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -138,12 +138,22 @@ describe('resource web', () => { bytes: true, html: true, images: true, + json: true, markdown: true, parse: true, screenshot: true, }, url: 'https://example.com', imageParams: { dedupe: 'none', enrich: ['dimensions'] }, + jsonParams: { + schema: { + type: 'bar', + properties: 'bar', + required: 'bar', + additionalProperties: 'bar', + }, + instructions: 'instructions', + }, markdownParams: { includeImages: true, includeLinks: true, From 8030e3da7fcaf50a299e6d5f53dbf23fb4cc94ac Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 23 Sep 2026 05:14:14 +0000 Subject: [PATCH 072/232] seal --- src/resources/web.ts | 63 ++++++++++++++++++++++++++++++--- tests/api-resources/web.test.ts | 10 ++++++ 2 files changed, 69 insertions(+), 4 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 227beb57..4d3d1e13 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -86,10 +86,12 @@ export class Web extends APIResource { /** * Reuse cached outputs independently and capture missing formats in one page * visit. Each cache key includes only the settings that affect that output. HTML - * is shared with Markdown and parsed fields. Cached outputs can come from - * different visits within maxAgeMs; use 0 for a fresh capture. HTML-only requests - * use the existing fast acquisition path. One credit per request, including cache - * hits, or two with browser actions; PDF OCR adds one credit per recovered page on + * is shared with Markdown, parsed fields, and JSON extraction. Cached outputs can + * come from different visits within maxAgeMs; use 0 for a fresh capture. HTML-only + * requests use the existing fast acquisition path. One credit per request, + * including cache hits and missing pages, or two with browser actions; JSON + * extraction adds four credits and runs an LLM over the page Markdown on every + * request that has text to extract; PDF OCR adds one credit per recovered page on * fresh extraction. Original response bytes and screenshots are limited to 20 MiB * each, screenshots to 40 megapixels, and the combined browser capture to 60 MiB. * @@ -949,6 +951,14 @@ export interface WebScrapeResponse { */ images: WebScrapeResponse.Images; + /** + * Page data extracted into jsonParams.schema, after shared content filters. Values + * are grounded in the page; optional fields the page does not state are omitted, + * or null when their type allows null. An empty object when the filters leave no + * text. + */ + json: WebScrapeResponse.Json; + /** * Markdown after content filters. */ @@ -1085,6 +1095,18 @@ export namespace WebScrapeResponse { } } + /** + * Page data extracted into jsonParams.schema, after shared content filters. Values + * are grounded in the page; optional fields the page does not state are omitted, + * or null when their type allows null. An empty object when the filters leave no + * text. + */ + export interface Json { + data: { [key: string]: unknown } | null; + + requested: boolean; + } + /** * Markdown after content filters. */ @@ -2054,6 +2076,11 @@ export interface WebScrapeParams { */ imageParams?: WebScrapeParams.ImageParams; + /** + * Required when formats.json is true. + */ + jsonParams?: WebScrapeParams.JsonParams; + /** * Markdown options. Requires formats.markdown: true. */ @@ -2126,6 +2153,14 @@ export namespace WebScrapeParams { */ images?: boolean; + /** + * Page data extracted by an LLM from the page Markdown into jsonParams.schema; + * values carried only in attributes or CSS classes need formats.parse instead. + * Adds four credits when the page has text to extract; when shared content filters + * leave no text the result is an empty object and only the base price applies. + */ + json?: boolean; + /** * Page content as Markdown. */ @@ -2159,6 +2194,26 @@ export namespace WebScrapeParams { enrich?: Array<'dimensions' | 'classification' | 'file'>; } + /** + * Required when formats.json is true. + */ + export interface JsonParams { + /** + * JSON Schema for the returned object. Must describe a top-level object; at most + * 50 KB serialized. Optional fields the page does not state are omitted, or null + * when their type allows null, while required non-nullable fields always receive a + * best-effort value, so prefer nullable or optional fields for data a page may + * omit. Zod users can pass the output of z.toJSONSchema(). + */ + schema: { [key: string]: unknown }; + + /** + * Optional guidance on which facts to prioritize or how to interpret schema + * fields. + */ + instructions?: string; + } + /** * Markdown options. Requires formats.markdown: true. */ diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 9d3ed311..5d169020 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -138,12 +138,22 @@ describe('resource web', () => { bytes: true, html: true, images: true, + json: true, markdown: true, parse: true, screenshot: true, }, url: 'https://example.com', imageParams: { dedupe: 'none', enrich: ['dimensions'] }, + jsonParams: { + schema: { + type: 'bar', + properties: 'bar', + required: 'bar', + additionalProperties: 'bar', + }, + instructions: 'instructions', + }, markdownParams: { includeImages: true, includeLinks: true, From 9a81729963bc7af20ab82498143b593f070adaeb Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 23 Sep 2026 06:28:15 +0000 Subject: [PATCH 073/232] feat(scrape): add highlights format to POST /web/scrape (#1210) Stainless-Generated-From: 50165be51e4551995d162f692e0411df24d8f38d --- src/resources/web.ts | 66 ++++++++++++++++++++++++++++----- tests/api-resources/web.test.ts | 2 + 2 files changed, 59 insertions(+), 9 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 4d3d1e13..d9366680 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -86,14 +86,16 @@ export class Web extends APIResource { /** * Reuse cached outputs independently and capture missing formats in one page * visit. Each cache key includes only the settings that affect that output. HTML - * is shared with Markdown, parsed fields, and JSON extraction. Cached outputs can - * come from different visits within maxAgeMs; use 0 for a fresh capture. HTML-only - * requests use the existing fast acquisition path. One credit per request, - * including cache hits and missing pages, or two with browser actions; JSON - * extraction adds four credits and runs an LLM over the page Markdown on every - * request that has text to extract; PDF OCR adds one credit per recovered page on - * fresh extraction. Original response bytes and screenshots are limited to 20 MiB - * each, screenshots to 40 megapixels, and the combined browser capture to 60 MiB. + * is shared with Markdown, parsed fields, highlights, and JSON extraction. Cached + * outputs can come from different visits within maxAgeMs; use 0 for a fresh + * capture. HTML-only requests use the existing fast acquisition path. Highlights + * return the plain-text passages most relevant to highlightsParams.query. One + * credit per request, including cache hits and missing pages, or two with browser + * actions; highlights add 3 credits when passages are returned; JSON extraction + * adds four credits and runs an LLM over the page Markdown on every request that + * has text to extract; PDF OCR adds one credit per recovered page on fresh + * extraction. Original response bytes and screenshots are limited to 20 MiB each, + * screenshots to 40 megapixels, and the combined browser capture to 60 MiB. * * @example * ```ts @@ -941,6 +943,13 @@ export interface WebScrapeResponse { */ cache_metadata: WebScrapeResponse.CacheMetadata; + /** + * Plain-text passages relevant to highlightsParams.query, in page order, each + * prefixed with its section heading in square brackets. Empty when the page has no + * text. + */ + highlights: WebScrapeResponse.Highlights; + /** * Rendered HTML after content filters. */ @@ -1043,6 +1052,17 @@ export namespace WebScrapeResponse { status: 'hit' | 'miss' | 'zdr'; } + /** + * Plain-text passages relevant to highlightsParams.query, in page order, each + * prefixed with its section heading in square brackets. Empty when the page has no + * text. + */ + export interface Highlights { + data: Array | null; + + requested: boolean; + } + /** * Rendered HTML after content filters. */ @@ -2071,6 +2091,11 @@ export interface WebScrapeParams { */ url: string; + /** + * Highlight options. Requires formats.highlights: true. + */ + highlightsParams?: WebScrapeParams.HighlightsParams; + /** * Image options. Requires formats.images: true. */ @@ -2128,7 +2153,8 @@ export interface WebScrapeParams { /** * Zero data retention. Bypasses caches and uploads; excludes request/response - * content and tags from logs. Must be enabled for your organization. + * content and tags from logs. Must be enabled for your organization. Not available + * with the highlights output. */ zdr?: 'enabled' | 'disabled'; } @@ -2143,6 +2169,13 @@ export namespace WebScrapeParams { */ bytes?: boolean; + /** + * Plain-text passages from the page that are most relevant to + * highlightsParams.query, each prefixed with its section heading. Adds 3 credits. + * Not available with zdr enabled. + */ + highlights?: boolean; + /** * Rendered HTML. */ @@ -2177,6 +2210,21 @@ export namespace WebScrapeParams { screenshot?: boolean; } + /** + * Highlight options. Requires formats.highlights: true. + */ + export interface HighlightsParams { + /** + * The question or topic to find passages for. + */ + query: string; + + /** + * Maximum combined length of the returned passages, in characters. + */ + maxCharacters?: number; + } + /** * Image options. Requires formats.images: true. */ diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 5d169020..a24d36d7 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -136,6 +136,7 @@ describe('resource web', () => { const response = await client.web.scrape({ formats: { bytes: true, + highlights: true, html: true, images: true, json: true, @@ -144,6 +145,7 @@ describe('resource web', () => { screenshot: true, }, url: 'https://example.com', + highlightsParams: { query: 'x', maxCharacters: 100 }, imageParams: { dedupe: 'none', enrich: ['dimensions'] }, jsonParams: { schema: { From 50165be51e4551995d162f692e0411df24d8f38d Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 23 Sep 2026 06:28:15 +0000 Subject: [PATCH 074/232] seal --- src/resources/web.ts | 66 ++++++++++++++++++++++++++++----- tests/api-resources/web.test.ts | 2 + 2 files changed, 59 insertions(+), 9 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 4d3d1e13..d9366680 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -86,14 +86,16 @@ export class Web extends APIResource { /** * Reuse cached outputs independently and capture missing formats in one page * visit. Each cache key includes only the settings that affect that output. HTML - * is shared with Markdown, parsed fields, and JSON extraction. Cached outputs can - * come from different visits within maxAgeMs; use 0 for a fresh capture. HTML-only - * requests use the existing fast acquisition path. One credit per request, - * including cache hits and missing pages, or two with browser actions; JSON - * extraction adds four credits and runs an LLM over the page Markdown on every - * request that has text to extract; PDF OCR adds one credit per recovered page on - * fresh extraction. Original response bytes and screenshots are limited to 20 MiB - * each, screenshots to 40 megapixels, and the combined browser capture to 60 MiB. + * is shared with Markdown, parsed fields, highlights, and JSON extraction. Cached + * outputs can come from different visits within maxAgeMs; use 0 for a fresh + * capture. HTML-only requests use the existing fast acquisition path. Highlights + * return the plain-text passages most relevant to highlightsParams.query. One + * credit per request, including cache hits and missing pages, or two with browser + * actions; highlights add 3 credits when passages are returned; JSON extraction + * adds four credits and runs an LLM over the page Markdown on every request that + * has text to extract; PDF OCR adds one credit per recovered page on fresh + * extraction. Original response bytes and screenshots are limited to 20 MiB each, + * screenshots to 40 megapixels, and the combined browser capture to 60 MiB. * * @example * ```ts @@ -941,6 +943,13 @@ export interface WebScrapeResponse { */ cache_metadata: WebScrapeResponse.CacheMetadata; + /** + * Plain-text passages relevant to highlightsParams.query, in page order, each + * prefixed with its section heading in square brackets. Empty when the page has no + * text. + */ + highlights: WebScrapeResponse.Highlights; + /** * Rendered HTML after content filters. */ @@ -1043,6 +1052,17 @@ export namespace WebScrapeResponse { status: 'hit' | 'miss' | 'zdr'; } + /** + * Plain-text passages relevant to highlightsParams.query, in page order, each + * prefixed with its section heading in square brackets. Empty when the page has no + * text. + */ + export interface Highlights { + data: Array | null; + + requested: boolean; + } + /** * Rendered HTML after content filters. */ @@ -2071,6 +2091,11 @@ export interface WebScrapeParams { */ url: string; + /** + * Highlight options. Requires formats.highlights: true. + */ + highlightsParams?: WebScrapeParams.HighlightsParams; + /** * Image options. Requires formats.images: true. */ @@ -2128,7 +2153,8 @@ export interface WebScrapeParams { /** * Zero data retention. Bypasses caches and uploads; excludes request/response - * content and tags from logs. Must be enabled for your organization. + * content and tags from logs. Must be enabled for your organization. Not available + * with the highlights output. */ zdr?: 'enabled' | 'disabled'; } @@ -2143,6 +2169,13 @@ export namespace WebScrapeParams { */ bytes?: boolean; + /** + * Plain-text passages from the page that are most relevant to + * highlightsParams.query, each prefixed with its section heading. Adds 3 credits. + * Not available with zdr enabled. + */ + highlights?: boolean; + /** * Rendered HTML. */ @@ -2177,6 +2210,21 @@ export namespace WebScrapeParams { screenshot?: boolean; } + /** + * Highlight options. Requires formats.highlights: true. + */ + export interface HighlightsParams { + /** + * The question or topic to find passages for. + */ + query: string; + + /** + * Maximum combined length of the returned passages, in characters. + */ + maxCharacters?: number; + } + /** * Image options. Requires formats.images: true. */ diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 5d169020..a24d36d7 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -136,6 +136,7 @@ describe('resource web', () => { const response = await client.web.scrape({ formats: { bytes: true, + highlights: true, html: true, images: true, json: true, @@ -144,6 +145,7 @@ describe('resource web', () => { screenshot: true, }, url: 'https://example.com', + highlightsParams: { query: 'x', maxCharacters: 100 }, imageParams: { dedupe: 'none', enrich: ['dimensions'] }, jsonParams: { schema: { From 21edbde24214379f9a20b11366b3e298ff4df407 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 23 Sep 2026 07:32:32 +0000 Subject: [PATCH 075/232] feat(scrape): add product extraction format to POST /web/scrape (#1212) Stainless-Generated-From: e801ba5a6ae78b72b8a4ce163aff70bac178c463 --- src/resources/web.ts | 198 ++++++++++++++++++++++++++++++-- tests/api-resources/web.test.ts | 2 + 2 files changed, 188 insertions(+), 12 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index d9366680..868732d4 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -86,16 +86,18 @@ export class Web extends APIResource { /** * Reuse cached outputs independently and capture missing formats in one page * visit. Each cache key includes only the settings that affect that output. HTML - * is shared with Markdown, parsed fields, highlights, and JSON extraction. Cached - * outputs can come from different visits within maxAgeMs; use 0 for a fresh - * capture. HTML-only requests use the existing fast acquisition path. Highlights - * return the plain-text passages most relevant to highlightsParams.query. One - * credit per request, including cache hits and missing pages, or two with browser - * actions; highlights add 3 credits when passages are returned; JSON extraction - * adds four credits and runs an LLM over the page Markdown on every request that - * has text to extract; PDF OCR adds one credit per recovered page on fresh - * extraction. Original response bytes and screenshots are limited to 20 MiB each, - * screenshots to 40 megapixels, and the combined browser capture to 60 MiB. + * is shared with Markdown, parsed fields, product data, highlights, and JSON + * extraction. Cached outputs can come from different visits within maxAgeMs; use 0 + * for a fresh capture. HTML-only requests use the existing fast acquisition path. + * Highlights return the plain-text passages most relevant to + * highlightsParams.query. One credit per request, including cache hits and missing + * pages, or two with browser actions; highlights add 3 credits when passages are + * returned; JSON extraction adds four credits and runs an LLM over the page + * Markdown on every request that has text to extract; PDF OCR adds one credit per + * recovered page on fresh extraction; the product output adds one credit, plus six + * more when the specialized model is used. Original response bytes and screenshots + * are limited to 20 MiB each, screenshots to 40 megapixels, and the combined + * browser capture to 60 MiB. * * @example * ```ts @@ -983,6 +985,11 @@ export interface WebScrapeResponse { */ parsed: WebScrapeResponse.Parsed; + /** + * Product detail page classification and the extracted product. + */ + product: WebScrapeResponse.Product; + /** * Unique id of this API call, also sent in the X-Request-Id response header. Quote * it when contacting support about a failed request. @@ -1000,8 +1007,10 @@ export interface WebScrapeResponse { url: string; /** - * Present when return-partial captures a page that is still loading or returns - * images before image processing finishes. Partial responses are not cached. + * Present when return-partial captures a page that is still loading, returns + * images before image processing finishes, or cuts product AI extraction short. + * Also present if the optional product AI fallback fails. Partial responses are + * not cached. */ isPartial?: true; @@ -1277,6 +1286,148 @@ export namespace WebScrapeResponse { requested: boolean; } + /** + * Product detail page classification and the extracted product. + */ + export interface Product { + data: Product.Data | null; + + requested: boolean; + } + + export namespace Product { + export interface Data { + /** + * Whether the page is a product detail page. + */ + isProductPage: boolean; + + /** + * The extracted product, or null when the page is not a product detail page. + */ + product: Data.Product | null; + } + + export namespace Data { + /** + * The extracted product, or null when the page is not a product detail page. + */ + export interface Product { + /** + * Stock or ordering availability. + */ + availability: + | 'in_stock' + | 'out_of_stock' + | 'limited_availability' + | 'preorder' + | 'backorder' + | 'made_to_order' + | 'discontinued' + | null; + + /** + * Brand or vendor. + */ + brand: string | null; + + /** + * Product category. + */ + category: string | null; + + /** + * ISO 4217 currency code. + */ + currency: string | null; + + /** + * Product description. + */ + description: string | null; + + /** + * Product dimensions as shown on the page. + */ + dimensions: Array; + + /** + * Key features and specifications. + */ + features: Array; + + /** + * Product image URLs, main image first. + */ + images: Array; + + /** + * Main product image URL. + */ + imageUrl: string | null; + + /** + * Product name. + */ + name: string; + + /** + * Current price. + */ + price: number | null; + + /** + * List price before any discount. + */ + regularPrice: number | null; + + /** + * Product identifier such as a SKU or model number. + */ + sku: string | null; + + /** + * Product tags. + */ + tags: Array; + + /** + * Intended audience. + */ + targetAudience: Array; + + /** + * Product variations, such as different colors or sizes, with their attributes and + * images. Empty if none are found. May not include every variation offered by the + * store. + */ + variants: Array; + } + + export namespace Product { + export interface Variant { + /** + * Explicit variant attributes such as color, size, material, pattern and + * properties declared by page. + */ + attributes: { [key: string]: string }; + + /** + * Original source image URLs explicitly attached to this variant. + */ + images: Array; + + sku: string | null; + + /** + * Variant or offer URL when provided by the source. May be shared by variants. + */ + url: string | null; + } + } + } + } + /** * An image data URL. Use directly as an image src. */ @@ -2124,6 +2275,11 @@ export interface WebScrapeParams { */ parseParams?: WebScrapeParams.ParseParams; + /** + * Product options. Requires formats.product: true. + */ + productParams?: WebScrapeParams.ProductParams; + /** * Screenshot options. Requires formats.screenshot: true. */ @@ -2204,6 +2360,11 @@ export namespace WebScrapeParams { */ parse?: boolean; + /** + * Structured product data for product detail pages. Adds one credit. + */ + product?: boolean; + /** * An inline image of the page. */ @@ -2297,6 +2458,19 @@ export namespace WebScrapeParams { } } + /** + * Product options. Requires formats.product: true. + */ + export interface ProductParams { + /** + * Extract the product with a specialized model when the page has no structured + * product data. Adds six credits when the model returns a verdict. If the fallback + * fails, returns a partial response with the deterministic result and no fallback + * charge. Request deadlines and client disconnects still apply. + */ + useAIFallback?: boolean; + } + /** * Screenshot options. Requires formats.screenshot: true. */ diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index a24d36d7..9e58d141 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -142,6 +142,7 @@ describe('resource web', () => { json: true, markdown: true, parse: true, + product: true, screenshot: true, }, url: 'https://example.com', @@ -172,6 +173,7 @@ describe('resource web', () => { }, }, }, + productParams: { useAIFallback: true }, screenshotParams: { area: 'viewport', format: 'png' }, sharedParams: { actions: [{ action: 'Click the product details tab', type: 'perform' }], From e801ba5a6ae78b72b8a4ce163aff70bac178c463 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 23 Sep 2026 07:32:32 +0000 Subject: [PATCH 076/232] seal --- src/resources/web.ts | 198 ++++++++++++++++++++++++++++++-- tests/api-resources/web.test.ts | 2 + 2 files changed, 188 insertions(+), 12 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index d9366680..868732d4 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -86,16 +86,18 @@ export class Web extends APIResource { /** * Reuse cached outputs independently and capture missing formats in one page * visit. Each cache key includes only the settings that affect that output. HTML - * is shared with Markdown, parsed fields, highlights, and JSON extraction. Cached - * outputs can come from different visits within maxAgeMs; use 0 for a fresh - * capture. HTML-only requests use the existing fast acquisition path. Highlights - * return the plain-text passages most relevant to highlightsParams.query. One - * credit per request, including cache hits and missing pages, or two with browser - * actions; highlights add 3 credits when passages are returned; JSON extraction - * adds four credits and runs an LLM over the page Markdown on every request that - * has text to extract; PDF OCR adds one credit per recovered page on fresh - * extraction. Original response bytes and screenshots are limited to 20 MiB each, - * screenshots to 40 megapixels, and the combined browser capture to 60 MiB. + * is shared with Markdown, parsed fields, product data, highlights, and JSON + * extraction. Cached outputs can come from different visits within maxAgeMs; use 0 + * for a fresh capture. HTML-only requests use the existing fast acquisition path. + * Highlights return the plain-text passages most relevant to + * highlightsParams.query. One credit per request, including cache hits and missing + * pages, or two with browser actions; highlights add 3 credits when passages are + * returned; JSON extraction adds four credits and runs an LLM over the page + * Markdown on every request that has text to extract; PDF OCR adds one credit per + * recovered page on fresh extraction; the product output adds one credit, plus six + * more when the specialized model is used. Original response bytes and screenshots + * are limited to 20 MiB each, screenshots to 40 megapixels, and the combined + * browser capture to 60 MiB. * * @example * ```ts @@ -983,6 +985,11 @@ export interface WebScrapeResponse { */ parsed: WebScrapeResponse.Parsed; + /** + * Product detail page classification and the extracted product. + */ + product: WebScrapeResponse.Product; + /** * Unique id of this API call, also sent in the X-Request-Id response header. Quote * it when contacting support about a failed request. @@ -1000,8 +1007,10 @@ export interface WebScrapeResponse { url: string; /** - * Present when return-partial captures a page that is still loading or returns - * images before image processing finishes. Partial responses are not cached. + * Present when return-partial captures a page that is still loading, returns + * images before image processing finishes, or cuts product AI extraction short. + * Also present if the optional product AI fallback fails. Partial responses are + * not cached. */ isPartial?: true; @@ -1277,6 +1286,148 @@ export namespace WebScrapeResponse { requested: boolean; } + /** + * Product detail page classification and the extracted product. + */ + export interface Product { + data: Product.Data | null; + + requested: boolean; + } + + export namespace Product { + export interface Data { + /** + * Whether the page is a product detail page. + */ + isProductPage: boolean; + + /** + * The extracted product, or null when the page is not a product detail page. + */ + product: Data.Product | null; + } + + export namespace Data { + /** + * The extracted product, or null when the page is not a product detail page. + */ + export interface Product { + /** + * Stock or ordering availability. + */ + availability: + | 'in_stock' + | 'out_of_stock' + | 'limited_availability' + | 'preorder' + | 'backorder' + | 'made_to_order' + | 'discontinued' + | null; + + /** + * Brand or vendor. + */ + brand: string | null; + + /** + * Product category. + */ + category: string | null; + + /** + * ISO 4217 currency code. + */ + currency: string | null; + + /** + * Product description. + */ + description: string | null; + + /** + * Product dimensions as shown on the page. + */ + dimensions: Array; + + /** + * Key features and specifications. + */ + features: Array; + + /** + * Product image URLs, main image first. + */ + images: Array; + + /** + * Main product image URL. + */ + imageUrl: string | null; + + /** + * Product name. + */ + name: string; + + /** + * Current price. + */ + price: number | null; + + /** + * List price before any discount. + */ + regularPrice: number | null; + + /** + * Product identifier such as a SKU or model number. + */ + sku: string | null; + + /** + * Product tags. + */ + tags: Array; + + /** + * Intended audience. + */ + targetAudience: Array; + + /** + * Product variations, such as different colors or sizes, with their attributes and + * images. Empty if none are found. May not include every variation offered by the + * store. + */ + variants: Array; + } + + export namespace Product { + export interface Variant { + /** + * Explicit variant attributes such as color, size, material, pattern and + * properties declared by page. + */ + attributes: { [key: string]: string }; + + /** + * Original source image URLs explicitly attached to this variant. + */ + images: Array; + + sku: string | null; + + /** + * Variant or offer URL when provided by the source. May be shared by variants. + */ + url: string | null; + } + } + } + } + /** * An image data URL. Use directly as an image src. */ @@ -2124,6 +2275,11 @@ export interface WebScrapeParams { */ parseParams?: WebScrapeParams.ParseParams; + /** + * Product options. Requires formats.product: true. + */ + productParams?: WebScrapeParams.ProductParams; + /** * Screenshot options. Requires formats.screenshot: true. */ @@ -2204,6 +2360,11 @@ export namespace WebScrapeParams { */ parse?: boolean; + /** + * Structured product data for product detail pages. Adds one credit. + */ + product?: boolean; + /** * An inline image of the page. */ @@ -2297,6 +2458,19 @@ export namespace WebScrapeParams { } } + /** + * Product options. Requires formats.product: true. + */ + export interface ProductParams { + /** + * Extract the product with a specialized model when the page has no structured + * product data. Adds six credits when the model returns a verdict. If the fallback + * fails, returns a partial response with the deterministic result and no fallback + * charge. Request deadlines and client disconnects still apply. + */ + useAIFallback?: boolean; + } + /** * Screenshot options. Requires formats.screenshot: true. */ diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index a24d36d7..9e58d141 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -142,6 +142,7 @@ describe('resource web', () => { json: true, markdown: true, parse: true, + product: true, screenshot: true, }, url: 'https://example.com', @@ -172,6 +173,7 @@ describe('resource web', () => { }, }, }, + productParams: { useAIFallback: true }, screenshotParams: { area: 'viewport', format: 'png' }, sharedParams: { actions: [{ action: 'Click the product details tab', type: 'perform' }], From 58005b984f0f8e01d9f6808af7ab4278e26be046 Mon Sep 17 00:00:00 2001 From: contextualbeer Date: Wed, 23 Sep 2026 09:33:52 +0200 Subject: [PATCH 077/232] release: 3.1.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 9 +++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 12 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index d4f6f299..ada7355e 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.0.0" + ".": "3.1.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 05cfd359..9685e5a5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## [3.1.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.0.0...v3.1.0) (2026-09-23) + + +### Features + +* **scrape:** add highlights format to POST /web/scrape ([#1210](https://github.com/context-dot-dev/context-typescript-sdk/issues/1210)) ([9a81729](https://github.com/context-dot-dev/context-typescript-sdk/commit/9a81729963bc7af20ab82498143b593f070adaeb)) +* **scrape:** add json output format to POST /web/scrape ([#1213](https://github.com/context-dot-dev/context-typescript-sdk/issues/1213)) ([7f96676](https://github.com/context-dot-dev/context-typescript-sdk/commit/7f966761a10434baa0a66aceb24725d227f71b16)) +* **scrape:** add product extraction format to POST /web/scrape ([#1212](https://github.com/context-dot-dev/context-typescript-sdk/issues/1212)) ([21edbde](https://github.com/context-dot-dev/context-typescript-sdk/commit/21edbde24214379f9a20b11366b3e298ff4df407)) + ## [3.0.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.19.0...v3.0.0) (2026-09-22) diff --git a/package.json b/package.json index c05e43db..defbbea0 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.0.0", + "version": "3.1.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index bccd5c23..cc0b2a97 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.0.0'; // x-release-please-version +export const VERSION = '3.1.0'; // x-release-please-version From 448684d79cea8d1e13990fd85d72218420ec8240 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 23 Sep 2026 09:04:08 +0000 Subject: [PATCH 078/232] seal --- .release-please-manifest.json | 2 +- CHANGELOG.md | 9 +++++++++ package.json | 2 +- src/resources/web.ts | 36 ++++++++++------------------------- src/version.ts | 2 +- 5 files changed, 22 insertions(+), 29 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index d4f6f299..ada7355e 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.0.0" + ".": "3.1.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 05cfd359..9685e5a5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## [3.1.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.0.0...v3.1.0) (2026-09-23) + + +### Features + +* **scrape:** add highlights format to POST /web/scrape ([#1210](https://github.com/context-dot-dev/context-typescript-sdk/issues/1210)) ([9a81729](https://github.com/context-dot-dev/context-typescript-sdk/commit/9a81729963bc7af20ab82498143b593f070adaeb)) +* **scrape:** add json output format to POST /web/scrape ([#1213](https://github.com/context-dot-dev/context-typescript-sdk/issues/1213)) ([7f96676](https://github.com/context-dot-dev/context-typescript-sdk/commit/7f966761a10434baa0a66aceb24725d227f71b16)) +* **scrape:** add product extraction format to POST /web/scrape ([#1212](https://github.com/context-dot-dev/context-typescript-sdk/issues/1212)) ([21edbde](https://github.com/context-dot-dev/context-typescript-sdk/commit/21edbde24214379f9a20b11366b3e298ff4df407)) + ## [3.0.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.19.0...v3.0.0) (2026-09-22) diff --git a/package.json b/package.json index c05e43db..defbbea0 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.0.0", + "version": "3.1.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/resources/web.ts b/src/resources/web.ts index 868732d4..18c127f9 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -946,9 +946,7 @@ export interface WebScrapeResponse { cache_metadata: WebScrapeResponse.CacheMetadata; /** - * Plain-text passages relevant to highlightsParams.query, in page order, each - * prefixed with its section heading in square brackets. Empty when the page has no - * text. + * Relevant passages for your question or topic. */ highlights: WebScrapeResponse.Highlights; @@ -963,10 +961,7 @@ export interface WebScrapeResponse { images: WebScrapeResponse.Images; /** - * Page data extracted into jsonParams.schema, after shared content filters. Values - * are grounded in the page; optional fields the page does not state are omitted, - * or null when their type allows null. An empty object when the filters leave no - * text. + * Page data extracted using your schema. */ json: WebScrapeResponse.Json; @@ -986,7 +981,7 @@ export interface WebScrapeResponse { parsed: WebScrapeResponse.Parsed; /** - * Product detail page classification and the extracted product. + * Product details found on the page. */ product: WebScrapeResponse.Product; @@ -1062,9 +1057,7 @@ export namespace WebScrapeResponse { } /** - * Plain-text passages relevant to highlightsParams.query, in page order, each - * prefixed with its section heading in square brackets. Empty when the page has no - * text. + * Relevant passages for your question or topic. */ export interface Highlights { data: Array | null; @@ -1125,10 +1118,7 @@ export namespace WebScrapeResponse { } /** - * Page data extracted into jsonParams.schema, after shared content filters. Values - * are grounded in the page; optional fields the page does not state are omitted, - * or null when their type allows null. An empty object when the filters leave no - * text. + * Page data extracted using your schema. */ export interface Json { data: { [key: string]: unknown } | null; @@ -1287,7 +1277,7 @@ export namespace WebScrapeResponse { } /** - * Product detail page classification and the extracted product. + * Product details found on the page. */ export interface Product { data: Product.Data | null; @@ -2309,8 +2299,7 @@ export interface WebScrapeParams { /** * Zero data retention. Bypasses caches and uploads; excludes request/response - * content and tags from logs. Must be enabled for your organization. Not available - * with the highlights output. + * content and tags from logs. Must be enabled for your organization. */ zdr?: 'enabled' | 'disabled'; } @@ -2326,9 +2315,7 @@ export namespace WebScrapeParams { bytes?: boolean; /** - * Plain-text passages from the page that are most relevant to - * highlightsParams.query, each prefixed with its section heading. Adds 3 credits. - * Not available with zdr enabled. + * Relevant passages for your question or topic. Adds 3 credits. */ highlights?: boolean; @@ -2343,10 +2330,7 @@ export namespace WebScrapeParams { images?: boolean; /** - * Page data extracted by an LLM from the page Markdown into jsonParams.schema; - * values carried only in attributes or CSS classes need formats.parse instead. - * Adds four credits when the page has text to extract; when shared content filters - * leave no text the result is an empty object and only the base price applies. + * Page data extracted using your schema. Adds 4 credits. */ json?: boolean; @@ -2361,7 +2345,7 @@ export namespace WebScrapeParams { parse?: boolean; /** - * Structured product data for product detail pages. Adds one credit. + * Product details such as name, price, and availability. Adds 1 credit. */ product?: boolean; diff --git a/src/version.ts b/src/version.ts index bccd5c23..cc0b2a97 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.0.0'; // x-release-please-version +export const VERSION = '3.1.0'; // x-release-please-version From abfa08c189f56daa91f53fd53fbf1b29ad58322d Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 23 Sep 2026 09:04:09 +0000 Subject: [PATCH 079/232] feat(scrape): enable highlights with zero data retention (#1246) Stainless-Generated-From: 448684d79cea8d1e13990fd85d72218420ec8240 --- src/resources/web.ts | 36 ++++++++++-------------------------- 1 file changed, 10 insertions(+), 26 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 868732d4..18c127f9 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -946,9 +946,7 @@ export interface WebScrapeResponse { cache_metadata: WebScrapeResponse.CacheMetadata; /** - * Plain-text passages relevant to highlightsParams.query, in page order, each - * prefixed with its section heading in square brackets. Empty when the page has no - * text. + * Relevant passages for your question or topic. */ highlights: WebScrapeResponse.Highlights; @@ -963,10 +961,7 @@ export interface WebScrapeResponse { images: WebScrapeResponse.Images; /** - * Page data extracted into jsonParams.schema, after shared content filters. Values - * are grounded in the page; optional fields the page does not state are omitted, - * or null when their type allows null. An empty object when the filters leave no - * text. + * Page data extracted using your schema. */ json: WebScrapeResponse.Json; @@ -986,7 +981,7 @@ export interface WebScrapeResponse { parsed: WebScrapeResponse.Parsed; /** - * Product detail page classification and the extracted product. + * Product details found on the page. */ product: WebScrapeResponse.Product; @@ -1062,9 +1057,7 @@ export namespace WebScrapeResponse { } /** - * Plain-text passages relevant to highlightsParams.query, in page order, each - * prefixed with its section heading in square brackets. Empty when the page has no - * text. + * Relevant passages for your question or topic. */ export interface Highlights { data: Array | null; @@ -1125,10 +1118,7 @@ export namespace WebScrapeResponse { } /** - * Page data extracted into jsonParams.schema, after shared content filters. Values - * are grounded in the page; optional fields the page does not state are omitted, - * or null when their type allows null. An empty object when the filters leave no - * text. + * Page data extracted using your schema. */ export interface Json { data: { [key: string]: unknown } | null; @@ -1287,7 +1277,7 @@ export namespace WebScrapeResponse { } /** - * Product detail page classification and the extracted product. + * Product details found on the page. */ export interface Product { data: Product.Data | null; @@ -2309,8 +2299,7 @@ export interface WebScrapeParams { /** * Zero data retention. Bypasses caches and uploads; excludes request/response - * content and tags from logs. Must be enabled for your organization. Not available - * with the highlights output. + * content and tags from logs. Must be enabled for your organization. */ zdr?: 'enabled' | 'disabled'; } @@ -2326,9 +2315,7 @@ export namespace WebScrapeParams { bytes?: boolean; /** - * Plain-text passages from the page that are most relevant to - * highlightsParams.query, each prefixed with its section heading. Adds 3 credits. - * Not available with zdr enabled. + * Relevant passages for your question or topic. Adds 3 credits. */ highlights?: boolean; @@ -2343,10 +2330,7 @@ export namespace WebScrapeParams { images?: boolean; /** - * Page data extracted by an LLM from the page Markdown into jsonParams.schema; - * values carried only in attributes or CSS classes need formats.parse instead. - * Adds four credits when the page has text to extract; when shared content filters - * leave no text the result is an empty object and only the base price applies. + * Page data extracted using your schema. Adds 4 credits. */ json?: boolean; @@ -2361,7 +2345,7 @@ export namespace WebScrapeParams { parse?: boolean; /** - * Structured product data for product detail pages. Adds one credit. + * Product details such as name, price, and availability. Adds 1 credit. */ product?: boolean; From f0c02c3e70d29cee5d4e6a5f87fca6db239d7df8 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 23 Sep 2026 19:48:01 +0000 Subject: [PATCH 080/232] seal --- src/resources/web.ts | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 18c127f9..e94a9b85 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -946,7 +946,9 @@ export interface WebScrapeResponse { cache_metadata: WebScrapeResponse.CacheMetadata; /** - * Relevant passages for your question or topic. + * Relevant passages for your question or topic, in page order. A heading in square + * brackets is included when needed to interpret a passage. Empty when the page has + * no text. */ highlights: WebScrapeResponse.Highlights; @@ -1057,7 +1059,9 @@ export namespace WebScrapeResponse { } /** - * Relevant passages for your question or topic. + * Relevant passages for your question or topic, in page order. A heading in square + * brackets is included when needed to interpret a passage. Empty when the page has + * no text. */ export interface Highlights { data: Array | null; @@ -2315,7 +2319,8 @@ export namespace WebScrapeParams { bytes?: boolean; /** - * Relevant passages for your question or topic. Adds 3 credits. + * Relevant passages for your question or topic, with headings included when needed + * for context. Adds 3 credits. */ highlights?: boolean; From 54b38a5dec14bd25540894b112826262d175c620 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 23 Sep 2026 19:48:01 +0000 Subject: [PATCH 081/232] fix(scrape): retain highlight headings only when needed (#1245) Stainless-Generated-From: f0c02c3e70d29cee5d4e6a5f87fca6db239d7df8 --- src/resources/web.ts | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 18c127f9..e94a9b85 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -946,7 +946,9 @@ export interface WebScrapeResponse { cache_metadata: WebScrapeResponse.CacheMetadata; /** - * Relevant passages for your question or topic. + * Relevant passages for your question or topic, in page order. A heading in square + * brackets is included when needed to interpret a passage. Empty when the page has + * no text. */ highlights: WebScrapeResponse.Highlights; @@ -1057,7 +1059,9 @@ export namespace WebScrapeResponse { } /** - * Relevant passages for your question or topic. + * Relevant passages for your question or topic, in page order. A heading in square + * brackets is included when needed to interpret a passage. Empty when the page has + * no text. */ export interface Highlights { data: Array | null; @@ -2315,7 +2319,8 @@ export namespace WebScrapeParams { bytes?: boolean; /** - * Relevant passages for your question or topic. Adds 3 credits. + * Relevant passages for your question or topic, with headings included when needed + * for context. Adds 3 credits. */ highlights?: boolean; From e18704d40b4dc7e7ee9cae5fd0958a81154670f2 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 24 Sep 2026 02:17:34 +0000 Subject: [PATCH 082/232] seal --- src/resources/web.ts | 123 ++++++++++++++++++++++++++++++++----------- 1 file changed, 93 insertions(+), 30 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index e94a9b85..ac8ed16a 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -90,14 +90,20 @@ export class Web extends APIResource { * extraction. Cached outputs can come from different visits within maxAgeMs; use 0 * for a fresh capture. HTML-only requests use the existing fast acquisition path. * Highlights return the plain-text passages most relevant to - * highlightsParams.query. One credit per request, including cache hits and missing - * pages, or two with browser actions; highlights add 3 credits when passages are - * returned; JSON extraction adds four credits and runs an LLM over the page - * Markdown on every request that has text to extract; PDF OCR adds one credit per - * recovered page on fresh extraction; the product output adds one credit, plus six - * more when the specialized model is used. Original response bytes and screenshots - * are limited to 20 MiB each, screenshots to 40 megapixels, and the combined - * browser capture to 60 MiB. + * highlightsParams.query. Requests with at least one successful output cost one + * base credit, including cache hits, or two with browser actions. All-failed + * responses are unbilled except missing pages, which retain the base price and the + * one-credit product charge when product was requested. Highlights add 3 credits + * when passages are returned. JSON extraction runs an LLM over nonempty page + * Markdown and adds four credits only when its result is returned successfully. + * PDF OCR adds one credit per recovered page on fresh extraction. Product adds one + * credit when its successful result is returned, plus six if that result used the + * specialized model. Original response bytes and screenshots are limited to 20 MiB + * each, screenshots to 40 megapixels, and the combined response to 60 MiB. An + * oversized output has success: false and data: null. If the combined response + * exceeds its limit, the largest outputs are marked failed until the remaining + * outputs fit. Valid captured pieces may still be cached when omitted to meet the + * response size limit. * * @example * ```ts @@ -1004,10 +1010,11 @@ export interface WebScrapeResponse { url: string; /** - * Present when return-partial captures a page that is still loading, returns - * images before image processing finishes, or cuts product AI extraction short. - * Also present if the optional product AI fallback fails. Partial responses are - * not cached. + * Present when a requested output fails, capture returns a page that is still + * loading, images return before processing finishes, or the optional product AI + * fallback fails or is cut short. Check each output's success field for its + * result. Valid captured pieces may be cached independently; failed retrievals and + * incomplete captures are not cached. */ isPartial?: true; @@ -1026,6 +1033,11 @@ export namespace WebScrapeResponse { data: Bytes.Data | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } export namespace Bytes { @@ -1067,6 +1079,11 @@ export namespace WebScrapeResponse { data: Array | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } /** @@ -1076,6 +1093,11 @@ export namespace WebScrapeResponse { data: string | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } /** @@ -1085,6 +1107,11 @@ export namespace WebScrapeResponse { data: Array | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } export namespace Images { @@ -1128,6 +1155,11 @@ export namespace WebScrapeResponse { data: { [key: string]: unknown } | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } /** @@ -1137,6 +1169,11 @@ export namespace WebScrapeResponse { data: string | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } /** @@ -1278,6 +1315,11 @@ export namespace WebScrapeResponse { data: { [key: string]: unknown } | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } /** @@ -1287,6 +1329,11 @@ export namespace WebScrapeResponse { data: Product.Data | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } export namespace Product { @@ -1429,6 +1476,11 @@ export namespace WebScrapeResponse { data: string | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } /** @@ -2292,12 +2344,16 @@ export interface WebScrapeParams { /** * Total deadline, including navigation, actions, waiting, and all outputs. - * Defaults to 60000 milliseconds with behavior fail. Use return-partial to capture - * the current page state and return captured images if image processing cannot - * finish before the deadline; these responses set isPartial and are not cached. - * Every requested format must still be available. Fixed waits must fit before a - * response reserve of up to 5000 milliseconds (at most one quarter of the timeout) - * when using return-partial. + * Defaults to 60000 milliseconds with behavior fail. Individual outputs have + * internal deadlines that reserve time to return completed outputs; timed-out + * outputs have success: false and data: null under either behavior. The overall + * request deadline remains enforced: fail returns an error if that deadline is + * reached. Use return-partial to allow the current page state and available + * outputs when the page is still loading. Partial responses set isPartial. Failed + * retrievals and incomplete captures are not cached; valid captured pieces may be + * cached independently. Fixed waits must fit before a response reserve of up to + * 5000 milliseconds (at most one quarter of the timeout) when using + * return-partial. */ timeoutOpts?: WebScrapeParams.TimeoutOpts; @@ -2320,7 +2376,7 @@ export namespace WebScrapeParams { /** * Relevant passages for your question or topic, with headings included when needed - * for context. Adds 3 credits. + * for context. Adds 3 credits when passages are returned. */ highlights?: boolean; @@ -2335,7 +2391,8 @@ export namespace WebScrapeParams { images?: boolean; /** - * Page data extracted using your schema. Adds 4 credits. + * Page data extracted using your schema. Adds 4 credits when extraction succeeds + * and its result is returned. */ json?: boolean; @@ -2350,7 +2407,8 @@ export namespace WebScrapeParams { parse?: boolean; /** - * Product details such as name, price, and availability. Adds 1 credit. + * Product details such as name, price, and availability. Adds 1 credit when its + * successful result is returned or the target page is missing. */ product?: boolean; @@ -2453,9 +2511,10 @@ export namespace WebScrapeParams { export interface ProductParams { /** * Extract the product with a specialized model when the page has no structured - * product data. Adds six credits when the model returns a verdict. If the fallback - * fails, returns a partial response with the deterministic result and no fallback - * charge. Request deadlines and client disconnects still apply. + * product data. Adds six credits when the model verdict is returned successfully. + * If the fallback fails, the product output has success: false and data: null with + * no fallback charge; other outputs remain available. Request deadlines and client + * disconnects still apply. */ useAIFallback?: boolean; } @@ -2653,12 +2712,16 @@ export namespace WebScrapeParams { /** * Total deadline, including navigation, actions, waiting, and all outputs. - * Defaults to 60000 milliseconds with behavior fail. Use return-partial to capture - * the current page state and return captured images if image processing cannot - * finish before the deadline; these responses set isPartial and are not cached. - * Every requested format must still be available. Fixed waits must fit before a - * response reserve of up to 5000 milliseconds (at most one quarter of the timeout) - * when using return-partial. + * Defaults to 60000 milliseconds with behavior fail. Individual outputs have + * internal deadlines that reserve time to return completed outputs; timed-out + * outputs have success: false and data: null under either behavior. The overall + * request deadline remains enforced: fail returns an error if that deadline is + * reached. Use return-partial to allow the current page state and available + * outputs when the page is still loading. Partial responses set isPartial. Failed + * retrievals and incomplete captures are not cached; valid captured pieces may be + * cached independently. Fixed waits must fit before a response reserve of up to + * 5000 milliseconds (at most one quarter of the timeout) when using + * return-partial. */ export interface TimeoutOpts { /** From a31d02e8c30a229cfd8b0fa0f3aa79ed9f301f10 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 24 Sep 2026 02:17:34 +0000 Subject: [PATCH 083/232] fix(scrape): preserve successful formats when other outputs fail (#1263) Stainless-Generated-From: e18704d40b4dc7e7ee9cae5fd0958a81154670f2 --- src/resources/web.ts | 123 ++++++++++++++++++++++++++++++++----------- 1 file changed, 93 insertions(+), 30 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index e94a9b85..ac8ed16a 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -90,14 +90,20 @@ export class Web extends APIResource { * extraction. Cached outputs can come from different visits within maxAgeMs; use 0 * for a fresh capture. HTML-only requests use the existing fast acquisition path. * Highlights return the plain-text passages most relevant to - * highlightsParams.query. One credit per request, including cache hits and missing - * pages, or two with browser actions; highlights add 3 credits when passages are - * returned; JSON extraction adds four credits and runs an LLM over the page - * Markdown on every request that has text to extract; PDF OCR adds one credit per - * recovered page on fresh extraction; the product output adds one credit, plus six - * more when the specialized model is used. Original response bytes and screenshots - * are limited to 20 MiB each, screenshots to 40 megapixels, and the combined - * browser capture to 60 MiB. + * highlightsParams.query. Requests with at least one successful output cost one + * base credit, including cache hits, or two with browser actions. All-failed + * responses are unbilled except missing pages, which retain the base price and the + * one-credit product charge when product was requested. Highlights add 3 credits + * when passages are returned. JSON extraction runs an LLM over nonempty page + * Markdown and adds four credits only when its result is returned successfully. + * PDF OCR adds one credit per recovered page on fresh extraction. Product adds one + * credit when its successful result is returned, plus six if that result used the + * specialized model. Original response bytes and screenshots are limited to 20 MiB + * each, screenshots to 40 megapixels, and the combined response to 60 MiB. An + * oversized output has success: false and data: null. If the combined response + * exceeds its limit, the largest outputs are marked failed until the remaining + * outputs fit. Valid captured pieces may still be cached when omitted to meet the + * response size limit. * * @example * ```ts @@ -1004,10 +1010,11 @@ export interface WebScrapeResponse { url: string; /** - * Present when return-partial captures a page that is still loading, returns - * images before image processing finishes, or cuts product AI extraction short. - * Also present if the optional product AI fallback fails. Partial responses are - * not cached. + * Present when a requested output fails, capture returns a page that is still + * loading, images return before processing finishes, or the optional product AI + * fallback fails or is cut short. Check each output's success field for its + * result. Valid captured pieces may be cached independently; failed retrievals and + * incomplete captures are not cached. */ isPartial?: true; @@ -1026,6 +1033,11 @@ export namespace WebScrapeResponse { data: Bytes.Data | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } export namespace Bytes { @@ -1067,6 +1079,11 @@ export namespace WebScrapeResponse { data: Array | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } /** @@ -1076,6 +1093,11 @@ export namespace WebScrapeResponse { data: string | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } /** @@ -1085,6 +1107,11 @@ export namespace WebScrapeResponse { data: Array | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } export namespace Images { @@ -1128,6 +1155,11 @@ export namespace WebScrapeResponse { data: { [key: string]: unknown } | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } /** @@ -1137,6 +1169,11 @@ export namespace WebScrapeResponse { data: string | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } /** @@ -1278,6 +1315,11 @@ export namespace WebScrapeResponse { data: { [key: string]: unknown } | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } /** @@ -1287,6 +1329,11 @@ export namespace WebScrapeResponse { data: Product.Data | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } export namespace Product { @@ -1429,6 +1476,11 @@ export namespace WebScrapeResponse { data: string | null; requested: boolean; + + /** + * True when retrieved, false when retrieval failed, and null when not requested. + */ + success: boolean | null; } /** @@ -2292,12 +2344,16 @@ export interface WebScrapeParams { /** * Total deadline, including navigation, actions, waiting, and all outputs. - * Defaults to 60000 milliseconds with behavior fail. Use return-partial to capture - * the current page state and return captured images if image processing cannot - * finish before the deadline; these responses set isPartial and are not cached. - * Every requested format must still be available. Fixed waits must fit before a - * response reserve of up to 5000 milliseconds (at most one quarter of the timeout) - * when using return-partial. + * Defaults to 60000 milliseconds with behavior fail. Individual outputs have + * internal deadlines that reserve time to return completed outputs; timed-out + * outputs have success: false and data: null under either behavior. The overall + * request deadline remains enforced: fail returns an error if that deadline is + * reached. Use return-partial to allow the current page state and available + * outputs when the page is still loading. Partial responses set isPartial. Failed + * retrievals and incomplete captures are not cached; valid captured pieces may be + * cached independently. Fixed waits must fit before a response reserve of up to + * 5000 milliseconds (at most one quarter of the timeout) when using + * return-partial. */ timeoutOpts?: WebScrapeParams.TimeoutOpts; @@ -2320,7 +2376,7 @@ export namespace WebScrapeParams { /** * Relevant passages for your question or topic, with headings included when needed - * for context. Adds 3 credits. + * for context. Adds 3 credits when passages are returned. */ highlights?: boolean; @@ -2335,7 +2391,8 @@ export namespace WebScrapeParams { images?: boolean; /** - * Page data extracted using your schema. Adds 4 credits. + * Page data extracted using your schema. Adds 4 credits when extraction succeeds + * and its result is returned. */ json?: boolean; @@ -2350,7 +2407,8 @@ export namespace WebScrapeParams { parse?: boolean; /** - * Product details such as name, price, and availability. Adds 1 credit. + * Product details such as name, price, and availability. Adds 1 credit when its + * successful result is returned or the target page is missing. */ product?: boolean; @@ -2453,9 +2511,10 @@ export namespace WebScrapeParams { export interface ProductParams { /** * Extract the product with a specialized model when the page has no structured - * product data. Adds six credits when the model returns a verdict. If the fallback - * fails, returns a partial response with the deterministic result and no fallback - * charge. Request deadlines and client disconnects still apply. + * product data. Adds six credits when the model verdict is returned successfully. + * If the fallback fails, the product output has success: false and data: null with + * no fallback charge; other outputs remain available. Request deadlines and client + * disconnects still apply. */ useAIFallback?: boolean; } @@ -2653,12 +2712,16 @@ export namespace WebScrapeParams { /** * Total deadline, including navigation, actions, waiting, and all outputs. - * Defaults to 60000 milliseconds with behavior fail. Use return-partial to capture - * the current page state and return captured images if image processing cannot - * finish before the deadline; these responses set isPartial and are not cached. - * Every requested format must still be available. Fixed waits must fit before a - * response reserve of up to 5000 milliseconds (at most one quarter of the timeout) - * when using return-partial. + * Defaults to 60000 milliseconds with behavior fail. Individual outputs have + * internal deadlines that reserve time to return completed outputs; timed-out + * outputs have success: false and data: null under either behavior. The overall + * request deadline remains enforced: fail returns an error if that deadline is + * reached. Use return-partial to allow the current page state and available + * outputs when the page is still loading. Partial responses set isPartial. Failed + * retrievals and incomplete captures are not cached; valid captured pieces may be + * cached independently. Fixed waits must fit before a response reserve of up to + * 5000 milliseconds (at most one quarter of the timeout) when using + * return-partial. */ export interface TimeoutOpts { /** From 742c8e55bd2b9e3595ec971aeb75723f45dcfc65 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 26 Sep 2026 03:07:44 +0000 Subject: [PATCH 084/232] seal --- src/resources/web.ts | 47 ++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index ac8ed16a..e76973c2 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -89,21 +89,21 @@ export class Web extends APIResource { * is shared with Markdown, parsed fields, product data, highlights, and JSON * extraction. Cached outputs can come from different visits within maxAgeMs; use 0 * for a fresh capture. HTML-only requests use the existing fast acquisition path. - * Highlights return the plain-text passages most relevant to - * highlightsParams.query. Requests with at least one successful output cost one - * base credit, including cache hits, or two with browser actions. All-failed - * responses are unbilled except missing pages, which retain the base price and the - * one-credit product charge when product was requested. Highlights add 3 credits - * when passages are returned. JSON extraction runs an LLM over nonempty page - * Markdown and adds four credits only when its result is returned successfully. - * PDF OCR adds one credit per recovered page on fresh extraction. Product adds one - * credit when its successful result is returned, plus six if that result used the - * specialized model. Original response bytes and screenshots are limited to 20 MiB - * each, screenshots to 40 megapixels, and the combined response to 60 MiB. An - * oversized output has success: false and data: null. If the combined response - * exceeds its limit, the largest outputs are marked failed until the remaining - * outputs fit. Valid captured pieces may still be cached when omitted to meet the - * response size limit. + * Highlights return Markdown excerpts most relevant to highlightsParams.query. + * Requests with at least one successful output cost one base credit, including + * cache hits, or two with browser actions. All-failed responses are unbilled + * except missing pages, which retain the base price and the one-credit product + * charge when product was requested. Highlights add 3 credits when passages are + * returned. JSON extraction runs an LLM over nonempty page Markdown and adds four + * credits only when its result is returned successfully. PDF OCR adds one credit + * per recovered page on fresh extraction. Product adds one credit when its + * successful result is returned, plus six if that result used the specialized + * model. Original response bytes and screenshots are limited to 20 MiB each, + * screenshots to 40 megapixels, and the combined response to 60 MiB. An oversized + * output has success: false and data: null. If the combined response exceeds its + * limit, the largest outputs are marked failed until the remaining outputs fit. + * Valid captured pieces may still be cached when omitted to meet the response size + * limit. * * @example * ```ts @@ -952,9 +952,9 @@ export interface WebScrapeResponse { cache_metadata: WebScrapeResponse.CacheMetadata; /** - * Relevant passages for your question or topic, in page order. A heading in square - * brackets is included when needed to interpret a passage. Empty when the page has - * no text. + * Relevant Markdown excerpts for your question or topic, in page order. Headings + * in square brackets supply necessary context; ellipses mark omitted portions. + * Empty when the page has no text. */ highlights: WebScrapeResponse.Highlights; @@ -1071,9 +1071,9 @@ export namespace WebScrapeResponse { } /** - * Relevant passages for your question or topic, in page order. A heading in square - * brackets is included when needed to interpret a passage. Empty when the page has - * no text. + * Relevant Markdown excerpts for your question or topic, in page order. Headings + * in square brackets supply necessary context; ellipses mark omitted portions. + * Empty when the page has no text. */ export interface Highlights { data: Array | null; @@ -2375,8 +2375,9 @@ export namespace WebScrapeParams { bytes?: boolean; /** - * Relevant passages for your question or topic, with headings included when needed - * for context. Adds 3 credits when passages are returned. + * Relevant Markdown excerpts for your question or topic, preserving code, lists, + * and tables, with headings included when needed for context. Adds 3 credits when + * passages are returned. */ highlights?: boolean; From 503abec171290eaab2c4fa97bfacffd28d4e70f3 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 26 Sep 2026 03:07:44 +0000 Subject: [PATCH 085/232] feat(highlights): preserve Markdown structure in scrape excerpts (#1236) Stainless-Generated-From: 742c8e55bd2b9e3595ec971aeb75723f45dcfc65 --- src/resources/web.ts | 47 ++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index ac8ed16a..e76973c2 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -89,21 +89,21 @@ export class Web extends APIResource { * is shared with Markdown, parsed fields, product data, highlights, and JSON * extraction. Cached outputs can come from different visits within maxAgeMs; use 0 * for a fresh capture. HTML-only requests use the existing fast acquisition path. - * Highlights return the plain-text passages most relevant to - * highlightsParams.query. Requests with at least one successful output cost one - * base credit, including cache hits, or two with browser actions. All-failed - * responses are unbilled except missing pages, which retain the base price and the - * one-credit product charge when product was requested. Highlights add 3 credits - * when passages are returned. JSON extraction runs an LLM over nonempty page - * Markdown and adds four credits only when its result is returned successfully. - * PDF OCR adds one credit per recovered page on fresh extraction. Product adds one - * credit when its successful result is returned, plus six if that result used the - * specialized model. Original response bytes and screenshots are limited to 20 MiB - * each, screenshots to 40 megapixels, and the combined response to 60 MiB. An - * oversized output has success: false and data: null. If the combined response - * exceeds its limit, the largest outputs are marked failed until the remaining - * outputs fit. Valid captured pieces may still be cached when omitted to meet the - * response size limit. + * Highlights return Markdown excerpts most relevant to highlightsParams.query. + * Requests with at least one successful output cost one base credit, including + * cache hits, or two with browser actions. All-failed responses are unbilled + * except missing pages, which retain the base price and the one-credit product + * charge when product was requested. Highlights add 3 credits when passages are + * returned. JSON extraction runs an LLM over nonempty page Markdown and adds four + * credits only when its result is returned successfully. PDF OCR adds one credit + * per recovered page on fresh extraction. Product adds one credit when its + * successful result is returned, plus six if that result used the specialized + * model. Original response bytes and screenshots are limited to 20 MiB each, + * screenshots to 40 megapixels, and the combined response to 60 MiB. An oversized + * output has success: false and data: null. If the combined response exceeds its + * limit, the largest outputs are marked failed until the remaining outputs fit. + * Valid captured pieces may still be cached when omitted to meet the response size + * limit. * * @example * ```ts @@ -952,9 +952,9 @@ export interface WebScrapeResponse { cache_metadata: WebScrapeResponse.CacheMetadata; /** - * Relevant passages for your question or topic, in page order. A heading in square - * brackets is included when needed to interpret a passage. Empty when the page has - * no text. + * Relevant Markdown excerpts for your question or topic, in page order. Headings + * in square brackets supply necessary context; ellipses mark omitted portions. + * Empty when the page has no text. */ highlights: WebScrapeResponse.Highlights; @@ -1071,9 +1071,9 @@ export namespace WebScrapeResponse { } /** - * Relevant passages for your question or topic, in page order. A heading in square - * brackets is included when needed to interpret a passage. Empty when the page has - * no text. + * Relevant Markdown excerpts for your question or topic, in page order. Headings + * in square brackets supply necessary context; ellipses mark omitted portions. + * Empty when the page has no text. */ export interface Highlights { data: Array | null; @@ -2375,8 +2375,9 @@ export namespace WebScrapeParams { bytes?: boolean; /** - * Relevant passages for your question or topic, with headings included when needed - * for context. Adds 3 credits when passages are returned. + * Relevant Markdown excerpts for your question or topic, preserving code, lists, + * and tables, with headings included when needed for context. Adds 3 credits when + * passages are returned. */ highlights?: boolean; From 119c71952492b0ece57683fd80af23b5709c9716 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 26 Sep 2026 10:05:24 +0000 Subject: [PATCH 086/232] seal --- src/resources/news.ts | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/src/resources/news.ts b/src/resources/news.ts index 9653f44f..e5f72573 100644 --- a/src/resources/news.ts +++ b/src/resources/news.ts @@ -11,9 +11,10 @@ export class News extends APIResource { /** * Searches live and historical company news for one company, identified in * searchBy by name, domain, ticker (optionally disambiguated by exchange), or - * ISIN. Results can be filtered by publisher domain, publisher country, article - * language, article type, and published-at date, and include stable story IDs, - * source metadata, verified entity relevance, and cursor pagination. + * ISIN. Results can be filtered by one of publisher domain, publisher country, + * article language, or article type, optionally combined with a published-at date + * range, and include stable story IDs, source metadata, verified entity relevance, + * and cursor pagination. * * @example * ```ts @@ -208,7 +209,9 @@ export interface NewsSearchParams { cursor?: string | null; /** - * Optional result filters. + * Optional result filters. Use at most one of sourceDomain, sourceCountry, + * articleLanguage, or articleType. A date range may accompany that category; + * date.from must not exceed date.to. */ filterBy?: NewsSearchParams.FilterBy; @@ -377,7 +380,9 @@ export namespace NewsSearchParams { } /** - * Optional result filters. + * Optional result filters. Use at most one of sourceDomain, sourceCountry, + * articleLanguage, or articleType. A date range may accompany that category; + * date.from must not exceed date.to. */ export interface FilterBy { /** @@ -393,7 +398,7 @@ export namespace NewsSearchParams { articleType?: Array<'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'>; /** - * Published-at window in epoch milliseconds. + * Published-at window in epoch milliseconds. from must be before or equal to to. */ date?: FilterBy.Date; @@ -437,7 +442,7 @@ export namespace NewsSearchParams { export namespace FilterBy { /** - * Published-at window in epoch milliseconds. + * Published-at window in epoch milliseconds. from must be before or equal to to. */ export interface Date { /** From b3b4267a2b4452dc71546243888dc1333e30ef19 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 26 Sep 2026 10:05:24 +0000 Subject: [PATCH 087/232] fix(openapi): document exclusive news filters (#1265) Stainless-Generated-From: 119c71952492b0ece57683fd80af23b5709c9716 --- src/resources/news.ts | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/src/resources/news.ts b/src/resources/news.ts index 9653f44f..e5f72573 100644 --- a/src/resources/news.ts +++ b/src/resources/news.ts @@ -11,9 +11,10 @@ export class News extends APIResource { /** * Searches live and historical company news for one company, identified in * searchBy by name, domain, ticker (optionally disambiguated by exchange), or - * ISIN. Results can be filtered by publisher domain, publisher country, article - * language, article type, and published-at date, and include stable story IDs, - * source metadata, verified entity relevance, and cursor pagination. + * ISIN. Results can be filtered by one of publisher domain, publisher country, + * article language, or article type, optionally combined with a published-at date + * range, and include stable story IDs, source metadata, verified entity relevance, + * and cursor pagination. * * @example * ```ts @@ -208,7 +209,9 @@ export interface NewsSearchParams { cursor?: string | null; /** - * Optional result filters. + * Optional result filters. Use at most one of sourceDomain, sourceCountry, + * articleLanguage, or articleType. A date range may accompany that category; + * date.from must not exceed date.to. */ filterBy?: NewsSearchParams.FilterBy; @@ -377,7 +380,9 @@ export namespace NewsSearchParams { } /** - * Optional result filters. + * Optional result filters. Use at most one of sourceDomain, sourceCountry, + * articleLanguage, or articleType. A date range may accompany that category; + * date.from must not exceed date.to. */ export interface FilterBy { /** @@ -393,7 +398,7 @@ export namespace NewsSearchParams { articleType?: Array<'editorial' | 'press_release' | 'regulatory_filing' | 'advisory'>; /** - * Published-at window in epoch milliseconds. + * Published-at window in epoch milliseconds. from must be before or equal to to. */ date?: FilterBy.Date; @@ -437,7 +442,7 @@ export namespace NewsSearchParams { export namespace FilterBy { /** - * Published-at window in epoch milliseconds. + * Published-at window in epoch milliseconds. from must be before or equal to to. */ export interface Date { /** From bade3eabe750969d299f6915d0a7eb5d4461523e Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 27 Sep 2026 01:55:11 +0000 Subject: [PATCH 088/232] seal --- .stats.yml | 2 +- api.md | 10 +++ src/client.ts | 12 ++++ src/resources/feedback.ts | 104 +++++++++++++++++++++++++++ src/resources/index.ts | 1 + tests/api-resources/feedback.test.ts | 36 ++++++++++ 6 files changed, 164 insertions(+), 1 deletion(-) create mode 100644 src/resources/feedback.ts create mode 100644 tests/api-resources/feedback.test.ts diff --git a/.stats.yml b/.stats.yml index 48f88c43..de0574c0 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 43 +configured_endpoints: 44 diff --git a/api.md b/api.md index c9330f41..43bc7eb2 100644 --- a/api.md +++ b/api.md @@ -185,3 +185,13 @@ Methods: - client.logs.retrieve(requestID) -> LogRetrieveResponse - client.logs.list({ ...params }) -> LogListResponse + +# Feedback + +Types: + +- FeedbackSubmitResponse + +Methods: + +- client.feedback.submit({ ...params }) -> FeedbackSubmitResponse diff --git a/src/client.ts b/src/client.ts index d76ce6da..1f9e2d36 100644 --- a/src/client.ts +++ b/src/client.ts @@ -40,6 +40,7 @@ import { BrandSearchParams, BrandSearchResponse, } from './resources/brand'; +import { Feedback, FeedbackSubmitParams, FeedbackSubmitResponse } from './resources/feedback'; import { Industry, IndustryRetrieveNaicsParams, @@ -840,6 +841,10 @@ export class ContextDev { * Read your organization's API request logs to debug failed calls. These endpoints cost no credits and use a separate rate limit. */ logs: API.Logs = new API.Logs(this); + /** + * Report bugs, docs mismatches, and friction with any Context.dev API. Submissions cost no credits and use a separate rate limit. + */ + feedback: API.Feedback = new API.Feedback(this); } ContextDev.Parse = Parse; @@ -853,6 +858,7 @@ ContextDev.Webhooks = Webhooks; ContextDev.People = People; ContextDev.News = News; ContextDev.Logs = Logs; +ContextDev.Feedback = Feedback; export declare namespace ContextDev { export type RequestOptions = Opts.RequestOptions; @@ -971,4 +977,10 @@ export declare namespace ContextDev { type LogListResponse as LogListResponse, type LogListParams as LogListParams, }; + + export { + Feedback as Feedback, + type FeedbackSubmitResponse as FeedbackSubmitResponse, + type FeedbackSubmitParams as FeedbackSubmitParams, + }; } diff --git a/src/resources/feedback.ts b/src/resources/feedback.ts new file mode 100644 index 00000000..37a82437 --- /dev/null +++ b/src/resources/feedback.ts @@ -0,0 +1,104 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../core/resource'; +import { APIPromise } from '../core/api-promise'; +import { RequestOptions } from '../internal/request-options'; + +/** + * Report bugs, docs mismatches, and friction with any Context.dev API. Submissions cost no credits and use a separate rate limit. + */ +export class Feedback extends APIResource { + /** + * Report a problem with a Context.dev API call, docs page, SDK, or CLI. Include + * request_id, url, or both. + * + * @example + * ```ts + * const response = await client.feedback.submit({ + * category: 'bug', + * note: 'Markdown drops the plan comparison table; expected all 4 rows.', + * request_id: '3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91', + * url: 'https://stripe.com/pricing', + * }); + * ``` + */ + submit(body: FeedbackSubmitParams, options?: RequestOptions): APIPromise { + return this._client.post('/feedback', { body, ...options }); + } +} + +export interface FeedbackSubmitResponse { + /** + * True when feedback for this request_id was already recorded; the original + * feedback_id is returned. + */ + already_submitted: boolean; + + /** + * ID of the stored feedback. + */ + feedback_id: string; + + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: FeedbackSubmitResponse.KeyMetadata; +} + +export namespace FeedbackSubmitResponse { + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + +export interface FeedbackSubmitParams { + /** + * Kind of issue. + */ + category: 'bug' | 'docs_mismatch' | 'friction' | 'feature_gap' | 'quality_degradation' | 'other'; + + /** + * What went wrong and what you expected instead. + */ + note: string; + + /** + * The request_id of the API call the feedback is about, from its response body or + * X-Request-Id header. + */ + request_id?: string; + + /** + * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + */ + tags?: Array; + + /** + * The page the feedback is about, such as one page of a crawl or a docs page. + */ + url?: string; +} + +export declare namespace Feedback { + export { + type FeedbackSubmitResponse as FeedbackSubmitResponse, + type FeedbackSubmitParams as FeedbackSubmitParams, + }; +} diff --git a/src/resources/index.ts b/src/resources/index.ts index 17ccfefe..1e1402fc 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -23,6 +23,7 @@ export { type BrandRetrieveParams, type BrandSearchParams, } from './brand'; +export { Feedback, type FeedbackSubmitResponse, type FeedbackSubmitParams } from './feedback'; export { Industry, type IndustryRetrieveNaicsResponse, diff --git a/tests/api-resources/feedback.test.ts b/tests/api-resources/feedback.test.ts new file mode 100644 index 00000000..243d0f0d --- /dev/null +++ b/tests/api-resources/feedback.test.ts @@ -0,0 +1,36 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import ContextDev from 'context.dev'; + +const client = new ContextDev({ + apiKey: 'My API Key', + baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', +}); + +describe('resource feedback', () => { + // Mock server tests are disabled + test.skip('submit: only required params', async () => { + const responsePromise = client.feedback.submit({ + category: 'bug', + note: 'Markdown drops the plan comparison table; expected all 4 rows.', + }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('submit: required and optional params', async () => { + const response = await client.feedback.submit({ + category: 'bug', + note: 'Markdown drops the plan comparison table; expected all 4 rows.', + request_id: '3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91', + tags: ['production', 'team-alpha'], + url: 'https://stripe.com/pricing', + }); + }); +}); From ccf8f08cec4db47eea9b49e3623fd375377f5b75 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 27 Sep 2026 01:55:12 +0000 Subject: [PATCH 089/232] feat(feedback): add agent feedback endpoint (#1322) Stainless-Generated-From: bade3eabe750969d299f6915d0a7eb5d4461523e --- .stats.yml | 2 +- api.md | 10 +++ src/client.ts | 12 ++++ src/resources/feedback.ts | 104 +++++++++++++++++++++++++++ src/resources/index.ts | 1 + tests/api-resources/feedback.test.ts | 36 ++++++++++ 6 files changed, 164 insertions(+), 1 deletion(-) create mode 100644 src/resources/feedback.ts create mode 100644 tests/api-resources/feedback.test.ts diff --git a/.stats.yml b/.stats.yml index 48f88c43..de0574c0 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 43 +configured_endpoints: 44 diff --git a/api.md b/api.md index c9330f41..43bc7eb2 100644 --- a/api.md +++ b/api.md @@ -185,3 +185,13 @@ Methods: - client.logs.retrieve(requestID) -> LogRetrieveResponse - client.logs.list({ ...params }) -> LogListResponse + +# Feedback + +Types: + +- FeedbackSubmitResponse + +Methods: + +- client.feedback.submit({ ...params }) -> FeedbackSubmitResponse diff --git a/src/client.ts b/src/client.ts index d76ce6da..1f9e2d36 100644 --- a/src/client.ts +++ b/src/client.ts @@ -40,6 +40,7 @@ import { BrandSearchParams, BrandSearchResponse, } from './resources/brand'; +import { Feedback, FeedbackSubmitParams, FeedbackSubmitResponse } from './resources/feedback'; import { Industry, IndustryRetrieveNaicsParams, @@ -840,6 +841,10 @@ export class ContextDev { * Read your organization's API request logs to debug failed calls. These endpoints cost no credits and use a separate rate limit. */ logs: API.Logs = new API.Logs(this); + /** + * Report bugs, docs mismatches, and friction with any Context.dev API. Submissions cost no credits and use a separate rate limit. + */ + feedback: API.Feedback = new API.Feedback(this); } ContextDev.Parse = Parse; @@ -853,6 +858,7 @@ ContextDev.Webhooks = Webhooks; ContextDev.People = People; ContextDev.News = News; ContextDev.Logs = Logs; +ContextDev.Feedback = Feedback; export declare namespace ContextDev { export type RequestOptions = Opts.RequestOptions; @@ -971,4 +977,10 @@ export declare namespace ContextDev { type LogListResponse as LogListResponse, type LogListParams as LogListParams, }; + + export { + Feedback as Feedback, + type FeedbackSubmitResponse as FeedbackSubmitResponse, + type FeedbackSubmitParams as FeedbackSubmitParams, + }; } diff --git a/src/resources/feedback.ts b/src/resources/feedback.ts new file mode 100644 index 00000000..37a82437 --- /dev/null +++ b/src/resources/feedback.ts @@ -0,0 +1,104 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../core/resource'; +import { APIPromise } from '../core/api-promise'; +import { RequestOptions } from '../internal/request-options'; + +/** + * Report bugs, docs mismatches, and friction with any Context.dev API. Submissions cost no credits and use a separate rate limit. + */ +export class Feedback extends APIResource { + /** + * Report a problem with a Context.dev API call, docs page, SDK, or CLI. Include + * request_id, url, or both. + * + * @example + * ```ts + * const response = await client.feedback.submit({ + * category: 'bug', + * note: 'Markdown drops the plan comparison table; expected all 4 rows.', + * request_id: '3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91', + * url: 'https://stripe.com/pricing', + * }); + * ``` + */ + submit(body: FeedbackSubmitParams, options?: RequestOptions): APIPromise { + return this._client.post('/feedback', { body, ...options }); + } +} + +export interface FeedbackSubmitResponse { + /** + * True when feedback for this request_id was already recorded; the original + * feedback_id is returned. + */ + already_submitted: boolean; + + /** + * ID of the stored feedback. + */ + feedback_id: string; + + /** + * Unique id of this API call, also sent in the X-Request-Id response header. Quote + * it when contacting support about a failed request. + */ + request_id: string; + + /** + * Credit usage, included whenever a valid API key is provided. + */ + key_metadata?: FeedbackSubmitResponse.KeyMetadata; +} + +export namespace FeedbackSubmitResponse { + /** + * Credit usage, included whenever a valid API key is provided. + */ + export interface KeyMetadata { + /** + * Credits used by this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + +export interface FeedbackSubmitParams { + /** + * Kind of issue. + */ + category: 'bug' | 'docs_mismatch' | 'friction' | 'feature_gap' | 'quality_degradation' | 'other'; + + /** + * What went wrong and what you expected instead. + */ + note: string; + + /** + * The request_id of the API call the feedback is about, from its response body or + * X-Request-Id header. + */ + request_id?: string; + + /** + * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + */ + tags?: Array; + + /** + * The page the feedback is about, such as one page of a crawl or a docs page. + */ + url?: string; +} + +export declare namespace Feedback { + export { + type FeedbackSubmitResponse as FeedbackSubmitResponse, + type FeedbackSubmitParams as FeedbackSubmitParams, + }; +} diff --git a/src/resources/index.ts b/src/resources/index.ts index 17ccfefe..1e1402fc 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -23,6 +23,7 @@ export { type BrandRetrieveParams, type BrandSearchParams, } from './brand'; +export { Feedback, type FeedbackSubmitResponse, type FeedbackSubmitParams } from './feedback'; export { Industry, type IndustryRetrieveNaicsResponse, diff --git a/tests/api-resources/feedback.test.ts b/tests/api-resources/feedback.test.ts new file mode 100644 index 00000000..243d0f0d --- /dev/null +++ b/tests/api-resources/feedback.test.ts @@ -0,0 +1,36 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import ContextDev from 'context.dev'; + +const client = new ContextDev({ + apiKey: 'My API Key', + baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', +}); + +describe('resource feedback', () => { + // Mock server tests are disabled + test.skip('submit: only required params', async () => { + const responsePromise = client.feedback.submit({ + category: 'bug', + note: 'Markdown drops the plan comparison table; expected all 4 rows.', + }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('submit: required and optional params', async () => { + const response = await client.feedback.submit({ + category: 'bug', + note: 'Markdown drops the plan comparison table; expected all 4 rows.', + request_id: '3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91', + tags: ['production', 'team-alpha'], + url: 'https://stripe.com/pricing', + }); + }); +}); From b6d848326f79ce7333f0299540976933420057d2 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 27 Sep 2026 04:14:09 +0000 Subject: [PATCH 090/232] fix(scrape): only flag partial success when a requested format succeeds (#1325) Stainless-Generated-From: fb8f9977c725d3dd0d34dbb83c55b1a2f3e629d2 --- src/resources/web.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index e76973c2..5462aeb7 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1010,11 +1010,11 @@ export interface WebScrapeResponse { url: string; /** - * Present when a requested output fails, capture returns a page that is still - * loading, images return before processing finishes, or the optional product AI - * fallback fails or is cut short. Check each output's success field for its - * result. Valid captured pieces may be cached independently; failed retrievals and - * incomplete captures are not cached. + * Present when at least one requested output succeeds while another fails, or when + * successful outputs come from a page that is still loading or images returned + * before processing finished. Absent when every requested output fails. Check each + * output's success field for its result. Valid captured pieces may be cached + * independently; failed retrievals and incomplete captures are not cached. */ isPartial?: true; From fb8f9977c725d3dd0d34dbb83c55b1a2f3e629d2 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 27 Sep 2026 04:14:09 +0000 Subject: [PATCH 091/232] seal --- src/resources/web.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index e76973c2..5462aeb7 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1010,11 +1010,11 @@ export interface WebScrapeResponse { url: string; /** - * Present when a requested output fails, capture returns a page that is still - * loading, images return before processing finishes, or the optional product AI - * fallback fails or is cut short. Check each output's success field for its - * result. Valid captured pieces may be cached independently; failed retrievals and - * incomplete captures are not cached. + * Present when at least one requested output succeeds while another fails, or when + * successful outputs come from a page that is still loading or images returned + * before processing finished. Absent when every requested output fails. Check each + * output's success field for its result. Valid captured pieces may be cached + * independently; failed retrievals and incomplete captures are not cached. */ isPartial?: true; From 6089a70b91d324a43defc18e539f5e6f1abc6114 Mon Sep 17 00:00:00 2001 From: contextualbeer Date: Sun, 27 Sep 2026 06:15:37 +0200 Subject: [PATCH 092/232] release: 3.2.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 17 +++++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 20 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index ada7355e..95a37e3e 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.1.0" + ".": "3.2.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 9685e5a5..21b367fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,22 @@ # Changelog +## [3.2.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.1.0...v3.2.0) (2026-09-27) + + +### Features + +* **feedback:** add agent feedback endpoint ([#1322](https://github.com/context-dot-dev/context-typescript-sdk/issues/1322)) ([ccf8f08](https://github.com/context-dot-dev/context-typescript-sdk/commit/ccf8f08cec4db47eea9b49e3623fd375377f5b75)) +* **highlights:** preserve Markdown structure in scrape excerpts ([#1236](https://github.com/context-dot-dev/context-typescript-sdk/issues/1236)) ([503abec](https://github.com/context-dot-dev/context-typescript-sdk/commit/503abec171290eaab2c4fa97bfacffd28d4e70f3)) +* **scrape:** enable highlights with zero data retention ([#1246](https://github.com/context-dot-dev/context-typescript-sdk/issues/1246)) ([abfa08c](https://github.com/context-dot-dev/context-typescript-sdk/commit/abfa08c189f56daa91f53fd53fbf1b29ad58322d)) + + +### Bug Fixes + +* **openapi:** document exclusive news filters ([#1265](https://github.com/context-dot-dev/context-typescript-sdk/issues/1265)) ([b3b4267](https://github.com/context-dot-dev/context-typescript-sdk/commit/b3b4267a2b4452dc71546243888dc1333e30ef19)) +* **scrape:** only flag partial success when a requested format succeeds ([#1325](https://github.com/context-dot-dev/context-typescript-sdk/issues/1325)) ([b6d8483](https://github.com/context-dot-dev/context-typescript-sdk/commit/b6d848326f79ce7333f0299540976933420057d2)) +* **scrape:** preserve successful formats when other outputs fail ([#1263](https://github.com/context-dot-dev/context-typescript-sdk/issues/1263)) ([a31d02e](https://github.com/context-dot-dev/context-typescript-sdk/commit/a31d02e8c30a229cfd8b0fa0f3aa79ed9f301f10)) +* **scrape:** retain highlight headings only when needed ([#1245](https://github.com/context-dot-dev/context-typescript-sdk/issues/1245)) ([54b38a5](https://github.com/context-dot-dev/context-typescript-sdk/commit/54b38a5dec14bd25540894b112826262d175c620)) + ## [3.1.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.0.0...v3.1.0) (2026-09-23) diff --git a/package.json b/package.json index defbbea0..500c5e4b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.1.0", + "version": "3.2.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index cc0b2a97..9ca3e095 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.1.0'; // x-release-please-version +export const VERSION = '3.2.0'; // x-release-please-version From 3abeb7b9aecff74a4d98e489f3075e365af60423 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 27 Sep 2026 08:53:08 +0000 Subject: [PATCH 093/232] seal --- .release-please-manifest.json | 2 +- CHANGELOG.md | 17 + package.json | 2 +- src/client.ts | 8 +- src/resources/batch.ts | 330 +++--- src/resources/brand.ts | 179 +-- src/resources/feedback.ts | 18 +- src/resources/industry.ts | 86 +- src/resources/logs.ts | 54 +- src/resources/monitors.ts | 1648 +++++++++++++++++--------- src/resources/news.ts | 36 +- src/resources/parse.ts | 31 +- src/resources/people.ts | 115 +- src/resources/utility.ts | 40 +- src/resources/web.ts | 805 ++++++------- src/resources/webhooks/deliveries.ts | 86 +- src/version.ts | 2 +- tests/api-resources/news.test.ts | 4 +- tests/api-resources/utility.test.ts | 4 +- tests/api-resources/web.test.ts | 10 +- 20 files changed, 1866 insertions(+), 1611 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index ada7355e..95a37e3e 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.1.0" + ".": "3.2.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 9685e5a5..21b367fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,22 @@ # Changelog +## [3.2.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.1.0...v3.2.0) (2026-09-27) + + +### Features + +* **feedback:** add agent feedback endpoint ([#1322](https://github.com/context-dot-dev/context-typescript-sdk/issues/1322)) ([ccf8f08](https://github.com/context-dot-dev/context-typescript-sdk/commit/ccf8f08cec4db47eea9b49e3623fd375377f5b75)) +* **highlights:** preserve Markdown structure in scrape excerpts ([#1236](https://github.com/context-dot-dev/context-typescript-sdk/issues/1236)) ([503abec](https://github.com/context-dot-dev/context-typescript-sdk/commit/503abec171290eaab2c4fa97bfacffd28d4e70f3)) +* **scrape:** enable highlights with zero data retention ([#1246](https://github.com/context-dot-dev/context-typescript-sdk/issues/1246)) ([abfa08c](https://github.com/context-dot-dev/context-typescript-sdk/commit/abfa08c189f56daa91f53fd53fbf1b29ad58322d)) + + +### Bug Fixes + +* **openapi:** document exclusive news filters ([#1265](https://github.com/context-dot-dev/context-typescript-sdk/issues/1265)) ([b3b4267](https://github.com/context-dot-dev/context-typescript-sdk/commit/b3b4267a2b4452dc71546243888dc1333e30ef19)) +* **scrape:** only flag partial success when a requested format succeeds ([#1325](https://github.com/context-dot-dev/context-typescript-sdk/issues/1325)) ([b6d8483](https://github.com/context-dot-dev/context-typescript-sdk/commit/b6d848326f79ce7333f0299540976933420057d2)) +* **scrape:** preserve successful formats when other outputs fail ([#1263](https://github.com/context-dot-dev/context-typescript-sdk/issues/1263)) ([a31d02e](https://github.com/context-dot-dev/context-typescript-sdk/commit/a31d02e8c30a229cfd8b0fa0f3aa79ed9f301f10)) +* **scrape:** retain highlight headings only when needed ([#1245](https://github.com/context-dot-dev/context-typescript-sdk/issues/1245)) ([54b38a5](https://github.com/context-dot-dev/context-typescript-sdk/commit/54b38a5dec14bd25540894b112826262d175c620)) + ## [3.1.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.0.0...v3.1.0) (2026-09-23) diff --git a/package.json b/package.json index defbbea0..500c5e4b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.1.0", + "version": "3.2.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/client.ts b/src/client.ts index 1f9e2d36..f8ca469f 100644 --- a/src/client.ts +++ b/src/client.ts @@ -824,7 +824,7 @@ export class ContextDev { industry: API.Industry = new API.Industry(this); utility: API.Utility = new API.Utility(this); /** - * Monitor pages, sitemaps, and extracted website data for exact or semantic changes. Webhook payloads are documented by the MonitorsChangeDetectedWebhookPayload and MonitorsRunCompletedWebhookPayload schemas. + * Watch websites for exact or meaningful changes. */ monitors: API.Monitors = new API.Monitors(this); /** @@ -834,15 +834,15 @@ export class ContextDev { webhooks: API.Webhooks = new API.Webhooks(this); people: API.People = new API.People(this); /** - * Search live first-party RSS and free historical news data by company identity. + * Search live and historical news about a company. */ news: API.News = new API.News(this); /** - * Read your organization's API request logs to debug failed calls. These endpoints cost no credits and use a separate rate limit. + * Read your organization's API request logs. */ logs: API.Logs = new API.Logs(this); /** - * Report bugs, docs mismatches, and friction with any Context.dev API. Submissions cost no credits and use a separate rate limit. + * Report API issues and documentation mismatches. */ feedback: API.Feedback = new API.Feedback(this); } diff --git a/src/resources/batch.ts b/src/resources/batch.ts index afc77b45..011368c2 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -13,7 +13,8 @@ import { path } from '../internal/utils/path'; */ export class Batch extends APIResource { /** - * Check progress, and get download links once the batch finishes. + * Get batch progress and result download links. Result files are deleted 7 days + * after the batch finishes. * * @example * ```ts @@ -25,8 +26,7 @@ export class Batch extends APIResource { } /** - * List your batches from newest to oldest. Filter by status or continue with a - * cursor. + * List your batches, newest first, with optional filters. * * @example * ```ts @@ -41,8 +41,8 @@ export class Batch extends APIResource { } /** - * Permanently delete a finished batch and its stored results. Active batches must - * settle first. + * Permanently delete a finished batch and its results. Its webhook deliveries can + * no longer be retried. * * @example * ```ts @@ -54,8 +54,8 @@ export class Batch extends APIResource { } /** - * Stop a batch from starting new pages. In-progress pages finish, and unused - * credits are refunded. + * Stop a batch from starting new pages. Pages already in progress finish before + * the batch becomes cancelled. * * @example * ```ts @@ -67,8 +67,8 @@ export class Batch extends APIResource { } /** - * Page through a finished batch's results as JSON instead of downloading the - * NDJSON files. + * Page through a finished batch’s results as JSON. Results remain available for 7 + * days. * * @example * ```ts @@ -86,7 +86,8 @@ export class Batch extends APIResource { } /** - * Scrape 25K URLs or crawl large websites asynchronously. + * Scrape up to 25,000 URLs, or crawl a site, asynchronously. Poll the batch ID or + * receive a webhook when it finishes. * * @example * ```ts @@ -157,8 +158,7 @@ export interface Failure { } /** - * The crawl controls as submitted, so the limits requested can be compared against - * what the crawl reached. + * Crawl settings as submitted. */ export interface CrawlControls { /** @@ -216,7 +216,7 @@ export namespace CrawlControls { } /** - * What submission took in, and what it charged for. + * What the submission accepted. */ export interface Intake { /** @@ -227,23 +227,17 @@ export interface Intake { duplicates: number; /** - * URLs from your list rejected as unusable; the same ones are itemised in - * `invalid_urls` at submission. Null for a crawl — a crawl that resolves no usable - * page is rejected outright with a 400 rather than accepted with an empty list. + * Rejected input URLs; `null` for a crawl. */ invalid: number | null; /** - * Pages credits were reserved for. Everything else — progress, the refund, the - * completion percentage — is measured against this. + * Pages accepted; progress counts toward this total. */ reserved: number; /** - * Whether `reserved` is an upper bound the batch may finish under. True only for a - * crawl that follows links, whose reachable page count is unknowable until it - * runs. False for a scrape and for a sitemap crawl, where `reserved` is an exact - * page count. + * True when `reserved` is a crawl ceiling; false when it is an exact URL count. */ reserved_is_ceiling: boolean; @@ -256,18 +250,17 @@ export interface Intake { export interface BatchRetrieveResponse { /** - * Batch ID used to retrieve or cancel the job. + * Batch ID. */ id: string; /** - * The crawl controls as submitted, so the limits requested can be compared against - * what the crawl reached. + * Crawl settings as submitted. */ crawl: CrawlControls | null; /** - * What this batch has done to your credit balance. + * Batch credit usage and settlement. */ credits: BatchRetrieveResponse.Credits; @@ -284,17 +277,17 @@ export interface BatchRetrieveResponse { format: 'markdown' | 'html'; /** - * What submission took in, and what it charged for. + * What the submission accepted. */ input: Intake; /** - * Rejected URLs, up to 100. These are not charged. + * Rejected URLs (first 100). */ invalid_urls: Array; /** - * How pages were selected. Matches `input.mode` on the submit request. + * `scrape` (URL list) or `crawl`. */ mode: 'scrape' | 'crawl'; @@ -310,14 +303,14 @@ export interface BatchRetrieveResponse { progress: BatchRetrieveResponse.Progress; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * 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. + * Result download links; null until the batch finishes. Files are deleted 7 days + * after the batch finishes. */ results: BatchRetrieveResponse.Results | null; @@ -346,30 +339,26 @@ export interface BatchRetrieveResponse { export namespace BatchRetrieveResponse { /** - * What this batch has done to your credit balance. + * Batch credit usage and settlement. */ export interface Credits { /** - * `reserved` minus `refunded` plus `ocr_charged` — what the batch has cost so far. - * Equal to `reserved` until the batch settles. + * `reserved` minus `refunded` plus `ocr_charged`. */ net: number; /** - * Credits charged for PDF pages recovered by OCR (pdf.ocr=true), 1 per recovered - * page, on top of `reserved`. Stays 0 until the batch settles. + * OCR usage charged when the batch settles. */ ocr_charged: number; /** - * Credits returned for pages that did not succeed. Stays 0 until the batch reaches - * a final status, then settles in one movement. + * Credits returned for unsuccessful pages when the batch settles. */ refunded: number; /** - * 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. + * Credits held when the batch was accepted. */ reserved: number; } @@ -396,9 +385,8 @@ export namespace BatchRetrieveResponse { failed: number; /** - * 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. + * Accepted pages not yet attempted. Unused crawl capacity is excluded after + * completion. */ pending: number; @@ -409,12 +397,12 @@ export namespace BatchRetrieveResponse { } /** - * 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. + * Result download links; null until the batch finishes. Files are deleted 7 days + * after the batch finishes. */ export interface Results { /** - * When the download URLs expire. + * When these links expire (24 hours after this response). */ expires_at: string; @@ -465,7 +453,7 @@ export namespace BatchRetrieveResponse { */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -478,8 +466,8 @@ export namespace BatchRetrieveResponse { export interface BatchListResponse { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -494,7 +482,7 @@ export interface BatchListResponse { has_more?: boolean; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: BatchListResponse.KeyMetadata; @@ -510,18 +498,17 @@ export namespace BatchListResponse { */ export interface Data { /** - * Batch ID used to retrieve or cancel the job. + * Batch ID. */ id: string; /** - * The crawl controls as submitted, so the limits requested can be compared against - * what the crawl reached. + * Crawl settings as submitted. */ crawl: BatchAPI.CrawlControls | null; /** - * What this batch has done to your credit balance. + * Batch credit usage and settlement. */ credits: Data.Credits; @@ -538,12 +525,12 @@ export namespace BatchListResponse { format: 'markdown' | 'html'; /** - * What submission took in, and what it charged for. + * What the submission accepted. */ input: BatchAPI.Intake; /** - * How pages were selected. Matches `input.mode` on the submit request. + * `scrape` (URL list) or `crawl`. */ mode: 'scrape' | 'crawl'; @@ -559,8 +546,8 @@ export namespace BatchListResponse { progress: Data.Progress; /** - * 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. + * Result download links; null until the batch finishes. Files are deleted 7 days + * after the batch finishes. */ results: Data.Results | null; @@ -579,30 +566,26 @@ export namespace BatchListResponse { export namespace Data { /** - * What this batch has done to your credit balance. + * Batch credit usage and settlement. */ export interface Credits { /** - * `reserved` minus `refunded` plus `ocr_charged` — what the batch has cost so far. - * Equal to `reserved` until the batch settles. + * `reserved` minus `refunded` plus `ocr_charged`. */ net: number; /** - * Credits charged for PDF pages recovered by OCR (pdf.ocr=true), 1 per recovered - * page, on top of `reserved`. Stays 0 until the batch settles. + * OCR usage charged when the batch settles. */ ocr_charged: number; /** - * Credits returned for pages that did not succeed. Stays 0 until the batch reaches - * a final status, then settles in one movement. + * Credits returned for unsuccessful pages when the batch settles. */ refunded: number; /** - * 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. + * Credits held when the batch was accepted. */ reserved: number; } @@ -617,9 +600,8 @@ export namespace BatchListResponse { failed: number; /** - * 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. + * Accepted pages not yet attempted. Unused crawl capacity is excluded after + * completion. */ pending: number; @@ -630,12 +612,12 @@ export namespace BatchListResponse { } /** - * 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. + * Result download links; null until the batch finishes. Files are deleted 7 days + * after the batch finishes. */ export interface Results { /** - * When the download URLs expire. + * When these links expire (24 hours after this response). */ expires_at: string; @@ -683,11 +665,11 @@ export namespace BatchListResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -700,8 +682,8 @@ export namespace BatchListResponse { export interface BatchDeleteResponse { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -716,18 +698,18 @@ export interface BatchDeleteResponse { deleted?: boolean; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: BatchDeleteResponse.KeyMetadata; } export namespace BatchDeleteResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -745,8 +727,7 @@ export interface BatchCancelResponse { id: string; /** - * The crawl controls as submitted, so the limits requested can be compared against - * what the crawl reached. + * Crawl settings as submitted. */ crawl: CrawlControls | null; @@ -761,7 +742,7 @@ export interface BatchCancelResponse { format: 'markdown' | 'html'; /** - * What submission took in, and what it charged for. + * What the submission accepted. */ input: Intake; @@ -781,8 +762,8 @@ export interface BatchCancelResponse { progress: BatchCancelResponse.Progress; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -798,7 +779,7 @@ export interface BatchCancelResponse { tags: Array; /** - * There is no finish time yet — the batch is still winding down. + * Batch timestamps. */ timing: BatchCancelResponse.Timing; @@ -814,8 +795,7 @@ export namespace BatchCancelResponse { */ export interface Credits { /** - * Credits debited at submission. The unspent remainder is refunded once the batch - * settles — read `credits.refunded` from GET /batch/{batch_id} then. + * Credits held at submission; unused credits are refunded when the batch settles. */ reserved: number; } @@ -830,7 +810,7 @@ export namespace BatchCancelResponse { failed: number; /** - * Reserved pages that will now be skipped, and refunded when the batch settles. + * Pages that will be skipped. */ pending: number; @@ -841,7 +821,7 @@ export namespace BatchCancelResponse { } /** - * There is no finish time yet — the batch is still winding down. + * Batch timestamps. */ export interface Timing { /** @@ -860,7 +840,7 @@ export namespace BatchCancelResponse { */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -873,8 +853,8 @@ export namespace BatchCancelResponse { export interface BatchGetResultsResponse { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -889,7 +869,7 @@ export interface BatchGetResultsResponse { has_more?: boolean; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: BatchGetResultsResponse.KeyMetadata; @@ -905,9 +885,7 @@ export namespace BatchGetResultsResponse { */ export interface Ok { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: Ok.CacheMetadata; @@ -943,7 +921,7 @@ export namespace BatchGetResultsResponse { html?: string; /** - * Caller-supplied identifier echoed from submission. + * Your `itemId` from submission. */ itemId?: string; @@ -958,17 +936,14 @@ export namespace BatchGetResultsResponse { meta?: { [key: string]: unknown }; /** - * PDF pages of this document recovered by OCR (pdf.ocr=true). Each recovered page - * bills 1 credit on top of the page base credit; absent when no OCR ran. + * Number of PDF pages recovered by OCR. Omitted when OCR did not run. */ ocr_pages?: number; } export namespace Ok { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -1152,7 +1127,7 @@ export namespace BatchGetResultsResponse { url: string; /** - * Caller-supplied identifier echoed from submission. + * Your `itemId` from submission. */ itemId?: string; @@ -1163,11 +1138,11 @@ export namespace BatchGetResultsResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -1185,15 +1160,12 @@ export interface BatchSubmitResponse { id: string; /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: BatchSubmitResponse.CacheMetadata; /** - * The crawl controls as submitted, so the limits requested can be compared against - * what the crawl reached. + * Crawl settings as submitted. */ crawl: CrawlControls | null; @@ -1213,12 +1185,12 @@ export interface BatchSubmitResponse { format: 'markdown' | 'html'; /** - * What submission took in, and what it charged for. + * What the submission accepted. */ input: Intake; /** - * Rejected URLs, up to 100. These are not charged. + * Rejected URLs (first 100). */ invalid_urls: Array; @@ -1228,8 +1200,8 @@ export interface BatchSubmitResponse { mode: 'scrape' | 'crawl'; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -1249,17 +1221,14 @@ export interface BatchSubmitResponse { key_metadata?: BatchSubmitResponse.KeyMetadata; /** - * Signing secret for the completion webhook, returned only here and never again. - * Store it now; it is not repeated by GET /batch/{batch_id}. + * Secret for verifying `X-Context-Signature`. Only submit returns it, so store it. */ webhook_secret?: string; } export namespace BatchSubmitResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -1279,8 +1248,7 @@ export namespace BatchSubmitResponse { */ export interface Credits { /** - * Credits just debited from your balance. Whatever the batch does not spend is - * refunded when it settles. + * Credits held at submission. */ reserved: number; } @@ -1302,7 +1270,7 @@ export namespace BatchSubmitResponse { */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -1372,8 +1340,8 @@ export interface BatchSubmitParams { tags?: Array; /** - * Body param: Completion webhook settings. Cannot be combined with webhookUrl. - * Omitting retry preserves legacy delivery; retry: {} opts into durable retries. + * Body param: Where to send the batch's final-status event. Omit `retry` for one + * attempt; `{}` uses the default retry schedule. */ webhook?: BatchSubmitParams.Webhook; @@ -1384,15 +1352,15 @@ export interface BatchSubmitParams { webhookUrl?: string; /** - * Header param: Any string unique to this submission. Retries with the same key - * return the original batch. + * Header param: Unique key per submission. Retrying with the same key and body + * returns the original batch; a different body returns `409`. */ 'Idempotency-Key'?: string; } export namespace BatchSubmitParams { /** - * Scrape up to 25K URLs in one batch. + * Scrape a list of up to 25,000 URLs. */ export interface Scrape { /** @@ -1454,8 +1422,7 @@ export namespace BatchSubmitParams { */ export interface Options { /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). + * Fetch from this country (ISO 3166-1 alpha-2). */ country?: | 'ad' @@ -1670,8 +1637,7 @@ export namespace BatchSubmitParams { excludeSelectors?: Array | null; /** - * Also include each page's HTML in its result record, as an `html` field alongside - * the Markdown. + * Also return each page's HTML in `html`. */ includeHTML?: boolean; @@ -1686,15 +1652,13 @@ export namespace BatchSubmitParams { includeLinks?: boolean; /** - * Keep only the subtrees matching these CSS selectors. Filtered pages are always - * fetched fresh, ignoring `maxAgeMs`. + * Keep only elements matching these CSS selectors. Filtered pages ignore + * `maxAgeMs`. */ includeSelectors?: Array | null; /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. */ maxAgeMs?: number | null; @@ -1705,8 +1669,7 @@ export namespace BatchSubmitParams { pdf?: Options.Pdf; /** - * Wait briefly for CSS and transition animations to settle before extraction, on - * pages that render in a browser. + * Wait for CSS animations to finish before extracting, on browser-rendered pages. */ settleAnimations?: boolean; @@ -1739,16 +1702,12 @@ export namespace BatchSubmitParams { end?: number; /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. When false, no OCR runs. + * Read scanned PDF pages with OCR; preserve pages that already have text. */ ocr?: boolean; /** - * When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and - * a 400 PDF_SKIPPED is returned. + * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. */ shouldParse?: boolean; @@ -1807,8 +1766,7 @@ export namespace BatchSubmitParams { */ export interface Options { /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). + * Fetch from this country (ISO 3166-1 alpha-2). */ country?: | 'ad' @@ -2023,15 +1981,13 @@ export namespace BatchSubmitParams { excludeSelectors?: Array | null; /** - * Keep only the subtrees matching these CSS selectors. Filtered pages are always - * fetched fresh, ignoring `maxAgeMs`. + * Keep only elements matching these CSS selectors. Filtered pages ignore + * `maxAgeMs`. */ includeSelectors?: Array | null; /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. */ maxAgeMs?: number | null; @@ -2042,8 +1998,7 @@ export namespace BatchSubmitParams { pdf?: Options.Pdf; /** - * Wait briefly for CSS and transition animations to settle before extraction, on - * pages that render in a browser. + * Wait for CSS animations to finish before extracting, on browser-rendered pages. */ settleAnimations?: boolean; @@ -2071,16 +2026,12 @@ export namespace BatchSubmitParams { end?: number; /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. When false, no OCR runs. + * Read scanned PDF pages with OCR; preserve pages that already have text. */ ocr?: boolean; /** - * When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and - * a 400 PDF_SKIPPED is returned. + * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. */ shouldParse?: boolean; @@ -2223,8 +2174,7 @@ export namespace BatchSubmitParams { */ export interface Options { /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). + * Fetch from this country (ISO 3166-1 alpha-2). */ country?: | 'ad' @@ -2439,8 +2389,7 @@ export namespace BatchSubmitParams { excludeSelectors?: Array | null; /** - * Also include each page's HTML in its result record, as an `html` field alongside - * the Markdown. + * Also return each page's HTML in `html`. */ includeHTML?: boolean; @@ -2455,15 +2404,13 @@ export namespace BatchSubmitParams { includeLinks?: boolean; /** - * Keep only the subtrees matching these CSS selectors. Filtered pages are always - * fetched fresh, ignoring `maxAgeMs`. + * Keep only elements matching these CSS selectors. Filtered pages ignore + * `maxAgeMs`. */ includeSelectors?: Array | null; /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. */ maxAgeMs?: number | null; @@ -2474,8 +2421,7 @@ export namespace BatchSubmitParams { pdf?: Options.Pdf; /** - * Wait briefly for CSS and transition animations to settle before extraction, on - * pages that render in a browser. + * Wait for CSS animations to finish before extracting, on browser-rendered pages. */ settleAnimations?: boolean; @@ -2508,16 +2454,12 @@ export namespace BatchSubmitParams { end?: number; /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. When false, no OCR runs. + * Read scanned PDF pages with OCR; preserve pages that already have text. */ ocr?: boolean; /** - * When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and - * a 400 PDF_SKIPPED is returned. + * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. */ shouldParse?: boolean; @@ -2643,8 +2585,7 @@ export namespace BatchSubmitParams { */ export interface Options { /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). + * Fetch from this country (ISO 3166-1 alpha-2). */ country?: | 'ad' @@ -2859,15 +2800,13 @@ export namespace BatchSubmitParams { excludeSelectors?: Array | null; /** - * Keep only the subtrees matching these CSS selectors. Filtered pages are always - * fetched fresh, ignoring `maxAgeMs`. + * Keep only elements matching these CSS selectors. Filtered pages ignore + * `maxAgeMs`. */ includeSelectors?: Array | null; /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. */ maxAgeMs?: number | null; @@ -2878,8 +2817,7 @@ export namespace BatchSubmitParams { pdf?: Options.Pdf; /** - * Wait briefly for CSS and transition animations to settle before extraction, on - * pages that render in a browser. + * Wait for CSS animations to finish before extracting, on browser-rendered pages. */ settleAnimations?: boolean; @@ -2907,16 +2845,12 @@ export namespace BatchSubmitParams { end?: number; /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. When false, no OCR runs. + * Read scanned PDF pages with OCR; preserve pages that already have text. */ ocr?: boolean; /** - * When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and - * a 400 PDF_SKIPPED is returned. + * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. */ shouldParse?: boolean; @@ -2930,10 +2864,14 @@ export namespace BatchSubmitParams { } /** - * Completion webhook settings. Cannot be combined with webhookUrl. Omitting retry - * preserves legacy delivery; retry: {} opts into durable retries. + * Where to send the batch's final-status event. Omit `retry` for one attempt; `{}` + * uses the default retry schedule. */ export interface Webhook { + /** + * Public HTTP(S) URL that receives batch completion, failure, or cancellation + * events. + */ url: string; /** diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 28b9c457..34aba28d 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -6,11 +6,8 @@ import { RequestOptions } from '../internal/request-options'; export class Brand extends APIResource { /** - * Retrieve logos, backdrops, colors, industry, description, and more. Provide - * exactly one lookup identifier in the request body: a domain, company name, email - * address, stock ticker, transaction descriptor, or direct URL. Note: - * `by_direct_url` fetches brand data only from the provided URL — not from the - * entire internet. + * Retrieve logos, colors, company details, and social links using one lookup + * identifier. A direct URL limits extraction to that page. * * @example * ```ts @@ -25,7 +22,8 @@ export class Brand extends APIResource { } /** - * Search indexed brands by name or domain + * Find up to 10 brands by name or domain, ordered by popularity. Use the returned + * domain to retrieve a full brand profile. * * @example * ```ts @@ -44,9 +42,7 @@ export interface BrandRetrieveResponse { brand: BrandRetrieveResponse.Brand; /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: BrandRetrieveResponse.CacheMetadata; @@ -56,18 +52,18 @@ export interface BrandRetrieveResponse { code: number; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Status of the response, e.g., 'ok' + * Always `ok` on success. */ status: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: BrandRetrieveResponse.KeyMetadata; @@ -146,7 +142,7 @@ export namespace BrandRetrieveResponse { phone?: string; /** - * Language to force for the retrieved brand data. + * Language, e.g. `english`. */ primary_language?: | 'afrikaans' @@ -754,7 +750,7 @@ export namespace BrandRetrieveResponse { type?: 'icon' | 'logo'; /** - * CDN hosted url of the logo (ready for display) + * Hosted logo URL. */ url?: string; } @@ -854,9 +850,7 @@ export namespace BrandRetrieveResponse { } /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -872,11 +866,11 @@ export namespace BrandRetrieveResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -889,8 +883,8 @@ export namespace BrandRetrieveResponse { export interface BrandSearchResponse { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -901,7 +895,7 @@ export interface BrandSearchResponse { results: Array; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: BrandSearchResponse.KeyMetadata; } @@ -926,11 +920,11 @@ export namespace BrandSearchResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -1085,10 +1079,8 @@ export declare namespace BrandRetrieveParams { | null; /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. + * Maximum age of cached brand data in ms. Defaults to 3 months; clamped to 0–1 + * year. `0` refreshes. */ maxAgeMs?: number; @@ -1100,35 +1092,29 @@ export declare namespace BrandRetrieveParams { maxSpeed?: boolean; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveByDomainRequest.TimeoutOpts; } export namespace BrandRetrieveByDomainRequest { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -1275,10 +1261,8 @@ export declare namespace BrandRetrieveParams { | null; /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. + * Maximum age of cached brand data in ms. Defaults to 3 months; clamped to 0–1 + * year. `0` refreshes. */ maxAgeMs?: number; @@ -1290,35 +1274,29 @@ export declare namespace BrandRetrieveParams { maxSpeed?: boolean; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveByNameRequest.TimeoutOpts; } export namespace BrandRetrieveByNameRequest { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -1459,10 +1437,8 @@ export declare namespace BrandRetrieveParams { | null; /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. + * Maximum age of cached brand data in ms. Defaults to 3 months; clamped to 0–1 + * year. `0` refreshes. */ maxAgeMs?: number; @@ -1474,35 +1450,29 @@ export declare namespace BrandRetrieveParams { maxSpeed?: boolean; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveByEmailRequest.TimeoutOpts; } export namespace BrandRetrieveByEmailRequest { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -1643,10 +1613,8 @@ export declare namespace BrandRetrieveParams { | null; /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. + * Maximum age of cached brand data in ms. Defaults to 3 months; clamped to 0–1 + * year. `0` refreshes. */ maxAgeMs?: number; @@ -1658,7 +1626,7 @@ export declare namespace BrandRetrieveParams { maxSpeed?: boolean; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; @@ -1668,30 +1636,24 @@ export declare namespace BrandRetrieveParams { ticker_exchange?: string; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveByTickerRequest.TimeoutOpts; } export namespace BrandRetrieveByTickerRequest { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -1711,35 +1673,29 @@ export declare namespace BrandRetrieveParams { type: 'by_direct_url'; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveByDirectURLRequest.TimeoutOpts; } export namespace BrandRetrieveByDirectURLRequest { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -1915,35 +1871,29 @@ export declare namespace BrandRetrieveParams { phone?: string | number; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveFromTransactionRequest.TimeoutOpts; } export namespace BrandRetrieveFromTransactionRequest { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -1970,8 +1920,7 @@ export interface BrandSearchParams { queryBy?: Array<'name' | 'domain'>; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; diff --git a/src/resources/feedback.ts b/src/resources/feedback.ts index 37a82437..5e1ffdd2 100644 --- a/src/resources/feedback.ts +++ b/src/resources/feedback.ts @@ -5,12 +5,12 @@ import { APIPromise } from '../core/api-promise'; import { RequestOptions } from '../internal/request-options'; /** - * Report bugs, docs mismatches, and friction with any Context.dev API. Submissions cost no credits and use a separate rate limit. + * Report API issues and documentation mismatches. */ export class Feedback extends APIResource { /** - * Report a problem with a Context.dev API call, docs page, SDK, or CLI. Include - * request_id, url, or both. + * Report an API issue or documentation mismatch, including request IDs when + * available. * * @example * ```ts @@ -40,24 +40,24 @@ export interface FeedbackSubmitResponse { feedback_id: string; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: FeedbackSubmitResponse.KeyMetadata; } export namespace FeedbackSubmitResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -86,7 +86,7 @@ export interface FeedbackSubmitParams { request_id?: string; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; diff --git a/src/resources/industry.ts b/src/resources/industry.ts index 3beac749..a82ba60d 100644 --- a/src/resources/industry.ts +++ b/src/resources/industry.ts @@ -6,7 +6,7 @@ import { RequestOptions } from '../internal/request-options'; export class Industry extends APIResource { /** - * Classify any brand into 2022 NAICS industry codes from its domain or name. + * Classify a company into NAICS industry codes. */ retrieveNaics( query: IndustryRetrieveNaicsParams, @@ -16,9 +16,7 @@ export class Industry extends APIResource { } /** - * Classify any brand into Standard Industrial Classification (SIC) codes from its - * domain or name. Choose between the original SIC system (`original_sic`) or the - * latest SIC list maintained by the SEC (`latest_sec`). + * Classify a company into SIC industry codes. */ retrieveSic( query: IndustryRetrieveSicParams, @@ -30,8 +28,8 @@ export class Industry extends APIResource { export interface IndustryRetrieveNaicsResponse { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -46,7 +44,7 @@ export interface IndustryRetrieveNaicsResponse { domain?: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: IndustryRetrieveNaicsResponse.KeyMetadata; @@ -57,7 +55,7 @@ export interface IndustryRetrieveNaicsResponse { partial?: boolean; /** - * Status of the response, e.g., 'ok' + * Always `ok` on success. */ status?: string; @@ -86,11 +84,11 @@ export namespace IndustryRetrieveNaicsResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -103,8 +101,8 @@ export namespace IndustryRetrieveNaicsResponse { export interface IndustryRetrieveSicResponse { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -126,7 +124,7 @@ export interface IndustryRetrieveSicResponse { domain?: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: IndustryRetrieveSicResponse.KeyMetadata; @@ -137,7 +135,7 @@ export interface IndustryRetrieveSicResponse { partial?: boolean; /** - * Status of the response, e.g., 'ok' + * Always `ok` on success. */ status?: string; @@ -184,11 +182,11 @@ export namespace IndustryRetrieveSicResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -219,45 +217,35 @@ export interface IndustryRetrieveNaicsParams { minResults?: number; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: IndustryRetrieveNaicsParams.TimeoutOpts; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace IndustryRetrieveNaicsParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -282,52 +270,40 @@ export interface IndustryRetrieveSicParams { minResults?: number; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: IndustryRetrieveSicParams.TimeoutOpts; /** - * Which SIC dataset to classify against. `original_sic` uses the 1987 Standard - * Industrial Classification system; `latest_sec` uses the current SIC list as - * published by the SEC. Defaults to `original_sic`. + * SIC dataset: `original_sic` (1987) or `latest_sec` (current SEC list). */ type?: 'original_sic' | 'latest_sec'; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace IndustryRetrieveSicParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } diff --git a/src/resources/logs.ts b/src/resources/logs.ts index 74f00c5d..14f71a1c 100644 --- a/src/resources/logs.ts +++ b/src/resources/logs.ts @@ -6,19 +6,19 @@ import { RequestOptions } from '../internal/request-options'; import { path } from '../internal/utils/path'; /** - * Read your organization's API request logs to debug failed calls. These endpoints cost no credits and use a separate rate limit. + * Read your organization's API request logs. */ export class Logs extends APIResource { /** - * Get one logged API call, including its request input and response body. + * Retrieve a request’s metadata, retained input, and response. */ retrieve(requestID: string, options?: RequestOptions): APIPromise { return this._client.get(path`/logs/${requestID}`, options); } /** - * List your organization's API requests, newest first. Defaults to the last 24 - * hours. + * List your organization’s request logs with filters and pagination. Logs also + * include batch settlements and monitor runs. */ list(query: LogListParams | null | undefined = {}, options?: RequestOptions): APIPromise { return this._client.get('/logs', { query, ...options }); @@ -29,13 +29,13 @@ export interface LogRetrieveResponse { data: LogRetrieveResponse.Data; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: LogRetrieveResponse.KeyMetadata; } @@ -68,7 +68,8 @@ export namespace LogRetrieveResponse { latency_ms: number; /** - * HTTP method. + * HTTP method, or `MONITOR` / `BATCH` for monitor-run and batch-settlement + * entries. */ method: string; @@ -107,11 +108,6 @@ export namespace LogRetrieveResponse { */ zdr: boolean; - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: Data.KeyMetadata; - /** * The retained JSON response with credentials redacted, or null when unavailable. */ @@ -133,29 +129,14 @@ export namespace LogRetrieveResponse { */ body?: unknown; } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -188,13 +169,13 @@ export interface LogListResponse { page: number; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: LogListResponse.KeyMetadata; } @@ -222,7 +203,8 @@ export namespace LogListResponse { latency_ms: number; /** - * HTTP method. + * HTTP method, or `MONITOR` / `BATCH` for monitor-run and batch-settlement + * entries. */ method: string; @@ -258,11 +240,11 @@ export namespace LogListResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index b54dd5bb..11bd5eb5 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -8,13 +8,12 @@ import { RequestOptions } from '../internal/request-options'; import { path } from '../internal/utils/path'; /** - * Monitor pages, sitemaps, and extracted website data for exact or semantic changes. Webhook payloads are documented by the MonitorsChangeDetectedWebhookPayload and MonitorsRunCompletedWebhookPayload schemas. + * Watch websites for exact or meaningful changes. */ export class Monitors extends APIResource { /** - * Creates a monitor. The request body is a union of the supported target/change - * detection combinations. The monitor runs immediately after creation to create - * its initial baseline. + * Watch a page, URL inventory, or extracted website data on a schedule. A run + * starts immediately to capture the baseline. * * @example * ```ts @@ -37,7 +36,7 @@ export class Monitors extends APIResource { } /** - * Get a monitor + * Retrieve a monitor’s configuration and current state. * * @example * ```ts @@ -49,9 +48,8 @@ export class Monitors extends APIResource { } /** - * Updates a monitor. If `target` or `change_detection` changes, the monitor - * creates a new baseline. Unsupported target/change detection combinations are - * rejected. + * Update a monitor. Changing its target or change detection replaces the baseline + * and queues a new baseline run. * * @example * ```ts @@ -76,9 +74,7 @@ export class Monitors extends APIResource { } /** - * Lists monitors for the authenticated organization. Supports free-text search - * (`q` over `search_by` fields, `prefix` or `exact` via `search_type`) plus - * status/type/tag filters. Results are paginated via the opaque `cursor`. + * List your monitors with optional search and filters. * * @example * ```ts @@ -93,7 +89,7 @@ export class Monitors extends APIResource { } /** - * Delete a monitor + * Delete a monitor and stop future runs and webhook retries. * * @example * ```ts @@ -105,8 +101,8 @@ export class Monitors extends APIResource { } /** - * Returns credits charged per monitor over an optional [since, until] window, - * newest spenders first. + * Return usage per monitor, highest first, for up to the 10,000 most recent runs + * in the requested window. * * @example * ```ts @@ -121,7 +117,7 @@ export class Monitors extends APIResource { } /** - * Returns how many monitors the account has and the maximum it allows. + * Retrieve your organization’s monitor allowance and usage. * * @example * ```ts @@ -133,7 +129,7 @@ export class Monitors extends APIResource { } /** - * Returns an account-wide feed of detected changes across monitors. + * List full change records across your monitors, newest first. * * @example * ```ts @@ -148,7 +144,7 @@ export class Monitors extends APIResource { } /** - * Returns an account-wide feed of monitor runs across all monitors. + * List runs across your monitors, newest first. * * @example * ```ts @@ -163,7 +159,7 @@ export class Monitors extends APIResource { } /** - * List changes for a monitor + * List full change records for a monitor, newest first. * * @example * ```ts @@ -181,7 +177,7 @@ export class Monitors extends APIResource { } /** - * List monitor runs + * List a monitor’s runs, newest first. * * @example * ```ts @@ -197,7 +193,7 @@ export class Monitors extends APIResource { } /** - * Get a change + * Retrieve a detected change, including its diff and available evidence. * * @example * ```ts @@ -211,8 +207,7 @@ export class Monitors extends APIResource { } /** - * Fetches one run for a monitor, including lifecycle status, timing, credits - * charged, and any detected change. + * Retrieve the status, timing, and results of one monitor run. * * @example * ```ts @@ -232,9 +227,8 @@ export class Monitors extends APIResource { } /** - * Generates a new signing secret for the monitor's webhook and returns the updated - * monitor (including the new `webhook.secret`). The previous secret stops signing - * deliveries immediately, so update your endpoint before rotating. + * Generate and return a new signing secret. It takes effect immediately for all + * subsequent delivery attempts. * * @example * ```ts @@ -251,8 +245,7 @@ export class Monitors extends APIResource { } /** - * Triggers an immediate run of the monitor outside its normal schedule. The run is - * queued and processed asynchronously. + * Queue a run without changing the regular schedule. Paused monitors return 409. * * @example * ```ts @@ -287,9 +280,7 @@ export interface WebhookDelivery { http_status: number | null; /** - * Delivery outcome. delivered means any 2xx response; rejected means a non-2xx - * response; failed means no HTTP response was received; skipped_unsafe_url means - * the URL failed the public-endpoint safety check. + * Outcome of the delivery attempt. Any 2xx response counts as delivered. */ status: 'delivered' | 'rejected' | 'failed' | 'skipped_unsafe_url'; @@ -307,15 +298,12 @@ export namespace WebhookDelivery { } } -/** - * A newly created monitor plus `initial_run_id`, the id of the baseline run queued - * at creation. - */ export interface MonitorCreateResponse { id: string; /** - * Discriminated union describing how changes are detected. + * How changes are judged. Defaults to `semantic` for extract targets and page + * targets with `instructions`, otherwise `exact`. */ change_detection: | MonitorCreateResponse.MonitorsExactChangeDetection @@ -324,38 +312,32 @@ export interface MonitorCreateResponse { created_at: string; /** - * The baseline run queued by this create call, or null if it could not be queued - * immediately (in which case the baseline runs on the next scheduled tick). Poll - * GET /monitors/{monitor_id}/runs/{run_id}. + * ID of the baseline run queued at creation; null if it will start on the next + * scheduled tick. */ initial_run_id: string | null; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; name: string; /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ - schedule: MonitorCreateResponse.Schedule; + request_id: string; /** - * Monitor lifecycle status. `failed` means the most recent run failed (see the - * monitor's `last_error`); failed monitors keep running on schedule and flip back - * to `active` on the next successful run. Monitors are auto-`paused` after - * repeated consecutive failures or insufficient-credit skips; resume by PATCHing - * status to `active`. + * Current state. Failed monitors keep running; paused monitors must be resumed + * with `status: "active"`. */ status: 'active' | 'paused' | 'failed'; /** - * Discriminated union describing what the monitor watches. + * What to watch: a page, a sitemap, or data extracted from a site. */ target: | MonitorCreateResponse.MonitorsPageTarget @@ -365,10 +347,8 @@ export interface MonitorCreateResponse { updated_at: string; /** - * Current baseline: the last observed value the monitor compares new snapshots - * against. Its shape follows `target.type` (page/sitemap/extract). Only populated - * on GET /monitors/{monitor_id}; null until the first baseline run completes (and - * after a target or change_detection update, which resets the baseline). + * Comparison baseline, included on Retrieve. Null until capture completes or after + * target changes. */ baseline?: | MonitorCreateResponse.MonitorsPageBaseline @@ -376,6 +356,11 @@ export interface MonitorCreateResponse { | MonitorCreateResponse.MonitorsExtractBaseline | null; + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorCreateResponse.KeyMetadata; + last_change_at?: string | null; /** @@ -386,16 +371,25 @@ export interface MonitorCreateResponse { last_run_at?: string | null; /** - * When the next scheduled run is due. + * When the next scheduled run is due; null while paused. */ next_run_at?: string | null; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + schedule?: MonitorCreateResponse.Schedule; + + /** + * Labels for filtering monitors, their changes, and their usage. */ tags?: Array; + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ webhook?: MonitorCreateResponse.Webhook | null; /** @@ -412,37 +406,26 @@ export namespace MonitorCreateResponse { * sitemap targets, this means URL additions and removals. */ export interface MonitorsExactChangeDetection { + /** + * Use `exact` to compare visible text or sitemap URLs. + */ type: 'exact'; } /** - * Detect meaning-level changes to page content, ignoring cosmetic or - * instruction-irrelevant differences. Which changes are meaningful is judged - * against the page or extract target's `instructions` (and an extract target's - * `schema`, when provided). + * Detect meaningful content changes using the target’s instructions and optional + * schema. */ export interface MonitorsSemanticChangeDetection { + /** + * Use `semantic` to judge changes against the target instructions. + */ type: 'semantic'; - confidence_threshold?: number; - } - - /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. - */ - export interface Schedule { /** - * Number of units between runs. The resulting interval (frequency × unit) must be - * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; - * maximum 365 when unit is days). + * Minimum confidence required to report a meaningful change, from 0 to 1. */ - frequency: number; - - type: 'interval'; - - unit: 'minutes' | 'hours' | 'days'; + confidence_threshold?: number; } /** @@ -450,24 +433,24 @@ export namespace MonitorCreateResponse { * detection judges confirmed stable diffs against `instructions`. */ export interface MonitorsPageTarget { + /** + * Use `page` to watch one web page. + */ type: 'page'; + /** + * Public HTTP(S) page URL to monitor. + */ url: string; /** - * CSS selectors for HTML regions to remove before text extraction. Applied after - * include_selectors; exclusion takes precedence when an element matches both. Omit - * or pass an empty array to apply no explicit exclusions. Changing these selectors - * creates a new baseline. + * Remove matching regions after inclusions. Changes create a new baseline. */ exclude_selectors?: Array; /** - * CSS selectors defining the HTML regions to monitor. Matching subtrees are - * combined in document order before text extraction, instead of automatic - * main-content selection. Omit or pass an empty array to use automatic - * main-content extraction. If the filtered page has no usable text, the run fails - * without replacing the baseline. Changing these selectors creates a new baseline. + * Monitor these CSS-selected regions. Empty or omitted uses main content. Changes + * create a new baseline. */ include_selectors?: Array; @@ -484,13 +467,12 @@ export namespace MonitorCreateResponse { } /** - * Watch a sitemap for URL additions and removals. Crawled URLs are normalized - * (lowercased host, no trailing slash/fragment) and scoped to the monitored site - * and its subdomains before comparison. On a detected difference the sitemap is - * re-fetched within the same run and only URLs both observations agree on are - * reported, suppressing transient crawl flaps. + * Watch a site’s URL inventory for confirmed additions and removals. */ export interface MonitorsSitemapTarget { + /** + * Use `sitemap` to watch a site for added or removed URLs. + */ type: 'sitemap'; /** @@ -515,11 +497,8 @@ export namespace MonitorCreateResponse { } /** - * Watch the monitor-relevant pages of a site for meaningful changes. A crawl - * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to - * track; each run re-checks exactly those pages, and confirmed content changes are - * judged for relevance against the monitor's `instructions` (and `schema`, when - * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + * Track relevant pages selected by `schema` and `instructions`; refresh the page + * set periodically. */ export interface MonitorsExtractTarget { /** @@ -528,6 +507,9 @@ export namespace MonitorCreateResponse { */ instructions: string; + /** + * Use `extract` to watch structured data across selected pages. + */ type: 'extract'; /** @@ -535,6 +517,9 @@ export namespace MonitorCreateResponse { */ url: string; + /** + * Allow page discovery on subdomains of the target site. + */ follow_subdomains?: boolean; /** @@ -548,14 +533,8 @@ export namespace MonitorCreateResponse { max_pages?: number; /** - * JSON Schema describing the data you care about. It is used three ways: it guides - * which pages are selected for tracking, it gives the change judge extra context - * on which changes matter (alongside `instructions`), and it defines the shape of - * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most - * about once a day). It is not a response format for changes: change events and - * webhook payloads always contain diffs, summaries, and evidence excerpts — never - * data in this schema's shape. If omitted, a default summary + key-points schema - * is used. + * JSON Schema for page selection and the baseline snapshot. Changes return diffs + * and evidence. */ schema?: { [key: string]: unknown }; } @@ -607,10 +586,8 @@ export namespace MonitorCreateResponse { captured_at: string; /** - * The extracted structured data, matching the monitor's extraction schema (same - * shape as the /web/extract endpoint's `data`). Refreshed when the monitor - * re-discovers its page set (at most about once a day); `null` when no extraction - * has been captured yet. + * Latest structured snapshot matching the extraction schema, refreshed at most + * daily; `null` before capture. */ data: unknown; @@ -620,6 +597,21 @@ export namespace MonitorCreateResponse { urls_analyzed: Array; } + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } + /** * Error from the most recent failed run; null when the last run succeeded. */ @@ -629,18 +621,43 @@ export namespace MonitorCreateResponse { message: string; } + /** + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + export interface Schedule { + /** + * Number of units between runs. The resulting interval (frequency × unit) must be + * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; + * maximum 365 when unit is days). + */ + frequency: number; + + /** + * Use `interval` to run on a repeating schedule. + */ + type: 'interval'; + + /** + * Time unit used with `frequency` to set the run interval. + */ + unit: 'minutes' | 'hours' | 'days'; + } + + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ export interface Webhook { /** - * Webhook URL events are delivered to. Slack incoming webhook URLs are - * automatically formatted as Slack messages. + * Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted + * messages. */ url: string; /** - * Events delivered to this endpoint. `change.detected` fires only when a run - * detects a change; `run.completed` fires on every completed run — including runs - * that detected no change — and embeds the change when one was detected. Defaults - * to `["change.detected"]` when omitted. + * Events to deliver. Defaults to `change.detected`; `run.completed` also includes + * unchanged runs. */ events?: Array<'change.detected' | 'run.completed'>; @@ -650,12 +667,8 @@ export namespace MonitorCreateResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Omitted unless the API key - * has monitors:write permission or full access. Each delivery includes an - * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over - * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time - * compare and reject stale timestamps to prevent replay. Generated by the API; - * cannot be set by clients. + * API-generated signing secret. Visible only with full access or `monitors:write` + * permission. */ secret?: string; } @@ -687,15 +700,12 @@ export namespace MonitorCreateResponse { } } -/** - * A web monitor. `mode` is the constant `web`; behavior is described by `target` - * (page/sitemap/extract) and `change_detection` (exact/semantic). - */ export interface MonitorRetrieveResponse { id: string; /** - * Discriminated union describing how changes are detected. + * How changes are judged. Defaults to `semantic` for extract targets and page + * targets with `instructions`, otherwise `exact`. */ change_detection: | MonitorRetrieveResponse.MonitorsExactChangeDetection @@ -704,31 +714,26 @@ export interface MonitorRetrieveResponse { created_at: string; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; name: string; /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ - schedule: MonitorRetrieveResponse.Schedule; + request_id: string; /** - * Monitor lifecycle status. `failed` means the most recent run failed (see the - * monitor's `last_error`); failed monitors keep running on schedule and flip back - * to `active` on the next successful run. Monitors are auto-`paused` after - * repeated consecutive failures or insufficient-credit skips; resume by PATCHing - * status to `active`. + * Current state. Failed monitors keep running; paused monitors must be resumed + * with `status: "active"`. */ status: 'active' | 'paused' | 'failed'; /** - * Discriminated union describing what the monitor watches. + * What to watch: a page, a sitemap, or data extracted from a site. */ target: | MonitorRetrieveResponse.MonitorsPageTarget @@ -738,10 +743,8 @@ export interface MonitorRetrieveResponse { updated_at: string; /** - * Current baseline: the last observed value the monitor compares new snapshots - * against. Its shape follows `target.type` (page/sitemap/extract). Only populated - * on GET /monitors/{monitor_id}; null until the first baseline run completes (and - * after a target or change_detection update, which resets the baseline). + * Comparison baseline, included on Retrieve. Null until capture completes or after + * target changes. */ baseline?: | MonitorRetrieveResponse.MonitorsPageBaseline @@ -749,6 +752,11 @@ export interface MonitorRetrieveResponse { | MonitorRetrieveResponse.MonitorsExtractBaseline | null; + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorRetrieveResponse.KeyMetadata; + last_change_at?: string | null; /** @@ -759,16 +767,25 @@ export interface MonitorRetrieveResponse { last_run_at?: string | null; /** - * When the next scheduled run is due. + * When the next scheduled run is due; null while paused. */ next_run_at?: string | null; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + schedule?: MonitorRetrieveResponse.Schedule; + + /** + * Labels for filtering monitors, their changes, and their usage. */ tags?: Array; + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ webhook?: MonitorRetrieveResponse.Webhook | null; /** @@ -785,37 +802,26 @@ export namespace MonitorRetrieveResponse { * sitemap targets, this means URL additions and removals. */ export interface MonitorsExactChangeDetection { + /** + * Use `exact` to compare visible text or sitemap URLs. + */ type: 'exact'; } /** - * Detect meaning-level changes to page content, ignoring cosmetic or - * instruction-irrelevant differences. Which changes are meaningful is judged - * against the page or extract target's `instructions` (and an extract target's - * `schema`, when provided). + * Detect meaningful content changes using the target’s instructions and optional + * schema. */ export interface MonitorsSemanticChangeDetection { + /** + * Use `semantic` to judge changes against the target instructions. + */ type: 'semantic'; - confidence_threshold?: number; - } - - /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. - */ - export interface Schedule { /** - * Number of units between runs. The resulting interval (frequency × unit) must be - * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; - * maximum 365 when unit is days). + * Minimum confidence required to report a meaningful change, from 0 to 1. */ - frequency: number; - - type: 'interval'; - - unit: 'minutes' | 'hours' | 'days'; + confidence_threshold?: number; } /** @@ -823,24 +829,24 @@ export namespace MonitorRetrieveResponse { * detection judges confirmed stable diffs against `instructions`. */ export interface MonitorsPageTarget { + /** + * Use `page` to watch one web page. + */ type: 'page'; + /** + * Public HTTP(S) page URL to monitor. + */ url: string; /** - * CSS selectors for HTML regions to remove before text extraction. Applied after - * include_selectors; exclusion takes precedence when an element matches both. Omit - * or pass an empty array to apply no explicit exclusions. Changing these selectors - * creates a new baseline. + * Remove matching regions after inclusions. Changes create a new baseline. */ exclude_selectors?: Array; /** - * CSS selectors defining the HTML regions to monitor. Matching subtrees are - * combined in document order before text extraction, instead of automatic - * main-content selection. Omit or pass an empty array to use automatic - * main-content extraction. If the filtered page has no usable text, the run fails - * without replacing the baseline. Changing these selectors creates a new baseline. + * Monitor these CSS-selected regions. Empty or omitted uses main content. Changes + * create a new baseline. */ include_selectors?: Array; @@ -857,13 +863,12 @@ export namespace MonitorRetrieveResponse { } /** - * Watch a sitemap for URL additions and removals. Crawled URLs are normalized - * (lowercased host, no trailing slash/fragment) and scoped to the monitored site - * and its subdomains before comparison. On a detected difference the sitemap is - * re-fetched within the same run and only URLs both observations agree on are - * reported, suppressing transient crawl flaps. + * Watch a site’s URL inventory for confirmed additions and removals. */ export interface MonitorsSitemapTarget { + /** + * Use `sitemap` to watch a site for added or removed URLs. + */ type: 'sitemap'; /** @@ -888,11 +893,8 @@ export namespace MonitorRetrieveResponse { } /** - * Watch the monitor-relevant pages of a site for meaningful changes. A crawl - * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to - * track; each run re-checks exactly those pages, and confirmed content changes are - * judged for relevance against the monitor's `instructions` (and `schema`, when - * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + * Track relevant pages selected by `schema` and `instructions`; refresh the page + * set periodically. */ export interface MonitorsExtractTarget { /** @@ -901,6 +903,9 @@ export namespace MonitorRetrieveResponse { */ instructions: string; + /** + * Use `extract` to watch structured data across selected pages. + */ type: 'extract'; /** @@ -908,6 +913,9 @@ export namespace MonitorRetrieveResponse { */ url: string; + /** + * Allow page discovery on subdomains of the target site. + */ follow_subdomains?: boolean; /** @@ -921,14 +929,8 @@ export namespace MonitorRetrieveResponse { max_pages?: number; /** - * JSON Schema describing the data you care about. It is used three ways: it guides - * which pages are selected for tracking, it gives the change judge extra context - * on which changes matter (alongside `instructions`), and it defines the shape of - * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most - * about once a day). It is not a response format for changes: change events and - * webhook payloads always contain diffs, summaries, and evidence excerpts — never - * data in this schema's shape. If omitted, a default summary + key-points schema - * is used. + * JSON Schema for page selection and the baseline snapshot. Changes return diffs + * and evidence. */ schema?: { [key: string]: unknown }; } @@ -980,10 +982,8 @@ export namespace MonitorRetrieveResponse { captured_at: string; /** - * The extracted structured data, matching the monitor's extraction schema (same - * shape as the /web/extract endpoint's `data`). Refreshed when the monitor - * re-discovers its page set (at most about once a day); `null` when no extraction - * has been captured yet. + * Latest structured snapshot matching the extraction schema, refreshed at most + * daily; `null` before capture. */ data: unknown; @@ -993,6 +993,21 @@ export namespace MonitorRetrieveResponse { urls_analyzed: Array; } + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } + /** * Error from the most recent failed run; null when the last run succeeded. */ @@ -1002,18 +1017,43 @@ export namespace MonitorRetrieveResponse { message: string; } + /** + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + export interface Schedule { + /** + * Number of units between runs. The resulting interval (frequency × unit) must be + * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; + * maximum 365 when unit is days). + */ + frequency: number; + + /** + * Use `interval` to run on a repeating schedule. + */ + type: 'interval'; + + /** + * Time unit used with `frequency` to set the run interval. + */ + unit: 'minutes' | 'hours' | 'days'; + } + + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ export interface Webhook { /** - * Webhook URL events are delivered to. Slack incoming webhook URLs are - * automatically formatted as Slack messages. + * Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted + * messages. */ url: string; /** - * Events delivered to this endpoint. `change.detected` fires only when a run - * detects a change; `run.completed` fires on every completed run — including runs - * that detected no change — and embeds the change when one was detected. Defaults - * to `["change.detected"]` when omitted. + * Events to deliver. Defaults to `change.detected`; `run.completed` also includes + * unchanged runs. */ events?: Array<'change.detected' | 'run.completed'>; @@ -1023,12 +1063,8 @@ export namespace MonitorRetrieveResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Omitted unless the API key - * has monitors:write permission or full access. Each delivery includes an - * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over - * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time - * compare and reject stale timestamps to prevent replay. Generated by the API; - * cannot be set by clients. + * API-generated signing secret. Visible only with full access or `monitors:write` + * permission. */ secret?: string; } @@ -1060,15 +1096,12 @@ export namespace MonitorRetrieveResponse { } } -/** - * A web monitor. `mode` is the constant `web`; behavior is described by `target` - * (page/sitemap/extract) and `change_detection` (exact/semantic). - */ export interface MonitorUpdateResponse { id: string; /** - * Discriminated union describing how changes are detected. + * How changes are judged. Defaults to `semantic` for extract targets and page + * targets with `instructions`, otherwise `exact`. */ change_detection: | MonitorUpdateResponse.MonitorsExactChangeDetection @@ -1077,31 +1110,26 @@ export interface MonitorUpdateResponse { created_at: string; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; name: string; /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ - schedule: MonitorUpdateResponse.Schedule; + request_id: string; /** - * Monitor lifecycle status. `failed` means the most recent run failed (see the - * monitor's `last_error`); failed monitors keep running on schedule and flip back - * to `active` on the next successful run. Monitors are auto-`paused` after - * repeated consecutive failures or insufficient-credit skips; resume by PATCHing - * status to `active`. + * Current state. Failed monitors keep running; paused monitors must be resumed + * with `status: "active"`. */ status: 'active' | 'paused' | 'failed'; /** - * Discriminated union describing what the monitor watches. + * What to watch: a page, a sitemap, or data extracted from a site. */ target: | MonitorUpdateResponse.MonitorsPageTarget @@ -1111,10 +1139,8 @@ export interface MonitorUpdateResponse { updated_at: string; /** - * Current baseline: the last observed value the monitor compares new snapshots - * against. Its shape follows `target.type` (page/sitemap/extract). Only populated - * on GET /monitors/{monitor_id}; null until the first baseline run completes (and - * after a target or change_detection update, which resets the baseline). + * Comparison baseline, included on Retrieve. Null until capture completes or after + * target changes. */ baseline?: | MonitorUpdateResponse.MonitorsPageBaseline @@ -1122,6 +1148,11 @@ export interface MonitorUpdateResponse { | MonitorUpdateResponse.MonitorsExtractBaseline | null; + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorUpdateResponse.KeyMetadata; + last_change_at?: string | null; /** @@ -1132,16 +1163,25 @@ export interface MonitorUpdateResponse { last_run_at?: string | null; /** - * When the next scheduled run is due. + * When the next scheduled run is due; null while paused. */ next_run_at?: string | null; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + schedule?: MonitorUpdateResponse.Schedule; + + /** + * Labels for filtering monitors, their changes, and their usage. */ tags?: Array; + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ webhook?: MonitorUpdateResponse.Webhook | null; /** @@ -1158,37 +1198,26 @@ export namespace MonitorUpdateResponse { * sitemap targets, this means URL additions and removals. */ export interface MonitorsExactChangeDetection { + /** + * Use `exact` to compare visible text or sitemap URLs. + */ type: 'exact'; } /** - * Detect meaning-level changes to page content, ignoring cosmetic or - * instruction-irrelevant differences. Which changes are meaningful is judged - * against the page or extract target's `instructions` (and an extract target's - * `schema`, when provided). + * Detect meaningful content changes using the target’s instructions and optional + * schema. */ export interface MonitorsSemanticChangeDetection { + /** + * Use `semantic` to judge changes against the target instructions. + */ type: 'semantic'; - confidence_threshold?: number; - } - - /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. - */ - export interface Schedule { /** - * Number of units between runs. The resulting interval (frequency × unit) must be - * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; - * maximum 365 when unit is days). + * Minimum confidence required to report a meaningful change, from 0 to 1. */ - frequency: number; - - type: 'interval'; - - unit: 'minutes' | 'hours' | 'days'; + confidence_threshold?: number; } /** @@ -1196,24 +1225,24 @@ export namespace MonitorUpdateResponse { * detection judges confirmed stable diffs against `instructions`. */ export interface MonitorsPageTarget { + /** + * Use `page` to watch one web page. + */ type: 'page'; + /** + * Public HTTP(S) page URL to monitor. + */ url: string; /** - * CSS selectors for HTML regions to remove before text extraction. Applied after - * include_selectors; exclusion takes precedence when an element matches both. Omit - * or pass an empty array to apply no explicit exclusions. Changing these selectors - * creates a new baseline. + * Remove matching regions after inclusions. Changes create a new baseline. */ exclude_selectors?: Array; /** - * CSS selectors defining the HTML regions to monitor. Matching subtrees are - * combined in document order before text extraction, instead of automatic - * main-content selection. Omit or pass an empty array to use automatic - * main-content extraction. If the filtered page has no usable text, the run fails - * without replacing the baseline. Changing these selectors creates a new baseline. + * Monitor these CSS-selected regions. Empty or omitted uses main content. Changes + * create a new baseline. */ include_selectors?: Array; @@ -1230,13 +1259,12 @@ export namespace MonitorUpdateResponse { } /** - * Watch a sitemap for URL additions and removals. Crawled URLs are normalized - * (lowercased host, no trailing slash/fragment) and scoped to the monitored site - * and its subdomains before comparison. On a detected difference the sitemap is - * re-fetched within the same run and only URLs both observations agree on are - * reported, suppressing transient crawl flaps. + * Watch a site’s URL inventory for confirmed additions and removals. */ export interface MonitorsSitemapTarget { + /** + * Use `sitemap` to watch a site for added or removed URLs. + */ type: 'sitemap'; /** @@ -1261,11 +1289,8 @@ export namespace MonitorUpdateResponse { } /** - * Watch the monitor-relevant pages of a site for meaningful changes. A crawl - * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to - * track; each run re-checks exactly those pages, and confirmed content changes are - * judged for relevance against the monitor's `instructions` (and `schema`, when - * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + * Track relevant pages selected by `schema` and `instructions`; refresh the page + * set periodically. */ export interface MonitorsExtractTarget { /** @@ -1274,6 +1299,9 @@ export namespace MonitorUpdateResponse { */ instructions: string; + /** + * Use `extract` to watch structured data across selected pages. + */ type: 'extract'; /** @@ -1281,6 +1309,9 @@ export namespace MonitorUpdateResponse { */ url: string; + /** + * Allow page discovery on subdomains of the target site. + */ follow_subdomains?: boolean; /** @@ -1294,14 +1325,8 @@ export namespace MonitorUpdateResponse { max_pages?: number; /** - * JSON Schema describing the data you care about. It is used three ways: it guides - * which pages are selected for tracking, it gives the change judge extra context - * on which changes matter (alongside `instructions`), and it defines the shape of - * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most - * about once a day). It is not a response format for changes: change events and - * webhook payloads always contain diffs, summaries, and evidence excerpts — never - * data in this schema's shape. If omitted, a default summary + key-points schema - * is used. + * JSON Schema for page selection and the baseline snapshot. Changes return diffs + * and evidence. */ schema?: { [key: string]: unknown }; } @@ -1353,10 +1378,8 @@ export namespace MonitorUpdateResponse { captured_at: string; /** - * The extracted structured data, matching the monitor's extraction schema (same - * shape as the /web/extract endpoint's `data`). Refreshed when the monitor - * re-discovers its page set (at most about once a day); `null` when no extraction - * has been captured yet. + * Latest structured snapshot matching the extraction schema, refreshed at most + * daily; `null` before capture. */ data: unknown; @@ -1366,6 +1389,21 @@ export namespace MonitorUpdateResponse { urls_analyzed: Array; } + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } + /** * Error from the most recent failed run; null when the last run succeeded. */ @@ -1375,18 +1413,43 @@ export namespace MonitorUpdateResponse { message: string; } + /** + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + export interface Schedule { + /** + * Number of units between runs. The resulting interval (frequency × unit) must be + * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; + * maximum 365 when unit is days). + */ + frequency: number; + + /** + * Use `interval` to run on a repeating schedule. + */ + type: 'interval'; + + /** + * Time unit used with `frequency` to set the run interval. + */ + unit: 'minutes' | 'hours' | 'days'; + } + + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ export interface Webhook { /** - * Webhook URL events are delivered to. Slack incoming webhook URLs are - * automatically formatted as Slack messages. + * Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted + * messages. */ url: string; /** - * Events delivered to this endpoint. `change.detected` fires only when a run - * detects a change; `run.completed` fires on every completed run — including runs - * that detected no change — and embeds the change when one was detected. Defaults - * to `["change.detected"]` when omitted. + * Events to deliver. Defaults to `change.detected`; `run.completed` also includes + * unchanged runs. */ events?: Array<'change.detected' | 'run.completed'>; @@ -1396,12 +1459,8 @@ export namespace MonitorUpdateResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Omitted unless the API key - * has monitors:write permission or full access. Each delivery includes an - * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over - * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time - * compare and reject stale timestamps to prevent replay. Generated by the API; - * cannot be set by clients. + * API-generated signing secret. Visible only with full access or `monitors:write` + * permission. */ secret?: string; } @@ -1439,6 +1498,17 @@ export interface MonitorListResponse { has_more: boolean; next_cursor: string | null; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorListResponse.KeyMetadata; } export namespace MonitorListResponse { @@ -1450,15 +1520,15 @@ export namespace MonitorListResponse { id: string; /** - * Discriminated union describing how changes are detected. + * How changes are judged. Defaults to `semantic` for extract targets and page + * targets with `instructions`, otherwise `exact`. */ change_detection: Data.MonitorsExactChangeDetection | Data.MonitorsSemanticChangeDetection; created_at: string; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; @@ -1472,26 +1542,21 @@ export namespace MonitorListResponse { schedule: Data.Schedule; /** - * Monitor lifecycle status. `failed` means the most recent run failed (see the - * monitor's `last_error`); failed monitors keep running on schedule and flip back - * to `active` on the next successful run. Monitors are auto-`paused` after - * repeated consecutive failures or insufficient-credit skips; resume by PATCHing - * status to `active`. + * Current state. Failed monitors keep running; paused monitors must be resumed + * with `status: "active"`. */ status: 'active' | 'paused' | 'failed'; /** - * Discriminated union describing what the monitor watches. + * What to watch: a page, a sitemap, or data extracted from a site. */ target: Data.MonitorsPageTarget | Data.MonitorsSitemapTarget | Data.MonitorsExtractTarget; updated_at: string; /** - * Current baseline: the last observed value the monitor compares new snapshots - * against. Its shape follows `target.type` (page/sitemap/extract). Only populated - * on GET /monitors/{monitor_id}; null until the first baseline run completes (and - * after a target or change_detection update, which resets the baseline). + * Comparison baseline, included on Retrieve. Null until capture completes or after + * target changes. */ baseline?: Data.MonitorsPageBaseline | Data.MonitorsSitemapBaseline | Data.MonitorsExtractBaseline | null; @@ -1505,16 +1570,18 @@ export namespace MonitorListResponse { last_run_at?: string | null; /** - * When the next scheduled run is due. + * When the next scheduled run is due; null while paused. */ next_run_at?: string | null; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Labels for filtering monitors, their changes, and their usage. */ tags?: Array; + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ webhook?: Data.Webhook | null; /** @@ -1531,18 +1598,25 @@ export namespace MonitorListResponse { * sitemap targets, this means URL additions and removals. */ export interface MonitorsExactChangeDetection { + /** + * Use `exact` to compare visible text or sitemap URLs. + */ type: 'exact'; } /** - * Detect meaning-level changes to page content, ignoring cosmetic or - * instruction-irrelevant differences. Which changes are meaningful is judged - * against the page or extract target's `instructions` (and an extract target's - * `schema`, when provided). + * Detect meaningful content changes using the target’s instructions and optional + * schema. */ export interface MonitorsSemanticChangeDetection { + /** + * Use `semantic` to judge changes against the target instructions. + */ type: 'semantic'; + /** + * Minimum confidence required to report a meaningful change, from 0 to 1. + */ confidence_threshold?: number; } @@ -1559,8 +1633,14 @@ export namespace MonitorListResponse { */ frequency: number; + /** + * Use `interval` to run on a repeating schedule. + */ type: 'interval'; + /** + * Time unit used with `frequency` to set the run interval. + */ unit: 'minutes' | 'hours' | 'days'; } @@ -1569,24 +1649,24 @@ export namespace MonitorListResponse { * detection judges confirmed stable diffs against `instructions`. */ export interface MonitorsPageTarget { + /** + * Use `page` to watch one web page. + */ type: 'page'; + /** + * Public HTTP(S) page URL to monitor. + */ url: string; /** - * CSS selectors for HTML regions to remove before text extraction. Applied after - * include_selectors; exclusion takes precedence when an element matches both. Omit - * or pass an empty array to apply no explicit exclusions. Changing these selectors - * creates a new baseline. + * Remove matching regions after inclusions. Changes create a new baseline. */ exclude_selectors?: Array; /** - * CSS selectors defining the HTML regions to monitor. Matching subtrees are - * combined in document order before text extraction, instead of automatic - * main-content selection. Omit or pass an empty array to use automatic - * main-content extraction. If the filtered page has no usable text, the run fails - * without replacing the baseline. Changing these selectors creates a new baseline. + * Monitor these CSS-selected regions. Empty or omitted uses main content. Changes + * create a new baseline. */ include_selectors?: Array; @@ -1603,13 +1683,12 @@ export namespace MonitorListResponse { } /** - * Watch a sitemap for URL additions and removals. Crawled URLs are normalized - * (lowercased host, no trailing slash/fragment) and scoped to the monitored site - * and its subdomains before comparison. On a detected difference the sitemap is - * re-fetched within the same run and only URLs both observations agree on are - * reported, suppressing transient crawl flaps. + * Watch a site’s URL inventory for confirmed additions and removals. */ export interface MonitorsSitemapTarget { + /** + * Use `sitemap` to watch a site for added or removed URLs. + */ type: 'sitemap'; /** @@ -1634,11 +1713,8 @@ export namespace MonitorListResponse { } /** - * Watch the monitor-relevant pages of a site for meaningful changes. A crawl - * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to - * track; each run re-checks exactly those pages, and confirmed content changes are - * judged for relevance against the monitor's `instructions` (and `schema`, when - * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + * Track relevant pages selected by `schema` and `instructions`; refresh the page + * set periodically. */ export interface MonitorsExtractTarget { /** @@ -1647,6 +1723,9 @@ export namespace MonitorListResponse { */ instructions: string; + /** + * Use `extract` to watch structured data across selected pages. + */ type: 'extract'; /** @@ -1654,6 +1733,9 @@ export namespace MonitorListResponse { */ url: string; + /** + * Allow page discovery on subdomains of the target site. + */ follow_subdomains?: boolean; /** @@ -1667,14 +1749,8 @@ export namespace MonitorListResponse { max_pages?: number; /** - * JSON Schema describing the data you care about. It is used three ways: it guides - * which pages are selected for tracking, it gives the change judge extra context - * on which changes matter (alongside `instructions`), and it defines the shape of - * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most - * about once a day). It is not a response format for changes: change events and - * webhook payloads always contain diffs, summaries, and evidence excerpts — never - * data in this schema's shape. If omitted, a default summary + key-points schema - * is used. + * JSON Schema for page selection and the baseline snapshot. Changes return diffs + * and evidence. */ schema?: { [key: string]: unknown }; } @@ -1726,10 +1802,8 @@ export namespace MonitorListResponse { captured_at: string; /** - * The extracted structured data, matching the monitor's extraction schema (same - * shape as the /web/extract endpoint's `data`). Refreshed when the monitor - * re-discovers its page set (at most about once a day); `null` when no extraction - * has been captured yet. + * Latest structured snapshot matching the extraction schema, refreshed at most + * daily; `null` before capture. */ data: unknown; @@ -1748,18 +1822,19 @@ export namespace MonitorListResponse { message: string; } + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ export interface Webhook { /** - * Webhook URL events are delivered to. Slack incoming webhook URLs are - * automatically formatted as Slack messages. + * Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted + * messages. */ url: string; /** - * Events delivered to this endpoint. `change.detected` fires only when a run - * detects a change; `run.completed` fires on every completed run — including runs - * that detected no change — and embeds the change when one was detected. Defaults - * to `["change.detected"]` when omitted. + * Events to deliver. Defaults to `change.detected`; `run.completed` also includes + * unchanged runs. */ events?: Array<'change.detected' | 'run.completed'>; @@ -1769,12 +1844,8 @@ export namespace MonitorListResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Omitted unless the API key - * has monitors:write permission or full access. Each delivery includes an - * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over - * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time - * compare and reject stale timestamps to prevent replay. Generated by the API; - * cannot be set by clients. + * API-generated signing secret. Visible only with full access or `monitors:write` + * permission. */ secret?: string; } @@ -1805,21 +1876,75 @@ export namespace MonitorListResponse { last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; } } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } export interface MonitorDeleteResponse { id: string; deleted: boolean; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorDeleteResponse.KeyMetadata; +} + +export namespace MonitorDeleteResponse { + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } export interface MonitorGetCreditUsageResponse { data: Array; + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + /** * Sum of credits across all monitors in the window. */ total_credits: number; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorGetCreditUsageResponse.KeyMetadata; } export namespace MonitorGetCreditUsageResponse { @@ -1841,12 +1966,26 @@ export namespace MonitorGetCreditUsageResponse { */ runs: number; } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } export interface MonitorGetLimitsResponse { /** - * Maximum number of monitors allowed for the account. Defaults to the plan - * allowance unless a custom limit is set for the organization. + * Most monitors you can have: your plan's allowance or a custom limit. */ monitors_limit: number; @@ -1856,9 +1995,38 @@ export interface MonitorGetLimitsResponse { monitors_used: number; /** - * The plan tier the limit was resolved from. + * `starter` means Developer; `pro` means Pro or Growth; `scale` means Scale or + * Enterprise. */ plan: 'free' | 'starter' | 'pro' | 'scale'; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorGetLimitsResponse.KeyMetadata; +} + +export namespace MonitorGetLimitsResponse { + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } export interface MonitorListAccountChangesResponse { @@ -1867,15 +2035,22 @@ export interface MonitorListAccountChangesResponse { has_more: boolean; next_cursor: string | null; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorListAccountChangesResponse.KeyMetadata; } export namespace MonitorListAccountChangesResponse { /** - * A lightweight change summary. `mode` is the constant `web`; `target_type` and - * `change_detection_type` describe the change, and which optional fields are - * present depends on them (e.g. sitemap changes include - * `added_url_count`/`removed_url_count`; semantic changes include - * `confidence`/`importance`). + * Detected change, including applicable diffs, URLs, and supporting evidence. */ export interface Data { id: string; @@ -1885,15 +2060,24 @@ export namespace MonitorListAccountChangesResponse { detected_at: string; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; monitor_id: string; + /** + * The run that detected this change. + */ + run_id: string; + summary: string; + /** + * Labels for filtering monitors, their changes, and their usage. + */ + tags: Array; + target_type: 'page' | 'sitemap' | 'extract'; title: string; @@ -1902,19 +2086,73 @@ export namespace MonitorListAccountChangesResponse { added_url_count?: number; + /** + * At most 500 URLs are included; the corresponding count field is always exact. + */ + added_urls?: Array; + + after_text_excerpt?: string; + + before_text_excerpt?: string; + confidence?: number; + /** + * Text diff between the previous and current page baseline (page targets). + */ + diff?: string; + + evidence?: Array; + importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; + /** + * At most 500 URLs are included; the corresponding count field is always exact. + */ + matched_urls?: Array; + removed_url_count?: number; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * At most 500 URLs are included; the corresponding count field is always exact. */ - tags?: Array; + removed_urls?: Array; + } + + export namespace Data { + export interface Evidence { + /** + * Snapshot of the content after the change. + */ + after: string; + + /** + * Snapshot of the content before the change. + */ + before: string; + + /** + * Optional URL the evidence relates to. Absent for whole-target diffs. + */ + url?: string; + } + } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; } } @@ -1923,7 +2161,18 @@ export interface MonitorListAccountRunsResponse { has_more: boolean; - next_cursor: string | null; + next_cursor: string | null; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorListAccountRunsResponse.KeyMetadata; } export namespace MonitorListAccountRunsResponse { @@ -1948,7 +2197,7 @@ export namespace MonitorListAccountRunsResponse { monitor_id: string; /** - * The first run after monitor creation is a baseline run. + * A baseline run follows creation or a target or detection change. */ run_type: 'baseline' | 'scheduled'; @@ -1981,9 +2230,7 @@ export namespace MonitorListAccountRunsResponse { webhook_deliveries?: Array; /** - * @deprecated Deprecated: use `webhook_deliveries`, which records every attempt - * now that a run can deliver multiple events. Omitted when no webhook was - * attempted, including historical runs created before delivery tracking was added. + * @deprecated Deprecated. Use `webhook_deliveries` for all attempts. */ webhook_delivery?: MonitorsAPI.WebhookDelivery; @@ -2000,6 +2247,21 @@ export namespace MonitorListAccountRunsResponse { message: string; } } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } export interface MonitorListChangesResponse { @@ -2008,15 +2270,22 @@ export interface MonitorListChangesResponse { has_more: boolean; next_cursor: string | null; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorListChangesResponse.KeyMetadata; } export namespace MonitorListChangesResponse { /** - * A lightweight change summary. `mode` is the constant `web`; `target_type` and - * `change_detection_type` describe the change, and which optional fields are - * present depends on them (e.g. sitemap changes include - * `added_url_count`/`removed_url_count`; semantic changes include - * `confidence`/`importance`). + * Detected change, including applicable diffs, URLs, and supporting evidence. */ export interface Data { id: string; @@ -2026,15 +2295,24 @@ export namespace MonitorListChangesResponse { detected_at: string; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; monitor_id: string; + /** + * The run that detected this change. + */ + run_id: string; + summary: string; + /** + * Labels for filtering monitors, their changes, and their usage. + */ + tags: Array; + target_type: 'page' | 'sitemap' | 'extract'; title: string; @@ -2043,19 +2321,73 @@ export namespace MonitorListChangesResponse { added_url_count?: number; + /** + * At most 500 URLs are included; the corresponding count field is always exact. + */ + added_urls?: Array; + + after_text_excerpt?: string; + + before_text_excerpt?: string; + confidence?: number; + /** + * Text diff between the previous and current page baseline (page targets). + */ + diff?: string; + + evidence?: Array; + importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; + /** + * At most 500 URLs are included; the corresponding count field is always exact. + */ + matched_urls?: Array; + removed_url_count?: number; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * At most 500 URLs are included; the corresponding count field is always exact. */ - tags?: Array; + removed_urls?: Array; + } + + export namespace Data { + export interface Evidence { + /** + * Snapshot of the content after the change. + */ + after: string; + + /** + * Snapshot of the content before the change. + */ + before: string; + + /** + * Optional URL the evidence relates to. Absent for whole-target diffs. + */ + url?: string; + } + } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; } } @@ -2065,6 +2397,17 @@ export interface MonitorListRunsResponse { has_more: boolean; next_cursor: string | null; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorListRunsResponse.KeyMetadata; } export namespace MonitorListRunsResponse { @@ -2089,7 +2432,7 @@ export namespace MonitorListRunsResponse { monitor_id: string; /** - * The first run after monitor creation is a baseline run. + * A baseline run follows creation or a target or detection change. */ run_type: 'baseline' | 'scheduled'; @@ -2122,9 +2465,7 @@ export namespace MonitorListRunsResponse { webhook_deliveries?: Array; /** - * @deprecated Deprecated: use `webhook_deliveries`, which records every attempt - * now that a run can deliver multiple events. Omitted when no webhook was - * attempted, including historical runs created before delivery tracking was added. + * @deprecated Deprecated. Use `webhook_deliveries` for all attempts. */ webhook_delivery?: MonitorsAPI.WebhookDelivery; @@ -2141,15 +2482,23 @@ export namespace MonitorListRunsResponse { message: string; } } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } -/** - * A detected change. `mode` is the constant `web`; `target_type` and - * `change_detection_type` describe the change, and which optional fields are - * present depends on them (page: `diff` + excerpts; sitemap: - * `added_urls`/`removed_urls`; semantic: - * `confidence`/`importance`/`evidence`/`matched_urls`). - */ export interface MonitorRetrieveChangeResponse { id: string; @@ -2158,13 +2507,18 @@ export interface MonitorRetrieveChangeResponse { detected_at: string; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; monitor_id: string; + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + /** * The run that detected this change. */ @@ -2173,8 +2527,7 @@ export interface MonitorRetrieveChangeResponse { summary: string; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Labels for filtering monitors, their changes, and their usage. */ tags: Array; @@ -2206,6 +2559,11 @@ export interface MonitorRetrieveChangeResponse { importance?: 'low' | 'medium' | 'high'; + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorRetrieveChangeResponse.KeyMetadata; + matched_url_count?: number; /** @@ -2238,6 +2596,21 @@ export namespace MonitorRetrieveChangeResponse { */ url?: string; } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } export interface MonitorRetrieveRunResponse { @@ -2261,7 +2634,13 @@ export interface MonitorRetrieveRunResponse { monitor_id: string; /** - * The first run after monitor creation is a baseline run. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * A baseline run follows creation or a target or detection change. */ run_type: 'baseline' | 'scheduled'; @@ -2279,6 +2658,11 @@ export interface MonitorRetrieveRunResponse { error?: MonitorRetrieveRunResponse.Error | null; + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorRetrieveRunResponse.KeyMetadata; + /** * Why a skipped run never executed; null unless status is `skipped`. */ @@ -2294,9 +2678,7 @@ export interface MonitorRetrieveRunResponse { webhook_deliveries?: Array; /** - * @deprecated Deprecated: use `webhook_deliveries`, which records every attempt - * now that a run can deliver multiple events. Omitted when no webhook was - * attempted, including historical runs created before delivery tracking was added. + * @deprecated Deprecated. Use `webhook_deliveries` for all attempts. */ webhook_delivery?: WebhookDelivery; @@ -2312,17 +2694,29 @@ export namespace MonitorRetrieveRunResponse { message: string; } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } -/** - * A web monitor. `mode` is the constant `web`; behavior is described by `target` - * (page/sitemap/extract) and `change_detection` (exact/semantic). - */ export interface MonitorRotateWebhookSecretResponse { id: string; /** - * Discriminated union describing how changes are detected. + * How changes are judged. Defaults to `semantic` for extract targets and page + * targets with `instructions`, otherwise `exact`. */ change_detection: | MonitorRotateWebhookSecretResponse.MonitorsExactChangeDetection @@ -2331,31 +2725,26 @@ export interface MonitorRotateWebhookSecretResponse { created_at: string; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; name: string; /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ - schedule: MonitorRotateWebhookSecretResponse.Schedule; + request_id: string; /** - * Monitor lifecycle status. `failed` means the most recent run failed (see the - * monitor's `last_error`); failed monitors keep running on schedule and flip back - * to `active` on the next successful run. Monitors are auto-`paused` after - * repeated consecutive failures or insufficient-credit skips; resume by PATCHing - * status to `active`. + * Current state. Failed monitors keep running; paused monitors must be resumed + * with `status: "active"`. */ status: 'active' | 'paused' | 'failed'; /** - * Discriminated union describing what the monitor watches. + * What to watch: a page, a sitemap, or data extracted from a site. */ target: | MonitorRotateWebhookSecretResponse.MonitorsPageTarget @@ -2365,10 +2754,8 @@ export interface MonitorRotateWebhookSecretResponse { updated_at: string; /** - * Current baseline: the last observed value the monitor compares new snapshots - * against. Its shape follows `target.type` (page/sitemap/extract). Only populated - * on GET /monitors/{monitor_id}; null until the first baseline run completes (and - * after a target or change_detection update, which resets the baseline). + * Comparison baseline, included on Retrieve. Null until capture completes or after + * target changes. */ baseline?: | MonitorRotateWebhookSecretResponse.MonitorsPageBaseline @@ -2376,6 +2763,11 @@ export interface MonitorRotateWebhookSecretResponse { | MonitorRotateWebhookSecretResponse.MonitorsExtractBaseline | null; + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorRotateWebhookSecretResponse.KeyMetadata; + last_change_at?: string | null; /** @@ -2386,16 +2778,25 @@ export interface MonitorRotateWebhookSecretResponse { last_run_at?: string | null; /** - * When the next scheduled run is due. + * When the next scheduled run is due; null while paused. */ next_run_at?: string | null; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + schedule?: MonitorRotateWebhookSecretResponse.Schedule; + + /** + * Labels for filtering monitors, their changes, and their usage. */ tags?: Array; + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ webhook?: MonitorRotateWebhookSecretResponse.Webhook | null; /** @@ -2412,37 +2813,26 @@ export namespace MonitorRotateWebhookSecretResponse { * sitemap targets, this means URL additions and removals. */ export interface MonitorsExactChangeDetection { + /** + * Use `exact` to compare visible text or sitemap URLs. + */ type: 'exact'; } /** - * Detect meaning-level changes to page content, ignoring cosmetic or - * instruction-irrelevant differences. Which changes are meaningful is judged - * against the page or extract target's `instructions` (and an extract target's - * `schema`, when provided). + * Detect meaningful content changes using the target’s instructions and optional + * schema. */ export interface MonitorsSemanticChangeDetection { + /** + * Use `semantic` to judge changes against the target instructions. + */ type: 'semantic'; - confidence_threshold?: number; - } - - /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. - */ - export interface Schedule { /** - * Number of units between runs. The resulting interval (frequency × unit) must be - * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; - * maximum 365 when unit is days). + * Minimum confidence required to report a meaningful change, from 0 to 1. */ - frequency: number; - - type: 'interval'; - - unit: 'minutes' | 'hours' | 'days'; + confidence_threshold?: number; } /** @@ -2450,24 +2840,24 @@ export namespace MonitorRotateWebhookSecretResponse { * detection judges confirmed stable diffs against `instructions`. */ export interface MonitorsPageTarget { + /** + * Use `page` to watch one web page. + */ type: 'page'; + /** + * Public HTTP(S) page URL to monitor. + */ url: string; /** - * CSS selectors for HTML regions to remove before text extraction. Applied after - * include_selectors; exclusion takes precedence when an element matches both. Omit - * or pass an empty array to apply no explicit exclusions. Changing these selectors - * creates a new baseline. + * Remove matching regions after inclusions. Changes create a new baseline. */ exclude_selectors?: Array; /** - * CSS selectors defining the HTML regions to monitor. Matching subtrees are - * combined in document order before text extraction, instead of automatic - * main-content selection. Omit or pass an empty array to use automatic - * main-content extraction. If the filtered page has no usable text, the run fails - * without replacing the baseline. Changing these selectors creates a new baseline. + * Monitor these CSS-selected regions. Empty or omitted uses main content. Changes + * create a new baseline. */ include_selectors?: Array; @@ -2484,13 +2874,12 @@ export namespace MonitorRotateWebhookSecretResponse { } /** - * Watch a sitemap for URL additions and removals. Crawled URLs are normalized - * (lowercased host, no trailing slash/fragment) and scoped to the monitored site - * and its subdomains before comparison. On a detected difference the sitemap is - * re-fetched within the same run and only URLs both observations agree on are - * reported, suppressing transient crawl flaps. + * Watch a site’s URL inventory for confirmed additions and removals. */ export interface MonitorsSitemapTarget { + /** + * Use `sitemap` to watch a site for added or removed URLs. + */ type: 'sitemap'; /** @@ -2515,11 +2904,8 @@ export namespace MonitorRotateWebhookSecretResponse { } /** - * Watch the monitor-relevant pages of a site for meaningful changes. A crawl - * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to - * track; each run re-checks exactly those pages, and confirmed content changes are - * judged for relevance against the monitor's `instructions` (and `schema`, when - * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + * Track relevant pages selected by `schema` and `instructions`; refresh the page + * set periodically. */ export interface MonitorsExtractTarget { /** @@ -2528,6 +2914,9 @@ export namespace MonitorRotateWebhookSecretResponse { */ instructions: string; + /** + * Use `extract` to watch structured data across selected pages. + */ type: 'extract'; /** @@ -2535,6 +2924,9 @@ export namespace MonitorRotateWebhookSecretResponse { */ url: string; + /** + * Allow page discovery on subdomains of the target site. + */ follow_subdomains?: boolean; /** @@ -2548,14 +2940,8 @@ export namespace MonitorRotateWebhookSecretResponse { max_pages?: number; /** - * JSON Schema describing the data you care about. It is used three ways: it guides - * which pages are selected for tracking, it gives the change judge extra context - * on which changes matter (alongside `instructions`), and it defines the shape of - * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most - * about once a day). It is not a response format for changes: change events and - * webhook payloads always contain diffs, summaries, and evidence excerpts — never - * data in this schema's shape. If omitted, a default summary + key-points schema - * is used. + * JSON Schema for page selection and the baseline snapshot. Changes return diffs + * and evidence. */ schema?: { [key: string]: unknown }; } @@ -2607,10 +2993,8 @@ export namespace MonitorRotateWebhookSecretResponse { captured_at: string; /** - * The extracted structured data, matching the monitor's extraction schema (same - * shape as the /web/extract endpoint's `data`). Refreshed when the monitor - * re-discovers its page set (at most about once a day); `null` when no extraction - * has been captured yet. + * Latest structured snapshot matching the extraction schema, refreshed at most + * daily; `null` before capture. */ data: unknown; @@ -2620,6 +3004,21 @@ export namespace MonitorRotateWebhookSecretResponse { urls_analyzed: Array; } + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } + /** * Error from the most recent failed run; null when the last run succeeded. */ @@ -2629,18 +3028,43 @@ export namespace MonitorRotateWebhookSecretResponse { message: string; } + /** + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + export interface Schedule { + /** + * Number of units between runs. The resulting interval (frequency × unit) must be + * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; + * maximum 365 when unit is days). + */ + frequency: number; + + /** + * Use `interval` to run on a repeating schedule. + */ + type: 'interval'; + + /** + * Time unit used with `frequency` to set the run interval. + */ + unit: 'minutes' | 'hours' | 'days'; + } + + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ export interface Webhook { /** - * Webhook URL events are delivered to. Slack incoming webhook URLs are - * automatically formatted as Slack messages. + * Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted + * messages. */ url: string; /** - * Events delivered to this endpoint. `change.detected` fires only when a run - * detects a change; `run.completed` fires on every completed run — including runs - * that detected no change — and embeds the change when one was detected. Defaults - * to `["change.detected"]` when omitted. + * Events to deliver. Defaults to `change.detected`; `run.completed` also includes + * unchanged runs. */ events?: Array<'change.detected' | 'run.completed'>; @@ -2650,12 +3074,8 @@ export namespace MonitorRotateWebhookSecretResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Omitted unless the API key - * has monitors:write permission or full access. Each delivery includes an - * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over - * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time - * compare and reject stale timestamps to prevent replay. Generated by the API; - * cannot be set by clients. + * API-generated signing secret. Visible only with full access or `monitors:write` + * permission. */ secret?: string; } @@ -2693,17 +3113,47 @@ export interface MonitorRunResponse { queued: boolean; /** - * The queued run. Poll GET /monitors/{monitor_id}/runs or use it to correlate - * results. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * ID of the queued run; pass it to Retrieve a monitor run. */ run_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorRunResponse.KeyMetadata; +} + +export namespace MonitorRunResponse { + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } export interface MonitorCreateParams { + /** + * Display name for the monitor. + */ name: string; /** - * Discriminated union describing what the monitor watches. + * What to watch: a page, a sitemap, or data extracted from a site. */ target: | MonitorCreateParams.MonitorsPageTarget @@ -2711,15 +3161,15 @@ export interface MonitorCreateParams { | MonitorCreateParams.MonitorsExtractTarget; /** - * Discriminated union describing how changes are detected. + * How changes are judged. Defaults to `semantic` for extract targets and page + * targets with `instructions`, otherwise `exact`. */ change_detection?: | MonitorCreateParams.MonitorsExactChangeDetection | MonitorCreateParams.MonitorsSemanticChangeDetection; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode?: 'web'; @@ -2731,11 +3181,13 @@ export interface MonitorCreateParams { schedule?: MonitorCreateParams.Schedule; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Labels for filtering monitors, their changes, and their usage. */ tags?: Array; + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ webhook?: MonitorCreateParams.Webhook | null; } @@ -2745,24 +3197,24 @@ export namespace MonitorCreateParams { * detection judges confirmed stable diffs against `instructions`. */ export interface MonitorsPageTarget { + /** + * Use `page` to watch one web page. + */ type: 'page'; + /** + * Public HTTP(S) page URL to monitor. + */ url: string; /** - * CSS selectors for HTML regions to remove before text extraction. Applied after - * include_selectors; exclusion takes precedence when an element matches both. Omit - * or pass an empty array to apply no explicit exclusions. Changing these selectors - * creates a new baseline. + * Remove matching regions after inclusions. Changes create a new baseline. */ exclude_selectors?: Array; /** - * CSS selectors defining the HTML regions to monitor. Matching subtrees are - * combined in document order before text extraction, instead of automatic - * main-content selection. Omit or pass an empty array to use automatic - * main-content extraction. If the filtered page has no usable text, the run fails - * without replacing the baseline. Changing these selectors creates a new baseline. + * Monitor these CSS-selected regions. Empty or omitted uses main content. Changes + * create a new baseline. */ include_selectors?: Array; @@ -2779,13 +3231,12 @@ export namespace MonitorCreateParams { } /** - * Watch a sitemap for URL additions and removals. Crawled URLs are normalized - * (lowercased host, no trailing slash/fragment) and scoped to the monitored site - * and its subdomains before comparison. On a detected difference the sitemap is - * re-fetched within the same run and only URLs both observations agree on are - * reported, suppressing transient crawl flaps. + * Watch a site’s URL inventory for confirmed additions and removals. */ export interface MonitorsSitemapTarget { + /** + * Use `sitemap` to watch a site for added or removed URLs. + */ type: 'sitemap'; /** @@ -2810,11 +3261,8 @@ export namespace MonitorCreateParams { } /** - * Watch the monitor-relevant pages of a site for meaningful changes. A crawl - * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to - * track; each run re-checks exactly those pages, and confirmed content changes are - * judged for relevance against the monitor's `instructions` (and `schema`, when - * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + * Track relevant pages selected by `schema` and `instructions`; refresh the page + * set periodically. */ export interface MonitorsExtractTarget { /** @@ -2823,6 +3271,9 @@ export namespace MonitorCreateParams { */ instructions: string; + /** + * Use `extract` to watch structured data across selected pages. + */ type: 'extract'; /** @@ -2830,6 +3281,9 @@ export namespace MonitorCreateParams { */ url: string; + /** + * Allow page discovery on subdomains of the target site. + */ follow_subdomains?: boolean; /** @@ -2843,14 +3297,8 @@ export namespace MonitorCreateParams { max_pages?: number; /** - * JSON Schema describing the data you care about. It is used three ways: it guides - * which pages are selected for tracking, it gives the change judge extra context - * on which changes matter (alongside `instructions`), and it defines the shape of - * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most - * about once a day). It is not a response format for changes: change events and - * webhook payloads always contain diffs, summaries, and evidence excerpts — never - * data in this schema's shape. If omitted, a default summary + key-points schema - * is used. + * JSON Schema for page selection and the baseline snapshot. Changes return diffs + * and evidence. */ schema?: { [key: string]: unknown }; } @@ -2860,18 +3308,25 @@ export namespace MonitorCreateParams { * sitemap targets, this means URL additions and removals. */ export interface MonitorsExactChangeDetection { + /** + * Use `exact` to compare visible text or sitemap URLs. + */ type: 'exact'; } /** - * Detect meaning-level changes to page content, ignoring cosmetic or - * instruction-irrelevant differences. Which changes are meaningful is judged - * against the page or extract target's `instructions` (and an extract target's - * `schema`, when provided). + * Detect meaningful content changes using the target’s instructions and optional + * schema. */ export interface MonitorsSemanticChangeDetection { + /** + * Use `semantic` to judge changes against the target instructions. + */ type: 'semantic'; + /** + * Minimum confidence required to report a meaningful change, from 0 to 1. + */ confidence_threshold?: number; } @@ -2888,23 +3343,30 @@ export namespace MonitorCreateParams { */ frequency: number; + /** + * Use `interval` to run on a repeating schedule. + */ type: 'interval'; + /** + * Time unit used with `frequency` to set the run interval. + */ unit: 'minutes' | 'hours' | 'days'; } + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ export interface Webhook { /** - * Webhook URL events are delivered to. Slack incoming webhook URLs are - * automatically formatted as Slack messages. + * Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted + * messages. */ url: string; /** - * Events delivered to this endpoint. `change.detected` fires only when a run - * detects a change; `run.completed` fires on every completed run — including runs - * that detected no change — and embeds the change when one was detected. Defaults - * to `["change.detected"]` when omitted. + * Events to deliver. Defaults to `change.detected`; `run.completed` also includes + * unchanged runs. */ events?: Array<'change.detected' | 'run.completed'>; @@ -2917,12 +3379,16 @@ export namespace MonitorCreateParams { export interface MonitorUpdateParams { /** - * Discriminated union describing how changes are detected. + * How changes are judged. Defaults to `semantic` for extract targets and page + * targets with `instructions`, otherwise `exact`. */ change_detection?: | MonitorUpdateParams.MonitorsExactChangeDetection | MonitorUpdateParams.MonitorsSemanticChangeDetection; + /** + * Display name for the monitor. + */ name?: string; /** @@ -2932,16 +3398,18 @@ export interface MonitorUpdateParams { */ schedule?: MonitorUpdateParams.Schedule; + /** + * Set `paused` to stop scheduled runs or `active` to resume them. + */ status?: 'active' | 'paused'; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Labels for filtering monitors, their changes, and their usage. */ tags?: Array; /** - * Discriminated union describing what the monitor watches. + * What to watch: a page, a sitemap, or data extracted from a site. */ target?: | MonitorUpdateParams.MonitorsPageTarget @@ -2949,7 +3417,7 @@ export interface MonitorUpdateParams { | MonitorUpdateParams.MonitorsExtractTarget; /** - * Set to null to remove the webhook. + * Set to null to remove the webhook. Changing `url` issues a new secret. */ webhook?: MonitorUpdateParams.Webhook | null; } @@ -2960,18 +3428,25 @@ export namespace MonitorUpdateParams { * sitemap targets, this means URL additions and removals. */ export interface MonitorsExactChangeDetection { + /** + * Use `exact` to compare visible text or sitemap URLs. + */ type: 'exact'; } /** - * Detect meaning-level changes to page content, ignoring cosmetic or - * instruction-irrelevant differences. Which changes are meaningful is judged - * against the page or extract target's `instructions` (and an extract target's - * `schema`, when provided). + * Detect meaningful content changes using the target’s instructions and optional + * schema. */ export interface MonitorsSemanticChangeDetection { + /** + * Use `semantic` to judge changes against the target instructions. + */ type: 'semantic'; + /** + * Minimum confidence required to report a meaningful change, from 0 to 1. + */ confidence_threshold?: number; } @@ -2988,8 +3463,14 @@ export namespace MonitorUpdateParams { */ frequency: number; + /** + * Use `interval` to run on a repeating schedule. + */ type: 'interval'; + /** + * Time unit used with `frequency` to set the run interval. + */ unit: 'minutes' | 'hours' | 'days'; } @@ -2998,24 +3479,24 @@ export namespace MonitorUpdateParams { * detection judges confirmed stable diffs against `instructions`. */ export interface MonitorsPageTarget { + /** + * Use `page` to watch one web page. + */ type: 'page'; + /** + * Public HTTP(S) page URL to monitor. + */ url: string; /** - * CSS selectors for HTML regions to remove before text extraction. Applied after - * include_selectors; exclusion takes precedence when an element matches both. Omit - * or pass an empty array to apply no explicit exclusions. Changing these selectors - * creates a new baseline. + * Remove matching regions after inclusions. Changes create a new baseline. */ exclude_selectors?: Array; /** - * CSS selectors defining the HTML regions to monitor. Matching subtrees are - * combined in document order before text extraction, instead of automatic - * main-content selection. Omit or pass an empty array to use automatic - * main-content extraction. If the filtered page has no usable text, the run fails - * without replacing the baseline. Changing these selectors creates a new baseline. + * Monitor these CSS-selected regions. Empty or omitted uses main content. Changes + * create a new baseline. */ include_selectors?: Array; @@ -3032,13 +3513,12 @@ export namespace MonitorUpdateParams { } /** - * Watch a sitemap for URL additions and removals. Crawled URLs are normalized - * (lowercased host, no trailing slash/fragment) and scoped to the monitored site - * and its subdomains before comparison. On a detected difference the sitemap is - * re-fetched within the same run and only URLs both observations agree on are - * reported, suppressing transient crawl flaps. + * Watch a site’s URL inventory for confirmed additions and removals. */ export interface MonitorsSitemapTarget { + /** + * Use `sitemap` to watch a site for added or removed URLs. + */ type: 'sitemap'; /** @@ -3063,11 +3543,8 @@ export namespace MonitorUpdateParams { } /** - * Watch the monitor-relevant pages of a site for meaningful changes. A crawl - * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to - * track; each run re-checks exactly those pages, and confirmed content changes are - * judged for relevance against the monitor's `instructions` (and `schema`, when - * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + * Track relevant pages selected by `schema` and `instructions`; refresh the page + * set periodically. */ export interface MonitorsExtractTarget { /** @@ -3076,6 +3553,9 @@ export namespace MonitorUpdateParams { */ instructions: string; + /** + * Use `extract` to watch structured data across selected pages. + */ type: 'extract'; /** @@ -3083,6 +3563,9 @@ export namespace MonitorUpdateParams { */ url: string; + /** + * Allow page discovery on subdomains of the target site. + */ follow_subdomains?: boolean; /** @@ -3096,33 +3579,25 @@ export namespace MonitorUpdateParams { max_pages?: number; /** - * JSON Schema describing the data you care about. It is used three ways: it guides - * which pages are selected for tracking, it gives the change judge extra context - * on which changes matter (alongside `instructions`), and it defines the shape of - * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most - * about once a day). It is not a response format for changes: change events and - * webhook payloads always contain diffs, summaries, and evidence excerpts — never - * data in this schema's shape. If omitted, a default summary + key-points schema - * is used. + * JSON Schema for page selection and the baseline snapshot. Changes return diffs + * and evidence. */ schema?: { [key: string]: unknown }; } /** - * Set to null to remove the webhook. + * Set to null to remove the webhook. Changing `url` issues a new secret. */ export interface Webhook { /** - * Webhook URL events are delivered to. Slack incoming webhook URLs are - * automatically formatted as Slack messages. + * Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted + * messages. */ url: string; /** - * Events delivered to this endpoint. `change.detected` fires only when a run - * detects a change; `run.completed` fires on every completed run — including runs - * that detected no change — and embeds the change when one was detected. Defaults - * to `["change.detected"]` when omitted. + * Events to deliver. Defaults to `change.detected`; `run.completed` also includes + * unchanged runs. */ events?: Array<'change.detected' | 'run.completed'>; @@ -3155,8 +3630,8 @@ export interface MonitorListParams { q?: string; /** - * Comma-separated fields to search with `q`. Defaults to all of them. Note - * `instructions` only exists on extract monitors. + * Fields to search with `q`. Defaults to all fields; page and extract targets can + * have instructions. */ search_by?: Array<'name' | 'url' | 'instructions' | 'tags'> | null; @@ -3303,6 +3778,9 @@ export interface MonitorListRunsParams { } export interface MonitorRetrieveRunParams { + /** + * ID of the monitor. + */ monitor_id: string; } diff --git a/src/resources/news.ts b/src/resources/news.ts index e5f72573..c857c1bc 100644 --- a/src/resources/news.ts +++ b/src/resources/news.ts @@ -5,23 +5,19 @@ import { APIPromise } from '../core/api-promise'; import { RequestOptions } from '../internal/request-options'; /** - * Search live first-party RSS and free historical news data by company identity. + * Search live and historical news about a company. */ export class News extends APIResource { /** - * Searches live and historical company news for one company, identified in - * searchBy by name, domain, ticker (optionally disambiguated by exchange), or - * ISIN. Results can be filtered by one of publisher domain, publisher country, - * article language, or article type, optionally combined with a published-at date - * range, and include stable story IDs, source metadata, verified entity relevance, - * and cursor pagination. + * Find company news by name, domain, ticker, or ISIN. Filter articles and continue + * through results with a cursor. * * @example * ```ts * const response = await client.news.search({ * searchBy: { - * entity: { name: 'xx', type: 'name' }, * type: 'entity', + * entity: { type: 'domain', domain: 'stripe.com' }, * }, * }); * ``` @@ -54,13 +50,13 @@ export interface NewsSearchResponse { next_cursor: string | null; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: NewsSearchResponse.KeyMetadata; } @@ -182,11 +178,11 @@ export namespace NewsSearchResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -226,7 +222,7 @@ export interface NewsSearchParams { sortBy?: NewsSearchParams.SortBy; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; } @@ -261,6 +257,9 @@ export namespace NewsSearchParams { */ name: string; + /** + * Use `name` to identify the company by name. + */ type: 'name'; } @@ -273,6 +272,9 @@ export namespace NewsSearchParams { */ domain: string; + /** + * Use `domain` to identify the company by website domain. + */ type: 'domain'; } @@ -285,6 +287,9 @@ export namespace NewsSearchParams { */ ticker: string; + /** + * Use `ticker` to identify a publicly traded company. + */ type: 'ticker'; /** @@ -375,6 +380,9 @@ export namespace NewsSearchParams { */ isin: string; + /** + * Use `isin` to identify the company by its securities identifier. + */ type: 'isin'; } } diff --git a/src/resources/parse.ts b/src/resources/parse.ts index cf7f74e7..19dc04e4 100644 --- a/src/resources/parse.ts +++ b/src/resources/parse.ts @@ -8,8 +8,7 @@ import { RequestOptions } from '../internal/request-options'; export class Parse extends APIResource { /** - * Converts raw text, source code, web/data, PDF, Microsoft Office, and image bytes - * into LLM-usable Markdown. + * Convert uploaded file bytes into Markdown and optional HTML. */ handle( body: Uploadable, @@ -55,8 +54,8 @@ export interface ParseHandleResponse { markdown: string; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -112,18 +111,18 @@ export interface ParseHandleResponse { | 'pnm'; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: ParseHandleResponse.KeyMetadata; } export namespace ParseHandleResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -227,11 +226,8 @@ export interface ParseHandleParams { includeLinks?: boolean; /** - * Query param: When true for PDF inputs, OCR the selected pages that have no - * usable text layer (scans), replacing each recovered page's text with the OCR - * result while pages with a real text layer keep it. pdf.start/pdf.end limit the - * inclusive page range. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. When false, no OCR runs. + * Query param: Read text from images and scanned PDF pages. PDF page ranges still + * apply. */ ocr?: boolean; @@ -247,8 +243,8 @@ export interface ParseHandleParams { shortenBase64Images?: boolean; /** - * Query param: Comma-separated tags for tracking request usage. Up to 20 tags, - * each 1-50 characters. + * Query param: Comma-separated labels for filtering usage, e.g. + * `production,team-alpha`. */ tags?: Array; @@ -258,11 +254,8 @@ export interface ParseHandleParams { useMainContentOnly?: boolean; /** - * Query param: Set to enabled to bypass shared caches and omit request and - * response content from retained usage logs. Asset uploads are skipped, so hosted - * image URLs are omitted. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * Query param: `enabled` turns on zero data retention. Returns 403 + * `ZDR_NOT_ENABLED` unless your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } diff --git a/src/resources/people.ts b/src/resources/people.ts index 9ebccb35..e20303b5 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -6,10 +6,8 @@ import { RequestOptions } from '../internal/request-options'; export class People extends APIResource { /** - * Finds and normalizes the best available person candidate from additive identity - * clues, then assigns an identity match score from 0 to 100. Available on all paid - * plans. Successful requests cost 20 credits. Disposable and free email addresses - * (like gmail.com, yahoo.com) will throw a 422 error. + * Find a person from identity clues and return their profile with a match score. + * Requires a paid plan; free or disposable email addresses return 422. * * @example * ```ts @@ -39,13 +37,13 @@ export interface PersonEnrichResponse { | PersonEnrichResponse.PersonEnrichmentNotFoundMatch; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: PersonEnrichResponse.KeyMetadata; @@ -265,11 +263,11 @@ export namespace PersonEnrichResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -281,95 +279,160 @@ export namespace PersonEnrichResponse { } export interface PersonEnrichParams { + /** + * Company context to help identify the person. Provide a name or domain. + */ company?: PersonEnrichParams.Company; + /** + * Education history to help distinguish people with similar names. + */ education?: Array; + /** + * Email address of the person to find. + */ email?: string; + /** + * Location context to help identify the person. Provide a city, region, or + * country. + */ location?: PersonEnrichParams.Location; + /** + * Person name. Without an email or person-profile URL, provide both first and last + * name plus company, education, or location. + */ name?: PersonEnrichParams.Name; + /** + * Public profile URLs for the person. A person-profile URL can identify the person + * without a name. + */ social_urls?: Array; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: PersonEnrichParams.TimeoutOpts; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace PersonEnrichParams { + /** + * Company context to help identify the person. Provide a name or domain. + */ export interface Company { + /** + * Website domain of a company associated with the person. + */ domain?: string; + /** + * Name of a company associated with the person. + */ name?: string; } export interface Education { + /** + * Degree or qualification earned. + */ degree?: string; + /** + * Subject or major studied. + */ field_of_study?: string; + /** + * Four-digit graduation year. + */ graduation_year?: number; + /** + * School or university, identified by name or domain. + */ institution?: Education.Institution; } export namespace Education { + /** + * School or university, identified by name or domain. + */ export interface Institution { + /** + * Website domain of the school or university. + */ domain?: string; + /** + * Name of the school or university. + */ name?: string; } } + /** + * Location context to help identify the person. Provide a city, region, or + * country. + */ export interface Location { + /** + * City associated with the person. + */ city?: string; + /** + * Country associated with the person. + */ country?: string; + /** + * State, province, or region associated with the person. + */ region?: string; } + /** + * Person name. Without an email or person-profile URL, provide both first and last + * name plus company, education, or location. + */ export interface Name { + /** + * First or given name. + */ first?: string; + /** + * Last or family name. + */ last?: string; } /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } diff --git a/src/resources/utility.ts b/src/resources/utility.ts index 683b587c..566199d9 100644 --- a/src/resources/utility.ts +++ b/src/resources/utility.ts @@ -6,16 +6,12 @@ import { RequestOptions } from '../internal/request-options'; export class Utility extends APIResource { /** - * Signal that you may fetch data soon to improve latency. The type field selects - * what to prefetch ('brand' queues a brand data fetch, 'styleguide' queues a - * styleguide extraction) and identifier carries exactly one lookup key: a domain, - * or an email whose domain is extracted and validated (free email providers and - * disposable email addresses are not allowed). + * Queue brand or styleguide data so a later lookup can return sooner. * * @example * ```ts * const response = await client.utility.prefetch({ - * identifier: { domain: 'xxx' }, + * identifier: { domain: 'stripe.com' }, * type: 'brand', * }); * ``` @@ -27,8 +23,8 @@ export class Utility extends APIResource { export interface UtilityPrefetchResponse { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -38,7 +34,7 @@ export interface UtilityPrefetchResponse { domain?: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: UtilityPrefetchResponse.KeyMetadata; @@ -48,7 +44,7 @@ export interface UtilityPrefetchResponse { message?: string; /** - * Status of the response, e.g., 'ok' + * Always `ok` on success. */ status?: string; @@ -60,11 +56,11 @@ export interface UtilityPrefetchResponse { export namespace UtilityPrefetchResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -84,20 +80,17 @@ export interface UtilityPrefetchParams { | UtilityPrefetchParams.UtilityPrefetchEmailIdentifier; /** - * What to prefetch: 'brand' warms the brand data cache, 'styleguide' warms the - * styleguide cache. + * Data to prefetch. */ type: 'brand' | 'styleguide'; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: UtilityPrefetchParams.TimeoutOpts; } @@ -108,7 +101,7 @@ export namespace UtilityPrefetchParams { */ export interface UtilityPrefetchDomainIdentifier { /** - * Domain name to prefetch data for + * Domain, e.g. `stripe.com`. */ domain: string; } @@ -126,19 +119,16 @@ export namespace UtilityPrefetchParams { } /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. This endpoint supports "fail": return 408 - * REQUEST_TIMEOUT without charging credits. + * Only "fail" is supported: return 408 at the deadline. */ behavior?: 'fail'; } diff --git a/src/resources/web.ts b/src/resources/web.ts index 5462aeb7..1a0de436 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -6,11 +6,8 @@ import { RequestOptions } from '../internal/request-options'; export class Web extends APIResource { /** - * Researches the live web and returns a sourced answer in your requested JSON - * shape. Select fast for a smaller research budget at 10 credits or ultra for - * deeper reasoning at 100 credits. Defaults to ultra. Fast research is limited to - * 30 seconds and ultra to 50 seconds; timeoutOpts.milliseconds can shorten either - * deadline. + * Research the web and return a sourced answer in your JSON shape. Choose `fast` + * for a short task or `ultra` for deeper research. * * @example * ```ts @@ -47,8 +44,7 @@ export class Web extends APIResource { } /** - * Extract a comprehensive design system from a website including colors, - * typography, spacing, shadows, and UI components. + * Extract colors, typography, spacing, and component styles from a website. * * @example * ```ts @@ -63,19 +59,13 @@ export class Web extends APIResource { } /** - * Discovers URLs using the same sitemap crawl, filters, and limits as - * /web/scrape/sitemap. Each URL includes its available title, description, - * keywords, and language. URLs without stored enrichment are returned immediately - * with only the URL and queued for background HTML scraping, so later requests can - * include their metadata. Responses are never cached as a whole; every request - * reads the current per-URL enrichment. Zero data retention and credential-bearing - * discovery requests return URLs without reading or storing shared enrichment or - * queuing background scrapes. Costs 1 credit, or 2 credits with search. + * Discover a site's URLs, with page titles, descriptions, keywords, and language + * when available. Metadata can be missing on newly discovered URLs. * * @example * ```ts * const response = await client.web.mapUrls({ - * domain: 'xxx', + * domain: 'stripe.com', * }); * ``` */ @@ -84,31 +74,13 @@ export class Web extends APIResource { } /** - * Reuse cached outputs independently and capture missing formats in one page - * visit. Each cache key includes only the settings that affect that output. HTML - * is shared with Markdown, parsed fields, product data, highlights, and JSON - * extraction. Cached outputs can come from different visits within maxAgeMs; use 0 - * for a fresh capture. HTML-only requests use the existing fast acquisition path. - * Highlights return Markdown excerpts most relevant to highlightsParams.query. - * Requests with at least one successful output cost one base credit, including - * cache hits, or two with browser actions. All-failed responses are unbilled - * except missing pages, which retain the base price and the one-credit product - * charge when product was requested. Highlights add 3 credits when passages are - * returned. JSON extraction runs an LLM over nonempty page Markdown and adds four - * credits only when its result is returned successfully. PDF OCR adds one credit - * per recovered page on fresh extraction. Product adds one credit when its - * successful result is returned, plus six if that result used the specialized - * model. Original response bytes and screenshots are limited to 20 MiB each, - * screenshots to 40 megapixels, and the combined response to 60 MiB. An oversized - * output has success: false and data: null. If the combined response exceeds its - * limit, the largest outputs are marked failed until the remaining outputs fit. - * Valid captured pieces may still be cached when omitted to meet the response size - * limit. + * Returns the outputs you enable in `formats` from one visit to a URL. Each output + * reports its own `success`, so a failed output does not fail the request. * * @example * ```ts * const response = await client.web.scrape({ - * formats: { html: true }, + * formats: { markdown: true }, * url: 'https://example.com', * }); * ``` @@ -133,11 +105,14 @@ export class Web extends APIResource { } /** - * Search the web and optionally scrape each result to Markdown in one round-trip. + * Search the web and optionally return page content with each result. * * @example * ```ts - * const response = await client.web.search({ query: 'x' }); + * const response = await client.web.search({ + * query: 'Stripe API authentication', + * numResults: 10, + * }); * ``` */ search(body: WebSearchParams, options?: RequestOptions): APIPromise { @@ -145,13 +120,14 @@ export class Web extends APIResource { } /** - * Performs a crawl starting from a given URL, extracts page content as Markdown, - * and returns results for all crawled pages. + * Crawl a website and return page content as Markdown. Use a batch for crawls + * beyond 500 pages. * * @example * ```ts * const response = await client.web.webCrawlMd({ * url: 'https://example.com', + * maxPages: 10, * }); * ``` */ @@ -173,7 +149,7 @@ export interface WebAnswersResponse { sources: Array; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebAnswersResponse.KeyMetadata; @@ -186,11 +162,11 @@ export interface WebAnswersResponse { export namespace WebAnswersResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -213,8 +189,8 @@ export interface WebExtractCompetitorsResponse { domain: string; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -229,7 +205,7 @@ export interface WebExtractCompetitorsResponse { target: WebExtractCompetitorsResponse.Target; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebExtractCompetitorsResponse.KeyMetadata; @@ -299,11 +275,11 @@ export namespace WebExtractCompetitorsResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -316,15 +292,13 @@ export namespace WebExtractCompetitorsResponse { export interface WebExtractStyleguideResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: WebExtractStyleguideResponse.CacheMetadata; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -339,21 +313,18 @@ export interface WebExtractStyleguideResponse { domain?: string; /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. + * `loaded`, or `still-loading` when capture ended before the page finished + * loading. */ finalDOMState?: 'loaded' | 'still-loading'; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebExtractStyleguideResponse.KeyMetadata; /** - * Status of the response, e.g., 'ok' + * Always `ok` on success. */ status?: string; @@ -365,9 +336,7 @@ export interface WebExtractStyleguideResponse { export namespace WebExtractStyleguideResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -383,11 +352,11 @@ export namespace WebExtractStyleguideResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -525,7 +494,7 @@ export namespace WebExtractStyleguideResponse { minHeight: string; /** - * Sampled minimum width of the button box (typically px) + * Minimum width (usually px). */ minWidth: string; @@ -586,7 +555,7 @@ export namespace WebExtractStyleguideResponse { minHeight: string; /** - * Sampled minimum width of the button box (typically px) + * Minimum width (usually px). */ minWidth: string; @@ -647,7 +616,7 @@ export namespace WebExtractStyleguideResponse { minHeight: string; /** - * Sampled minimum width of the button box (typically px) + * Minimum width (usually px). */ minWidth: string; @@ -790,7 +759,7 @@ export namespace WebExtractStyleguideResponse { fontFallbacks: Array; /** - * Primary face (first family in the computed stack) + * First font in the stack. */ fontFamily: string; @@ -810,7 +779,7 @@ export namespace WebExtractStyleguideResponse { fontFallbacks: Array; /** - * Primary face (first family in the computed stack) + * First font in the stack. */ fontFamily: string; @@ -830,7 +799,7 @@ export namespace WebExtractStyleguideResponse { fontFallbacks: Array; /** - * Primary face (first family in the computed stack) + * First font in the stack. */ fontFamily: string; @@ -850,7 +819,7 @@ export namespace WebExtractStyleguideResponse { fontFallbacks: Array; /** - * Primary face (first family in the computed stack) + * First font in the stack. */ fontFamily: string; @@ -871,7 +840,7 @@ export namespace WebExtractStyleguideResponse { fontFallbacks: Array; /** - * Primary face (first family in the computed stack) + * First font in the stack. */ fontFamily: string; @@ -891,8 +860,8 @@ export interface WebMapURLsResponse { domain: string; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -901,7 +870,7 @@ export interface WebMapURLsResponse { urls: Array; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebMapURLsResponse.KeyMetadata; @@ -922,11 +891,11 @@ export namespace WebMapURLsResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -939,22 +908,18 @@ export namespace WebMapURLsResponse { export interface WebScrapeResponse { /** - * Original HTTP response body. Waiting, actions, and content filters never change - * it. + * The original HTTP response body, unchanged by waits, actions, and filters. */ bytes: WebScrapeResponse.Bytes; /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: WebScrapeResponse.CacheMetadata; /** - * Relevant Markdown excerpts for your question or topic, in page order. Headings - * in square brackets supply necessary context; ellipses mark omitted portions. - * Empty when the page has no text. + * Relevant Markdown excerpts in page order. `[Heading]` adds context; `…` marks + * omitted text. */ highlights: WebScrapeResponse.Highlights; @@ -964,12 +929,12 @@ export interface WebScrapeResponse { html: WebScrapeResponse.HTML; /** - * Images after content filters. Empty when none are found. + * Images after content filters. `[]` when none are found. */ images: WebScrapeResponse.Images; /** - * Page data extracted using your schema. + * Object matching `jsonParams.schema`. */ json: WebScrapeResponse.Json; @@ -979,12 +944,13 @@ export interface WebScrapeResponse { markdown: WebScrapeResponse.Markdown; /** - * Page details, when available. + * Page metadata. Fields are omitted when not found. */ metadata: WebScrapeResponse.Metadata; /** - * Fields produced by parseParams.rules, after shared content filters. + * Fields from `parseParams.rules`, after content filters. Unmatched fields are + * `null` (`[]` for lists). */ parsed: WebScrapeResponse.Parsed; @@ -994,13 +960,13 @@ export interface WebScrapeResponse { product: WebScrapeResponse.Product; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * An image data URL. Use directly as an image src. + * Screenshot as a base64 image data URL. */ screenshot: WebScrapeResponse.Screenshot; @@ -1010,24 +976,20 @@ export interface WebScrapeResponse { url: string; /** - * Present when at least one requested output succeeds while another fails, or when - * successful outputs come from a page that is still loading or images returned - * before processing finished. Absent when every requested output fails. Check each - * output's success field for its result. Valid captured pieces may be cached - * independently; failed retrievals and incomplete captures are not cached. + * True when at least one requested output succeeds but the response has failed or + * incomplete outputs. Absent when all requested outputs fail. */ isPartial?: true; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebScrapeResponse.KeyMetadata; } export namespace WebScrapeResponse { /** - * Original HTTP response body. Waiting, actions, and content filters never change - * it. + * The original HTTP response body, unchanged by waits, actions, and filters. */ export interface Bytes { data: Bytes.Data | null; @@ -1035,7 +997,7 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } @@ -1043,8 +1005,7 @@ export namespace WebScrapeResponse { export namespace Bytes { export interface Data { /** - * Original response body as base64, after HTTP decompression. Maximum decoded - * size: 20 MiB. + * Body as base64, after HTTP decompression. Up to 20 MiB decoded. */ base64: string; @@ -1053,9 +1014,7 @@ export namespace WebScrapeResponse { } /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -1071,9 +1030,8 @@ export namespace WebScrapeResponse { } /** - * Relevant Markdown excerpts for your question or topic, in page order. Headings - * in square brackets supply necessary context; ellipses mark omitted portions. - * Empty when the page has no text. + * Relevant Markdown excerpts in page order. `[Heading]` adds context; `…` marks + * omitted text. */ export interface Highlights { data: Array | null; @@ -1081,7 +1039,7 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } @@ -1095,13 +1053,13 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } /** - * Images after content filters. Empty when none are found. + * Images after content filters. `[]` when none are found. */ export interface Images { data: Array | null; @@ -1109,7 +1067,7 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } @@ -1137,8 +1095,8 @@ export namespace WebScrapeResponse { | 'other'; /** - * Hosted copy when file enrichment is requested and zdr is disabled. Valid for 24 - * hours from the original capture. + * Hosted image URL, valid for 24 hours after capture. Requires `file` enrichment + * and ZDR disabled. */ fileUrl?: string; @@ -1149,7 +1107,7 @@ export namespace WebScrapeResponse { } /** - * Page data extracted using your schema. + * Object matching `jsonParams.schema`. */ export interface Json { data: { [key: string]: unknown } | null; @@ -1157,7 +1115,7 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } @@ -1171,13 +1129,13 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } /** - * Page details, when available. + * Page metadata. Fields are omitted when not found. */ export interface Metadata { /** @@ -1211,8 +1169,7 @@ export namespace WebScrapeResponse { favicon?: string; /** - * Page headings (h1–h6) in document order, extracted from the unfiltered document. - * Capped at the first 500 headings. Omitted when the page has none. + * Up to 500 h1–h6 headings in document order, before content filtering. */ headings?: Array; @@ -1309,7 +1266,8 @@ export namespace WebScrapeResponse { } /** - * Fields produced by parseParams.rules, after shared content filters. + * Fields from `parseParams.rules`, after content filters. Unmatched fields are + * `null` (`[]` for lists). */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1317,7 +1275,7 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } @@ -1331,7 +1289,7 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } @@ -1470,7 +1428,7 @@ export namespace WebScrapeResponse { } /** - * An image data URL. Use directly as an image src. + * Screenshot as a base64 image data URL. */ export interface Screenshot { data: string | null; @@ -1478,17 +1436,17 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -1501,15 +1459,13 @@ export namespace WebScrapeResponse { export interface WebScreenshotResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: WebScreenshotResponse.CacheMetadata; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -1524,11 +1480,8 @@ export interface WebScreenshotResponse { domain?: string; /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. + * `loaded`, or `still-loading` when capture ended before the page finished + * loading. */ finalDOMState?: 'loaded' | 'still-loading'; @@ -1538,7 +1491,7 @@ export interface WebScreenshotResponse { height?: number; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebScreenshotResponse.KeyMetadata; @@ -1554,7 +1507,7 @@ export interface WebScreenshotResponse { screenshotType?: 'viewport' | 'fullPage'; /** - * Status of the response, e.g., 'ok' + * Always `ok` on success. */ status?: string; @@ -1566,9 +1519,7 @@ export interface WebScreenshotResponse { export namespace WebScreenshotResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -1584,11 +1535,11 @@ export namespace WebScreenshotResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -1601,9 +1552,7 @@ export namespace WebScreenshotResponse { export interface WebSearchResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: WebSearchResponse.CacheMetadata; @@ -1613,15 +1562,15 @@ export interface WebSearchResponse { query: string; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; results: Array; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebSearchResponse.KeyMetadata; @@ -1635,9 +1584,7 @@ export interface WebSearchResponse { export namespace WebSearchResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -1697,22 +1644,19 @@ export namespace WebSearchResponse { markdown: string | null; /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. + * `loaded`, or `still-loading` when capture ended before the page finished + * loading. */ finalDOMState?: 'loaded' | 'still-loading'; } } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -1725,24 +1669,22 @@ export namespace WebSearchResponse { export interface WebWebCrawlMdResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: WebWebCrawlMdResponse.CacheMetadata; metadata: WebWebCrawlMdResponse.Metadata; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; results: Array; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebWebCrawlMdResponse.KeyMetadata; @@ -1756,9 +1698,7 @@ export interface WebWebCrawlMdResponse { export namespace WebWebCrawlMdResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -1973,11 +1913,11 @@ export namespace WebWebCrawlMdResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -1990,66 +1930,51 @@ export namespace WebWebCrawlMdResponse { export interface WebAnswersParams { /** - * What to research and answer, in plain language. Naming a domain in the task (for - * example "pricing on context.dev") makes the agent read that site before it - * searches. + * Research task. Name a domain to have it read before searching. */ task: string; /** - * An example object with placeholder values (for example {"pricing_page_url": "", - * "plans": [{"name": "", "price": 0}]}). Object keys and value types are - * preserved; unknown values may be null. Empty arrays accept any JSON items. - * Defaults to {"result": ""}. Maximum 8 levels, 500 values, and 16000 characters. + * Example answer object, not JSON Schema. Up to 8 levels, 500 values, and 16000 + * characters; unknowns may be null. */ json_format?: { [key: string]: unknown }; /** - * Research level: fast uses a smaller model and research budget for 10 credits; - * ultra uses deeper reasoning and research for 100 credits. Defaults to ultra. - * Only successful requests consume credits. + * `fast` for short tasks; `ultra` for deeper research (default). */ mode?: 'fast' | 'ultra'; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: WebAnswersParams.TimeoutOpts; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace WebAnswersParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -2068,45 +1993,35 @@ export interface WebExtractCompetitorsParams { numCompetitors?: number; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: WebExtractCompetitorsParams.TimeoutOpts; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace WebExtractCompetitorsParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -2120,10 +2035,7 @@ export interface WebExtractStyleguideParams { colorScheme?: 'light' | 'dark'; /** - * A specific URL to fetch the styleguide from directly, bypassing domain - * resolution (e.g., 'https://example.com/design-system'). When provided, the - * styleguide is extracted from this exact URL. You must provide either 'domain' or - * 'directUrl', but not both. + * Exact URL to inspect. Provide either `domain` or `directUrl`, not both. */ directUrl?: string; @@ -2135,54 +2047,41 @@ export interface WebExtractStyleguideParams { domain?: string; /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. + * Maximum age of cached brand data in ms. Defaults to 3 months; clamped to 0–1 + * year. `0` refreshes. */ maxAgeMs?: number | null; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: WebExtractStyleguideParams.TimeoutOpts; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace WebExtractStyleguideParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. "return-partial" requires at least 5000 ms. */ behavior?: 'fail' | 'return-partial'; } @@ -2190,52 +2089,43 @@ export namespace WebExtractStyleguideParams { export interface WebMapURLsParams { /** - * Domain to build a sitemap for + * Domain to map, e.g. `stripe.com`. */ domain: string; /** - * Optional outbound HTTP headers forwarded only to the target URL, sent as - * deep-object query params such as headers[X-Custom]=value. When provided, caching - * is bypassed: the result is neither read from nor written to cache. + * HTTP headers for the target origin. Non-empty headers bypass caching. */ headers?: { [key: string]: string }; /** - * When true, discover and include public pages and sitemaps on subdomains of the - * requested domain. Defaults to false. + * Include URLs on subdomains. */ includeSubdomains?: boolean; /** - * Maximum number of links to return from the sitemap crawl. Defaults to 10,000. - * Minimum is 1, maximum is 100,000. + * Maximum number of URLs to return. */ maxLinks?: number; /** - * Optional search phrase. When provided, the crawled sitemap is filtered to the - * pages whose URLs are about that phrase, most relevant first, and the request - * costs 2 credits instead of 1. + * Filter URLs by a topic or phrase, most relevant first. */ search?: string; /** - * Optional explicit sitemap URL. When provided, exactly this sitemap is crawled - * instead of discovering the domain's sitemaps. + * Fetch this sitemap instead of discovering sitemaps. Must belong to the domain or + * a subdomain. */ sitemapUrl?: string; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: WebMapURLsParams.TimeoutOpts; @@ -2246,32 +2136,25 @@ export interface WebMapURLsParams { urlRegex?: string; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace WebMapURLsParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -2279,17 +2162,17 @@ export namespace WebMapURLsParams { export interface WebScrapeParams { /** - * Outputs to return. Enable at least one; omitted formats are false. + * Outputs to return. Set at least one to `true`. */ formats: WebScrapeParams.Formats; /** - * The URL to scrape. + * Public HTTP or HTTPS URL to scrape. */ url: string; /** - * Highlight options. Requires formats.highlights: true. + * Required when `formats.highlights` is `true`. */ highlightsParams?: WebScrapeParams.HighlightsParams; @@ -2304,15 +2187,13 @@ export interface WebScrapeParams { jsonParams?: WebScrapeParams.JsonParams; /** - * Markdown options. Requires formats.markdown: true. + * Markdown options. Requires `formats.markdown`. */ markdownParams?: WebScrapeParams.MarkdownParams; /** - * Maximum age of each cached output. Defaults to 1 day; 0 fetches fresh and - * updates the requested outputs. Compatible outputs are shared with the individual - * scrape endpoints. Image results with hosted files refresh after 23 hours; other - * outputs retain their own freshness. + * Maximum age of a cached output, in milliseconds. `0` fetches fresh. Defaults to + * 1 day. */ maxAgeMs?: number; @@ -2332,8 +2213,7 @@ export interface WebScrapeParams { screenshotParams?: WebScrapeParams.ScreenshotParams; /** - * Shared browser and content settings. Content filters leave screenshots and - * original bytes unchanged. + * Browser and content settings shared by all outputs. */ sharedParams?: WebScrapeParams.SharedParams; @@ -2343,30 +2223,20 @@ export interface WebScrapeParams { tags?: Array; /** - * Total deadline, including navigation, actions, waiting, and all outputs. - * Defaults to 60000 milliseconds with behavior fail. Individual outputs have - * internal deadlines that reserve time to return completed outputs; timed-out - * outputs have success: false and data: null under either behavior. The overall - * request deadline remains enforced: fail returns an error if that deadline is - * reached. Use return-partial to allow the current page state and available - * outputs when the page is still loading. Partial responses set isPartial. Failed - * retrievals and incomplete captures are not cached; valid captured pieces may be - * cached independently. Fixed waits must fit before a response reserve of up to - * 5000 milliseconds (at most one quarter of the timeout) when using - * return-partial. + * Deadline for the whole request. Defaults to 60000 ms with `fail`. Fixed waits + * must end before it. */ timeoutOpts?: WebScrapeParams.TimeoutOpts; /** - * Zero data retention. Bypasses caches and uploads; excludes request/response - * content and tags from logs. Must be enabled for your organization. + * `enabled` turns on zero data retention. Your organization must have ZDR enabled. */ zdr?: 'enabled' | 'disabled'; } export namespace WebScrapeParams { /** - * Outputs to return. Enable at least one; omitted formats are false. + * Outputs to return. Set at least one to `true`. */ export interface Formats { /** @@ -2375,9 +2245,7 @@ export namespace WebScrapeParams { bytes?: boolean; /** - * Relevant Markdown excerpts for your question or topic, preserving code, lists, - * and tables, with headings included when needed for context. Adds 3 credits when - * passages are returned. + * Markdown excerpts relevant to `highlightsParams.query`. */ highlights?: boolean; @@ -2392,8 +2260,7 @@ export namespace WebScrapeParams { images?: boolean; /** - * Page data extracted using your schema. Adds 4 credits when extraction succeeds - * and its result is returned. + * An object matching `jsonParams.schema`, extracted from the page. */ json?: boolean; @@ -2403,24 +2270,23 @@ export namespace WebScrapeParams { markdown?: boolean; /** - * Fields selected by parseParams.rules. + * Fields extracted with `parseParams.rules`, returned as `parsed`. */ parse?: boolean; /** - * Product details such as name, price, and availability. Adds 1 credit when its - * successful result is returned or the target page is missing. + * Product details such as name, price, and availability. */ product?: boolean; /** - * An inline image of the page. + * A screenshot of the page. */ screenshot?: boolean; } /** - * Highlight options. Requires formats.highlights: true. + * Required when `formats.highlights` is `true`. */ export interface HighlightsParams { /** @@ -2429,7 +2295,7 @@ export namespace WebScrapeParams { query: string; /** - * Maximum combined length of the returned passages, in characters. + * Maximum combined length of returned passages. */ maxCharacters?: number; } @@ -2439,14 +2305,12 @@ export namespace WebScrapeParams { */ export interface ImageParams { /** - * For visual duplicates, keep the largest image. + * Set `visual` to drop visual duplicates, keeping the largest copy. */ dedupe?: 'none' | 'visual'; /** - * Add dimensions, a visual category, or a hosted file URL. Each image has a - * maximum processing time of 30000 milliseconds, bounded by the remaining request - * deadline. + * Extra data per image: `dimensions`, `classification`, or a hosted `file` URL. */ enrich?: Array<'dimensions' | 'classification' | 'file'>; } @@ -2456,31 +2320,34 @@ export namespace WebScrapeParams { */ export interface JsonParams { /** - * JSON Schema for the returned object. Must describe a top-level object; at most - * 50 KB serialized. Optional fields the page does not state are omitted, or null - * when their type allows null, while required non-nullable fields always receive a - * best-effort value, so prefer nullable or optional fields for data a page may - * omit. Zod users can pass the output of z.toJSONSchema(). + * JSON Schema for a top-level object, up to 50 KB. Use optional or nullable fields + * for missing facts. */ schema: { [key: string]: unknown }; /** - * Optional guidance on which facts to prioritize or how to interpret schema - * fields. + * Extra guidance, such as which facts to prefer or how to read a field. */ instructions?: string; } /** - * Markdown options. Requires formats.markdown: true. + * Markdown options. Requires `formats.markdown`. */ export interface MarkdownParams { + /** + * Include images in the Markdown using image syntax with URLs and alt text. + */ includeImages?: boolean; + /** + * Keep link URLs in the Markdown. Set false to return link text without URLs. + */ includeLinks?: boolean; /** - * Base64 images use placeholders by default. Requires includeImages: true. + * How base64 images appear: `placeholder` (default) or `preserve`. Requires + * `includeImages`. */ inlineImages?: 'placeholder' | 'preserve'; } @@ -2490,18 +2357,28 @@ export namespace WebScrapeParams { */ export interface ParseParams { /** - * Map field names to CSS selectors or rules. Missing items return null; missing - * lists return []. + * Field names mapped to CSS selectors (`h1`, `a@href`) or rule objects. Max 100 + * fields, 5 levels. */ rules: { [key: string]: string | ParseParams.UnionMember1 }; } export namespace ParseParams { export interface UnionMember1 { + /** + * CSS selector to match within the current page or parent rule. + */ selector: string; + /** + * Return text, HTML, an attribute such as `@href`, or nested field rules. Defaults + * to text. + */ output?: 'text' | 'html' | string | unknown; + /** + * Return the first match with `item` or all matches with `list`. + */ type?: 'item' | 'list'; } } @@ -2511,11 +2388,7 @@ export namespace WebScrapeParams { */ export interface ProductParams { /** - * Extract the product with a specialized model when the page has no structured - * product data. Adds six credits when the model verdict is returned successfully. - * If the fallback fails, the product output has success: false and data: null with - * no fallback charge; other outputs remain available. Request deadlines and client - * disconnects still apply. + * Use an AI model when the page has no structured product data. */ useAIFallback?: boolean; } @@ -2525,17 +2398,21 @@ export namespace WebScrapeParams { */ export interface ScreenshotParams { /** - * Viewport, full page, one visible element, or a rectangle. Maximum 40 megapixels. + * What to capture: `viewport`, `fullPage`, one element, or a rectangle. Max 40 + * megapixels. */ area?: 'viewport' | 'fullPage' | ScreenshotParams.Element | ScreenshotParams.Rectangle; + /** + * Image format for the screenshot. + */ format?: 'png' | 'jpeg' | 'webp'; } export namespace ScreenshotParams { export interface Element { /** - * Must match one visible element. + * CSS selector matching exactly one visible element. */ selector: string; } @@ -2544,66 +2421,76 @@ export namespace WebScrapeParams { * Pixels from the document origin. */ export interface Rectangle { + /** + * Height of the capture in pixels. + */ height: number; + /** + * Width of the capture in pixels. + */ width: number; + /** + * Left edge of the capture, in pixels from the document origin. + */ x: number; + /** + * Top edge of the capture, in pixels from the document origin. + */ y: number; } } /** - * Shared browser and content settings. Content filters leave screenshots and - * original bytes unchanged. + * Browser and content settings shared by all outputs. */ export interface SharedParams { /** - * Run in order before capture. A failed action fails the request. Bypasses - * caching. + * Browser steps run in order before capture. Requires a paid plan. Skips the + * cache. */ actions?: Array; /** - * Supported two-letter country code, case-insensitive. Applies to every output, - * including image downloads. + * Proxy country as a two-letter code, such as `US`. Case-insensitive. */ country?: string; /** - * Dismiss cookie banners by accepting cookies before actions. + * Accept cookie banners before actions and capture. */ dismissCookies?: boolean; /** - * Dismiss other popups before actions. + * Close other popups before actions and capture. */ dismissPopups?: boolean; /** - * Remove matching content. Exclusions win. + * Remove elements matching these CSS selectors. Overrides `includeSelectors`. */ excludeSelectors?: Array; /** - * Headers for the target origin. Requests with custom headers bypass caching. + * HTTP headers to send to the target site. Requests with headers skip the cache. */ headers?: { [key: string]: string }; /** - * Include iframe content in extraction. Screenshots show visible frames - * regardless. + * Include iframe content in HTML and text outputs. Screenshots always show visible + * frames. */ includeFrames?: boolean; /** - * Keep matching content after mainContentOnly. + * Keep only elements matching these CSS selectors. */ includeSelectors?: Array; /** - * Keep only main content in HTML, Markdown, images, and parsed fields. + * Keep only the main content. Doesn't affect `screenshot`, `bytes`, or `product`. */ mainContentOnly?: boolean; @@ -2613,42 +2500,61 @@ export namespace WebScrapeParams { parsers?: SharedParams.Parsers; /** - * Settle animations before capture. Defaults to true with screenshots, otherwise - * false. + * Wait for CSS animations to finish before capture. Defaults to `true` when + * `screenshot` is requested. */ settleAnimations?: boolean; /** - * Override the browser color scheme. + * Emulate a light or dark color scheme. */ theme?: 'light' | 'dark'; /** - * Browser dimensions in pixels. + * Browser size in pixels. Omit for 1920 × 1080. When provided, missing dimensions + * default to 1440 × 900. */ viewport?: SharedParams.Viewport; /** - * After actions, wait this many milliseconds or until a CSS selector is visible. - * Defaults to 500 ms, or 2000 ms with frames or an XML URL. Set 0 to skip. + * Milliseconds, or a CSS selector to wait for, after actions. Defaults to 500 + * (2000 with frames or XML). */ waitFor?: number | string; } export namespace SharedParams { export interface Perform { + /** + * One browser instruction, such as clicking a button or entering text. + */ action: string; + /** + * Use `perform` for a plain-language browser instruction. + */ type: 'perform'; } export interface Scroll { + /** + * Use `scroll` to move through the page or a container. + */ type: 'scroll'; + /** + * Distance per scroll: pixels, one `viewport`, or `max` to reach the end. + */ amount?: number | 'viewport' | 'max'; + /** + * Direction to scroll. + */ direction?: 'down' | 'up' | 'left' | 'right'; + /** + * Maximum number of scroll steps for this action. + */ maxScrolls?: number; /** @@ -2658,14 +2564,26 @@ export namespace WebScrapeParams { } export interface Wait { + /** + * Time to pause in milliseconds before the next action. + */ milliseconds: number; + /** + * Use `wait` to pause for a fixed duration. + */ type: 'wait'; } export interface WaitFor { + /** + * CSS selector to wait for before continuing. + */ selector: string; + /** + * Use `waitFor` to wait for a matching element. + */ type: 'waitFor'; } @@ -2674,23 +2592,23 @@ export namespace WebScrapeParams { */ export interface Parsers { /** - * PDF text options for HTML, Markdown, and parsed fields. + * PDF page range and OCR. */ pdf?: Parsers.Pdf; } export namespace Parsers { /** - * PDF text options for HTML, Markdown, and parsed fields. + * PDF page range and OCR. */ export interface Pdf { /** - * Last page to parse. Must be at least startPage. + * Last page to parse. Must be at least `startPage`. */ endPage?: number; /** - * Read text from scanned pages. + * Set `auto` to read scanned pages with OCR. */ ocr?: 'off' | 'auto'; @@ -2702,40 +2620,35 @@ export namespace WebScrapeParams { } /** - * Browser dimensions in pixels. + * Browser size in pixels. Omit for 1920 × 1080. When provided, missing dimensions + * default to 1440 × 900. */ export interface Viewport { + /** + * Browser viewport height in pixels. + */ height?: number; + /** + * Browser viewport width in pixels. + */ width?: number; } } /** - * Total deadline, including navigation, actions, waiting, and all outputs. - * Defaults to 60000 milliseconds with behavior fail. Individual outputs have - * internal deadlines that reserve time to return completed outputs; timed-out - * outputs have success: false and data: null under either behavior. The overall - * request deadline remains enforced: fail returns an error if that deadline is - * reached. Use return-partial to allow the current page state and available - * outputs when the page is still loading. Partial responses set isPartial. Failed - * retrievals and incomplete captures are not cached; valid captured pieces may be - * cached independently. Fixed waits must fit before a response reserve of up to - * 5000 milliseconds (at most one quarter of the timeout) when using - * return-partial. + * Deadline for the whole request. Defaults to 60000 ms with `fail`. Fixed waits + * must end before it. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. "return-partial" requires at least 5000 ms. */ behavior?: 'fail' | 'return-partial'; } @@ -2758,8 +2671,7 @@ export interface WebScreenshotParams { colorScheme?: 'light' | 'dark'; /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). + * Fetch from this country (ISO 3166-1 alpha-2). */ country?: | 'ad' @@ -3033,15 +2945,12 @@ export interface WebScreenshotParams { scrollOffset?: number | null; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: WebScreenshotParams.TimeoutOpts; @@ -3060,33 +2969,25 @@ export interface WebScreenshotParams { waitForMs?: number | null; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace WebScreenshotParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. "return-partial" requires at least 5000 ms. */ behavior?: 'fail' | 'return-partial'; } @@ -3387,28 +3288,23 @@ export interface WebSearchParams { numResults?: number; /** - * Expand the query into multiple parallel variants for broader recall. + * Currently has no effect. */ queryFanout?: boolean; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: WebSearchParams.TimeoutOpts; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } @@ -3455,9 +3351,7 @@ export namespace WebSearchParams { shortenBase64Images?: boolean; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: MarkdownOptions.TimeoutOpts; @@ -3496,43 +3390,34 @@ export namespace WebSearchParams { } /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. "return-partial" requires at least 5000 ms. */ behavior?: 'fail' | 'return-partial'; } } /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -3540,13 +3425,12 @@ export namespace WebSearchParams { export interface WebWebCrawlMdParams { /** - * The starting URL for the crawl (must include http:// or https:// protocol) + * Start URL, including `http://` or `https://`. */ url: string; /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). + * Fetch from this country (ISO 3166-1 alpha-2). */ country?: | 'ad' @@ -3755,9 +3639,7 @@ export interface WebWebCrawlMdParams { | 'zw'; /** - * CSS selectors to remove before each crawled page is converted to Markdown. - * Applied after includeSelectors. Exclusion takes precedence: an element matching - * both is removed. Examples: "nav", "footer", ".ad-banner", "[aria-hidden=true]". + * Remove matching elements after inclusions. Exclusions take precedence. */ excludeSelectors?: Array; @@ -3785,17 +3667,12 @@ export interface WebWebCrawlMdParams { includeLinks?: boolean; /** - * CSS selectors. When provided, only matching HTML subtrees (and their - * descendants) are kept before each crawled page is converted to Markdown. When - * omitted, the entire document is kept. Examples: "article.main", "#content", - * "[role=main]". + * Keep matching HTML subtrees before converting each page to Markdown. */ includeSelectors?: Array; /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * Maximum cache age in milliseconds. Defaults to 1 day; `0` fetches fresh. */ maxAgeMs?: number; @@ -3805,20 +3682,18 @@ export interface WebWebCrawlMdParams { maxDepth?: number; /** - * Maximum number of pages to crawl. Hard cap: 500. + * Maximum pages to crawl. */ maxPages?: number; /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ pdf?: WebWebCrawlMdParams.Pdf; /** - * When true, waits briefly for CSS and transition animations to settle before - * extracting each crawled page. Defaults to false. This adds a bit of latency in - * exchange for more stable output on animated pages. + * Wait briefly for CSS animations and transitions to settle before reading each + * page. */ settleAnimations?: boolean; @@ -3828,22 +3703,18 @@ export interface WebWebCrawlMdParams { shortenBase64Images?: boolean; /** - * Soft time budget for the crawl in milliseconds. After each scrape, the crawler - * checks the elapsed time and, if exceeded, returns the pages collected so far - * instead of continuing. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 - * (80s). + * Soft crawl deadline in milliseconds. Returns pages collected before the next + * deadline check. */ stopAfterMs?: number; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: WebWebCrawlMdParams.TimeoutOpts; @@ -3867,18 +3738,15 @@ export interface WebWebCrawlMdParams { waitForMs?: number; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace WebWebCrawlMdParams { /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ export interface Pdf { /** @@ -3888,10 +3756,7 @@ export namespace WebWebCrawlMdParams { end?: number; /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. + * Read scanned PDF pages with OCR; preserve pages that already contain text. */ ocr?: boolean; @@ -3908,21 +3773,17 @@ export namespace WebWebCrawlMdParams { } /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } diff --git a/src/resources/webhooks/deliveries.ts b/src/resources/webhooks/deliveries.ts index 89b1f012..f8ac98f4 100644 --- a/src/resources/webhooks/deliveries.ts +++ b/src/resources/webhooks/deliveries.ts @@ -8,11 +8,11 @@ import { RequestOptions } from '../../internal/request-options'; import { path } from '../../internal/utils/path'; /** - * Inspect and retry webhook deliveries. These endpoints cost no credits. + * Inspect and retry batch and monitor webhook deliveries. */ export class Deliveries extends APIResource { /** - * Get a webhook delivery, including its status and latest attempt. + * Retrieve a webhook delivery’s status and original payload. * * @example * ```ts @@ -30,7 +30,7 @@ export class Deliveries extends APIResource { } /** - * List your batch or monitor webhook deliveries, newest first. + * List batch and monitor webhook deliveries from the last 30 days. * * @example * ```ts @@ -46,7 +46,7 @@ export class Deliveries extends APIResource { } /** - * List delivery attempts, newest first. + * List a delivery’s attempts, newest first. * * @example * ```ts @@ -65,7 +65,8 @@ export class Deliveries extends APIResource { } /** - * Retry a webhook delivery within seven days of creation. + * Resend the original payload using the source’s current URL and secret. Available + * for 7 days after the event. * * @example * ```ts @@ -118,7 +119,7 @@ export interface Attempt { started_at: string; /** - * What started this attempt. + * `initial`, `automatic` (scheduled retry), or `manual` (Retry endpoint). */ trigger: 'initial' | 'automatic' | 'manual'; @@ -192,7 +193,7 @@ export interface Delivery { retry: WebhooksAPI.RetryConfig; /** - * Manual retry deadline, seven days after event creation. + * Last time you can retry manually (7 days after the event). */ retry_expires_at: string; @@ -202,7 +203,8 @@ export interface Delivery { source: Delivery.Batch | Delivery.Monitor; /** - * Current delivery status. + * `pending`, `delivering`, `retrying`, `delivered`, `failed`, or `cancelled` + * (source or its webhook was removed). */ status: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; @@ -235,7 +237,7 @@ export namespace Delivery { batch_id: string; /** - * Delivery source. + * Which deliveries to list: `batch` or `monitor`. */ type: 'batch'; } @@ -252,7 +254,7 @@ export namespace Delivery { run_id: string; /** - * Delivery source. + * Which deliveries to list: `batch` or `monitor`. */ type: 'monitor'; } @@ -290,7 +292,7 @@ export interface DeliverySummary { next_attempt_at: string | null; /** - * Manual retry deadline, seven days after event creation. + * Last time you can retry manually (7 days after the event). */ retry_expires_at: string; @@ -300,7 +302,8 @@ export interface DeliverySummary { source: DeliverySummary.Batch | DeliverySummary.Monitor; /** - * Current delivery status. + * `pending`, `delivering`, `retrying`, `delivered`, `failed`, or `cancelled` + * (source or its webhook was removed). */ status: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; @@ -333,7 +336,7 @@ export namespace DeliverySummary { batch_id: string; /** - * Delivery source. + * Which deliveries to list: `batch` or `monitor`. */ type: 'batch'; } @@ -350,7 +353,7 @@ export namespace DeliverySummary { run_id: string; /** - * Delivery source. + * Which deliveries to list: `batch` or `monitor`. */ type: 'monitor'; } @@ -358,24 +361,24 @@ export namespace DeliverySummary { export interface DeliveryRetrieveResponse extends Delivery { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: DeliveryRetrieveResponse.KeyMetadata; } export namespace DeliveryRetrieveResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -403,24 +406,24 @@ export interface DeliveryListResponse { next_cursor: string | null; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: DeliveryListResponse.KeyMetadata; } export namespace DeliveryListResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -448,24 +451,24 @@ export interface DeliveryListAttemptsResponse { next_cursor: string | null; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: DeliveryListAttemptsResponse.KeyMetadata; } export namespace DeliveryListAttemptsResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -483,24 +486,24 @@ export interface DeliveryRetryResponse { id: string; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: DeliveryRetryResponse.KeyMetadata; } export namespace DeliveryRetryResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -513,8 +516,7 @@ export namespace DeliveryRetryResponse { export interface DeliveryRetrieveParams { /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; } @@ -554,7 +556,7 @@ export declare namespace DeliveryListParams { status?: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; } @@ -596,7 +598,7 @@ export declare namespace DeliveryListParams { status?: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; } @@ -614,21 +616,19 @@ export interface DeliveryListAttemptsParams { limit?: number; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; } export interface DeliveryRetryParams { /** - * Body param: Resend a delivery that already succeeded. + * Body param: Resend even if the delivery already succeeded. Defaults to false. */ force?: boolean; /** - * Body param: Optional tags for tracking usage. Up to 20 tags, each 1 to 50 - * characters. + * Body param: Labels for filtering usage in the dashboard. */ tags?: Array; diff --git a/src/version.ts b/src/version.ts index cc0b2a97..9ca3e095 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.1.0'; // x-release-please-version +export const VERSION = '3.2.0'; // x-release-please-version diff --git a/tests/api-resources/news.test.ts b/tests/api-resources/news.test.ts index 0cc48978..7f486ac7 100644 --- a/tests/api-resources/news.test.ts +++ b/tests/api-resources/news.test.ts @@ -12,7 +12,7 @@ describe('resource news', () => { test.skip('search: only required params', async () => { const responsePromise = client.news.search({ searchBy: { - entity: { name: 'xx', type: 'name' }, + entity: { domain: 'stripe.com', type: 'domain' }, type: 'entity', }, }); @@ -29,7 +29,7 @@ describe('resource news', () => { test.skip('search: required and optional params', async () => { const response = await client.news.search({ searchBy: { - entity: { name: 'xx', type: 'name' }, + entity: { domain: 'stripe.com', type: 'domain' }, type: 'entity', }, cursor: 'cursor', diff --git a/tests/api-resources/utility.test.ts b/tests/api-resources/utility.test.ts index 120bfd69..28ff7a74 100644 --- a/tests/api-resources/utility.test.ts +++ b/tests/api-resources/utility.test.ts @@ -11,7 +11,7 @@ describe('resource utility', () => { // Mock server tests are disabled test.skip('prefetch: only required params', async () => { const responsePromise = client.utility.prefetch({ - identifier: { domain: 'xxx' }, + identifier: { domain: 'stripe.com' }, type: 'brand', }); const rawResponse = await responsePromise.asResponse(); @@ -26,7 +26,7 @@ describe('resource utility', () => { // Mock server tests are disabled test.skip('prefetch: required and optional params', async () => { const response = await client.utility.prefetch({ - identifier: { domain: 'xxx' }, + identifier: { domain: 'stripe.com' }, type: 'brand', tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 9e58d141..b6ace8ef 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -90,7 +90,7 @@ describe('resource web', () => { // Mock server tests are disabled test.skip('mapUrls: only required params', async () => { - const responsePromise = client.web.mapUrls({ domain: 'xxx' }); + const responsePromise = client.web.mapUrls({ domain: 'stripe.com' }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -103,7 +103,7 @@ describe('resource web', () => { // Mock server tests are disabled test.skip('mapUrls: required and optional params', async () => { const response = await client.web.mapUrls({ - domain: 'xxx', + domain: 'stripe.com', headers: { foo: 'J!' }, includeSubdomains: true, maxLinks: 1, @@ -245,7 +245,7 @@ describe('resource web', () => { // Mock server tests are disabled test.skip('search: only required params', async () => { - const responsePromise = client.web.search({ query: 'x' }); + const responsePromise = client.web.search({ query: 'Stripe API authentication' }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -258,7 +258,7 @@ describe('resource web', () => { // Mock server tests are disabled test.skip('search: required and optional params', async () => { const response = await client.web.search({ - query: 'x', + query: 'Stripe API authentication', country: 'af', excludeDomains: ['string'], freshness: 'last_24_hours', @@ -312,7 +312,7 @@ describe('resource web', () => { includeSelectors: ['string'], maxAgeMs: 0, maxDepth: 0, - maxPages: 1, + maxPages: 10, pdf: { end: 1, ocr: true, From 790d1f42e0cd523501a3e7d038be664c64929765 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 27 Sep 2026 08:53:09 +0000 Subject: [PATCH 094/232] docs(openapi): complete concise API reference metadata (#1329) Stainless-Generated-From: 3abeb7b9aecff74a4d98e489f3075e365af60423 --- src/client.ts | 8 +- src/resources/batch.ts | 330 +++--- src/resources/brand.ts | 179 +-- src/resources/feedback.ts | 18 +- src/resources/industry.ts | 86 +- src/resources/logs.ts | 54 +- src/resources/monitors.ts | 1648 +++++++++++++++++--------- src/resources/news.ts | 36 +- src/resources/parse.ts | 31 +- src/resources/people.ts | 115 +- src/resources/utility.ts | 40 +- src/resources/web.ts | 805 ++++++------- src/resources/webhooks/deliveries.ts | 86 +- tests/api-resources/news.test.ts | 4 +- tests/api-resources/utility.test.ts | 4 +- tests/api-resources/web.test.ts | 10 +- 16 files changed, 1846 insertions(+), 1608 deletions(-) diff --git a/src/client.ts b/src/client.ts index 1f9e2d36..f8ca469f 100644 --- a/src/client.ts +++ b/src/client.ts @@ -824,7 +824,7 @@ export class ContextDev { industry: API.Industry = new API.Industry(this); utility: API.Utility = new API.Utility(this); /** - * Monitor pages, sitemaps, and extracted website data for exact or semantic changes. Webhook payloads are documented by the MonitorsChangeDetectedWebhookPayload and MonitorsRunCompletedWebhookPayload schemas. + * Watch websites for exact or meaningful changes. */ monitors: API.Monitors = new API.Monitors(this); /** @@ -834,15 +834,15 @@ export class ContextDev { webhooks: API.Webhooks = new API.Webhooks(this); people: API.People = new API.People(this); /** - * Search live first-party RSS and free historical news data by company identity. + * Search live and historical news about a company. */ news: API.News = new API.News(this); /** - * Read your organization's API request logs to debug failed calls. These endpoints cost no credits and use a separate rate limit. + * Read your organization's API request logs. */ logs: API.Logs = new API.Logs(this); /** - * Report bugs, docs mismatches, and friction with any Context.dev API. Submissions cost no credits and use a separate rate limit. + * Report API issues and documentation mismatches. */ feedback: API.Feedback = new API.Feedback(this); } diff --git a/src/resources/batch.ts b/src/resources/batch.ts index afc77b45..011368c2 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -13,7 +13,8 @@ import { path } from '../internal/utils/path'; */ export class Batch extends APIResource { /** - * Check progress, and get download links once the batch finishes. + * Get batch progress and result download links. Result files are deleted 7 days + * after the batch finishes. * * @example * ```ts @@ -25,8 +26,7 @@ export class Batch extends APIResource { } /** - * List your batches from newest to oldest. Filter by status or continue with a - * cursor. + * List your batches, newest first, with optional filters. * * @example * ```ts @@ -41,8 +41,8 @@ export class Batch extends APIResource { } /** - * Permanently delete a finished batch and its stored results. Active batches must - * settle first. + * Permanently delete a finished batch and its results. Its webhook deliveries can + * no longer be retried. * * @example * ```ts @@ -54,8 +54,8 @@ export class Batch extends APIResource { } /** - * Stop a batch from starting new pages. In-progress pages finish, and unused - * credits are refunded. + * Stop a batch from starting new pages. Pages already in progress finish before + * the batch becomes cancelled. * * @example * ```ts @@ -67,8 +67,8 @@ export class Batch extends APIResource { } /** - * Page through a finished batch's results as JSON instead of downloading the - * NDJSON files. + * Page through a finished batch’s results as JSON. Results remain available for 7 + * days. * * @example * ```ts @@ -86,7 +86,8 @@ export class Batch extends APIResource { } /** - * Scrape 25K URLs or crawl large websites asynchronously. + * Scrape up to 25,000 URLs, or crawl a site, asynchronously. Poll the batch ID or + * receive a webhook when it finishes. * * @example * ```ts @@ -157,8 +158,7 @@ export interface Failure { } /** - * The crawl controls as submitted, so the limits requested can be compared against - * what the crawl reached. + * Crawl settings as submitted. */ export interface CrawlControls { /** @@ -216,7 +216,7 @@ export namespace CrawlControls { } /** - * What submission took in, and what it charged for. + * What the submission accepted. */ export interface Intake { /** @@ -227,23 +227,17 @@ export interface Intake { duplicates: number; /** - * URLs from your list rejected as unusable; the same ones are itemised in - * `invalid_urls` at submission. Null for a crawl — a crawl that resolves no usable - * page is rejected outright with a 400 rather than accepted with an empty list. + * Rejected input URLs; `null` for a crawl. */ invalid: number | null; /** - * Pages credits were reserved for. Everything else — progress, the refund, the - * completion percentage — is measured against this. + * Pages accepted; progress counts toward this total. */ reserved: number; /** - * Whether `reserved` is an upper bound the batch may finish under. True only for a - * crawl that follows links, whose reachable page count is unknowable until it - * runs. False for a scrape and for a sitemap crawl, where `reserved` is an exact - * page count. + * True when `reserved` is a crawl ceiling; false when it is an exact URL count. */ reserved_is_ceiling: boolean; @@ -256,18 +250,17 @@ export interface Intake { export interface BatchRetrieveResponse { /** - * Batch ID used to retrieve or cancel the job. + * Batch ID. */ id: string; /** - * The crawl controls as submitted, so the limits requested can be compared against - * what the crawl reached. + * Crawl settings as submitted. */ crawl: CrawlControls | null; /** - * What this batch has done to your credit balance. + * Batch credit usage and settlement. */ credits: BatchRetrieveResponse.Credits; @@ -284,17 +277,17 @@ export interface BatchRetrieveResponse { format: 'markdown' | 'html'; /** - * What submission took in, and what it charged for. + * What the submission accepted. */ input: Intake; /** - * Rejected URLs, up to 100. These are not charged. + * Rejected URLs (first 100). */ invalid_urls: Array; /** - * How pages were selected. Matches `input.mode` on the submit request. + * `scrape` (URL list) or `crawl`. */ mode: 'scrape' | 'crawl'; @@ -310,14 +303,14 @@ export interface BatchRetrieveResponse { progress: BatchRetrieveResponse.Progress; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * 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. + * Result download links; null until the batch finishes. Files are deleted 7 days + * after the batch finishes. */ results: BatchRetrieveResponse.Results | null; @@ -346,30 +339,26 @@ export interface BatchRetrieveResponse { export namespace BatchRetrieveResponse { /** - * What this batch has done to your credit balance. + * Batch credit usage and settlement. */ export interface Credits { /** - * `reserved` minus `refunded` plus `ocr_charged` — what the batch has cost so far. - * Equal to `reserved` until the batch settles. + * `reserved` minus `refunded` plus `ocr_charged`. */ net: number; /** - * Credits charged for PDF pages recovered by OCR (pdf.ocr=true), 1 per recovered - * page, on top of `reserved`. Stays 0 until the batch settles. + * OCR usage charged when the batch settles. */ ocr_charged: number; /** - * Credits returned for pages that did not succeed. Stays 0 until the batch reaches - * a final status, then settles in one movement. + * Credits returned for unsuccessful pages when the batch settles. */ refunded: number; /** - * 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. + * Credits held when the batch was accepted. */ reserved: number; } @@ -396,9 +385,8 @@ export namespace BatchRetrieveResponse { failed: number; /** - * 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. + * Accepted pages not yet attempted. Unused crawl capacity is excluded after + * completion. */ pending: number; @@ -409,12 +397,12 @@ export namespace BatchRetrieveResponse { } /** - * 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. + * Result download links; null until the batch finishes. Files are deleted 7 days + * after the batch finishes. */ export interface Results { /** - * When the download URLs expire. + * When these links expire (24 hours after this response). */ expires_at: string; @@ -465,7 +453,7 @@ export namespace BatchRetrieveResponse { */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -478,8 +466,8 @@ export namespace BatchRetrieveResponse { export interface BatchListResponse { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -494,7 +482,7 @@ export interface BatchListResponse { has_more?: boolean; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: BatchListResponse.KeyMetadata; @@ -510,18 +498,17 @@ export namespace BatchListResponse { */ export interface Data { /** - * Batch ID used to retrieve or cancel the job. + * Batch ID. */ id: string; /** - * The crawl controls as submitted, so the limits requested can be compared against - * what the crawl reached. + * Crawl settings as submitted. */ crawl: BatchAPI.CrawlControls | null; /** - * What this batch has done to your credit balance. + * Batch credit usage and settlement. */ credits: Data.Credits; @@ -538,12 +525,12 @@ export namespace BatchListResponse { format: 'markdown' | 'html'; /** - * What submission took in, and what it charged for. + * What the submission accepted. */ input: BatchAPI.Intake; /** - * How pages were selected. Matches `input.mode` on the submit request. + * `scrape` (URL list) or `crawl`. */ mode: 'scrape' | 'crawl'; @@ -559,8 +546,8 @@ export namespace BatchListResponse { progress: Data.Progress; /** - * 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. + * Result download links; null until the batch finishes. Files are deleted 7 days + * after the batch finishes. */ results: Data.Results | null; @@ -579,30 +566,26 @@ export namespace BatchListResponse { export namespace Data { /** - * What this batch has done to your credit balance. + * Batch credit usage and settlement. */ export interface Credits { /** - * `reserved` minus `refunded` plus `ocr_charged` — what the batch has cost so far. - * Equal to `reserved` until the batch settles. + * `reserved` minus `refunded` plus `ocr_charged`. */ net: number; /** - * Credits charged for PDF pages recovered by OCR (pdf.ocr=true), 1 per recovered - * page, on top of `reserved`. Stays 0 until the batch settles. + * OCR usage charged when the batch settles. */ ocr_charged: number; /** - * Credits returned for pages that did not succeed. Stays 0 until the batch reaches - * a final status, then settles in one movement. + * Credits returned for unsuccessful pages when the batch settles. */ refunded: number; /** - * 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. + * Credits held when the batch was accepted. */ reserved: number; } @@ -617,9 +600,8 @@ export namespace BatchListResponse { failed: number; /** - * 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. + * Accepted pages not yet attempted. Unused crawl capacity is excluded after + * completion. */ pending: number; @@ -630,12 +612,12 @@ export namespace BatchListResponse { } /** - * 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. + * Result download links; null until the batch finishes. Files are deleted 7 days + * after the batch finishes. */ export interface Results { /** - * When the download URLs expire. + * When these links expire (24 hours after this response). */ expires_at: string; @@ -683,11 +665,11 @@ export namespace BatchListResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -700,8 +682,8 @@ export namespace BatchListResponse { export interface BatchDeleteResponse { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -716,18 +698,18 @@ export interface BatchDeleteResponse { deleted?: boolean; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: BatchDeleteResponse.KeyMetadata; } export namespace BatchDeleteResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -745,8 +727,7 @@ export interface BatchCancelResponse { id: string; /** - * The crawl controls as submitted, so the limits requested can be compared against - * what the crawl reached. + * Crawl settings as submitted. */ crawl: CrawlControls | null; @@ -761,7 +742,7 @@ export interface BatchCancelResponse { format: 'markdown' | 'html'; /** - * What submission took in, and what it charged for. + * What the submission accepted. */ input: Intake; @@ -781,8 +762,8 @@ export interface BatchCancelResponse { progress: BatchCancelResponse.Progress; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -798,7 +779,7 @@ export interface BatchCancelResponse { tags: Array; /** - * There is no finish time yet — the batch is still winding down. + * Batch timestamps. */ timing: BatchCancelResponse.Timing; @@ -814,8 +795,7 @@ export namespace BatchCancelResponse { */ export interface Credits { /** - * Credits debited at submission. The unspent remainder is refunded once the batch - * settles — read `credits.refunded` from GET /batch/{batch_id} then. + * Credits held at submission; unused credits are refunded when the batch settles. */ reserved: number; } @@ -830,7 +810,7 @@ export namespace BatchCancelResponse { failed: number; /** - * Reserved pages that will now be skipped, and refunded when the batch settles. + * Pages that will be skipped. */ pending: number; @@ -841,7 +821,7 @@ export namespace BatchCancelResponse { } /** - * There is no finish time yet — the batch is still winding down. + * Batch timestamps. */ export interface Timing { /** @@ -860,7 +840,7 @@ export namespace BatchCancelResponse { */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -873,8 +853,8 @@ export namespace BatchCancelResponse { export interface BatchGetResultsResponse { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -889,7 +869,7 @@ export interface BatchGetResultsResponse { has_more?: boolean; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: BatchGetResultsResponse.KeyMetadata; @@ -905,9 +885,7 @@ export namespace BatchGetResultsResponse { */ export interface Ok { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: Ok.CacheMetadata; @@ -943,7 +921,7 @@ export namespace BatchGetResultsResponse { html?: string; /** - * Caller-supplied identifier echoed from submission. + * Your `itemId` from submission. */ itemId?: string; @@ -958,17 +936,14 @@ export namespace BatchGetResultsResponse { meta?: { [key: string]: unknown }; /** - * PDF pages of this document recovered by OCR (pdf.ocr=true). Each recovered page - * bills 1 credit on top of the page base credit; absent when no OCR ran. + * Number of PDF pages recovered by OCR. Omitted when OCR did not run. */ ocr_pages?: number; } export namespace Ok { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -1152,7 +1127,7 @@ export namespace BatchGetResultsResponse { url: string; /** - * Caller-supplied identifier echoed from submission. + * Your `itemId` from submission. */ itemId?: string; @@ -1163,11 +1138,11 @@ export namespace BatchGetResultsResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -1185,15 +1160,12 @@ export interface BatchSubmitResponse { id: string; /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: BatchSubmitResponse.CacheMetadata; /** - * The crawl controls as submitted, so the limits requested can be compared against - * what the crawl reached. + * Crawl settings as submitted. */ crawl: CrawlControls | null; @@ -1213,12 +1185,12 @@ export interface BatchSubmitResponse { format: 'markdown' | 'html'; /** - * What submission took in, and what it charged for. + * What the submission accepted. */ input: Intake; /** - * Rejected URLs, up to 100. These are not charged. + * Rejected URLs (first 100). */ invalid_urls: Array; @@ -1228,8 +1200,8 @@ export interface BatchSubmitResponse { mode: 'scrape' | 'crawl'; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -1249,17 +1221,14 @@ export interface BatchSubmitResponse { key_metadata?: BatchSubmitResponse.KeyMetadata; /** - * Signing secret for the completion webhook, returned only here and never again. - * Store it now; it is not repeated by GET /batch/{batch_id}. + * Secret for verifying `X-Context-Signature`. Only submit returns it, so store it. */ webhook_secret?: string; } export namespace BatchSubmitResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -1279,8 +1248,7 @@ export namespace BatchSubmitResponse { */ export interface Credits { /** - * Credits just debited from your balance. Whatever the batch does not spend is - * refunded when it settles. + * Credits held at submission. */ reserved: number; } @@ -1302,7 +1270,7 @@ export namespace BatchSubmitResponse { */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -1372,8 +1340,8 @@ export interface BatchSubmitParams { tags?: Array; /** - * Body param: Completion webhook settings. Cannot be combined with webhookUrl. - * Omitting retry preserves legacy delivery; retry: {} opts into durable retries. + * Body param: Where to send the batch's final-status event. Omit `retry` for one + * attempt; `{}` uses the default retry schedule. */ webhook?: BatchSubmitParams.Webhook; @@ -1384,15 +1352,15 @@ export interface BatchSubmitParams { webhookUrl?: string; /** - * Header param: Any string unique to this submission. Retries with the same key - * return the original batch. + * Header param: Unique key per submission. Retrying with the same key and body + * returns the original batch; a different body returns `409`. */ 'Idempotency-Key'?: string; } export namespace BatchSubmitParams { /** - * Scrape up to 25K URLs in one batch. + * Scrape a list of up to 25,000 URLs. */ export interface Scrape { /** @@ -1454,8 +1422,7 @@ export namespace BatchSubmitParams { */ export interface Options { /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). + * Fetch from this country (ISO 3166-1 alpha-2). */ country?: | 'ad' @@ -1670,8 +1637,7 @@ export namespace BatchSubmitParams { excludeSelectors?: Array | null; /** - * Also include each page's HTML in its result record, as an `html` field alongside - * the Markdown. + * Also return each page's HTML in `html`. */ includeHTML?: boolean; @@ -1686,15 +1652,13 @@ export namespace BatchSubmitParams { includeLinks?: boolean; /** - * Keep only the subtrees matching these CSS selectors. Filtered pages are always - * fetched fresh, ignoring `maxAgeMs`. + * Keep only elements matching these CSS selectors. Filtered pages ignore + * `maxAgeMs`. */ includeSelectors?: Array | null; /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. */ maxAgeMs?: number | null; @@ -1705,8 +1669,7 @@ export namespace BatchSubmitParams { pdf?: Options.Pdf; /** - * Wait briefly for CSS and transition animations to settle before extraction, on - * pages that render in a browser. + * Wait for CSS animations to finish before extracting, on browser-rendered pages. */ settleAnimations?: boolean; @@ -1739,16 +1702,12 @@ export namespace BatchSubmitParams { end?: number; /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. When false, no OCR runs. + * Read scanned PDF pages with OCR; preserve pages that already have text. */ ocr?: boolean; /** - * When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and - * a 400 PDF_SKIPPED is returned. + * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. */ shouldParse?: boolean; @@ -1807,8 +1766,7 @@ export namespace BatchSubmitParams { */ export interface Options { /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). + * Fetch from this country (ISO 3166-1 alpha-2). */ country?: | 'ad' @@ -2023,15 +1981,13 @@ export namespace BatchSubmitParams { excludeSelectors?: Array | null; /** - * Keep only the subtrees matching these CSS selectors. Filtered pages are always - * fetched fresh, ignoring `maxAgeMs`. + * Keep only elements matching these CSS selectors. Filtered pages ignore + * `maxAgeMs`. */ includeSelectors?: Array | null; /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. */ maxAgeMs?: number | null; @@ -2042,8 +1998,7 @@ export namespace BatchSubmitParams { pdf?: Options.Pdf; /** - * Wait briefly for CSS and transition animations to settle before extraction, on - * pages that render in a browser. + * Wait for CSS animations to finish before extracting, on browser-rendered pages. */ settleAnimations?: boolean; @@ -2071,16 +2026,12 @@ export namespace BatchSubmitParams { end?: number; /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. When false, no OCR runs. + * Read scanned PDF pages with OCR; preserve pages that already have text. */ ocr?: boolean; /** - * When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and - * a 400 PDF_SKIPPED is returned. + * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. */ shouldParse?: boolean; @@ -2223,8 +2174,7 @@ export namespace BatchSubmitParams { */ export interface Options { /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). + * Fetch from this country (ISO 3166-1 alpha-2). */ country?: | 'ad' @@ -2439,8 +2389,7 @@ export namespace BatchSubmitParams { excludeSelectors?: Array | null; /** - * Also include each page's HTML in its result record, as an `html` field alongside - * the Markdown. + * Also return each page's HTML in `html`. */ includeHTML?: boolean; @@ -2455,15 +2404,13 @@ export namespace BatchSubmitParams { includeLinks?: boolean; /** - * Keep only the subtrees matching these CSS selectors. Filtered pages are always - * fetched fresh, ignoring `maxAgeMs`. + * Keep only elements matching these CSS selectors. Filtered pages ignore + * `maxAgeMs`. */ includeSelectors?: Array | null; /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. */ maxAgeMs?: number | null; @@ -2474,8 +2421,7 @@ export namespace BatchSubmitParams { pdf?: Options.Pdf; /** - * Wait briefly for CSS and transition animations to settle before extraction, on - * pages that render in a browser. + * Wait for CSS animations to finish before extracting, on browser-rendered pages. */ settleAnimations?: boolean; @@ -2508,16 +2454,12 @@ export namespace BatchSubmitParams { end?: number; /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. When false, no OCR runs. + * Read scanned PDF pages with OCR; preserve pages that already have text. */ ocr?: boolean; /** - * When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and - * a 400 PDF_SKIPPED is returned. + * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. */ shouldParse?: boolean; @@ -2643,8 +2585,7 @@ export namespace BatchSubmitParams { */ export interface Options { /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). + * Fetch from this country (ISO 3166-1 alpha-2). */ country?: | 'ad' @@ -2859,15 +2800,13 @@ export namespace BatchSubmitParams { excludeSelectors?: Array | null; /** - * Keep only the subtrees matching these CSS selectors. Filtered pages are always - * fetched fresh, ignoring `maxAgeMs`. + * Keep only elements matching these CSS selectors. Filtered pages ignore + * `maxAgeMs`. */ includeSelectors?: Array | null; /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. */ maxAgeMs?: number | null; @@ -2878,8 +2817,7 @@ export namespace BatchSubmitParams { pdf?: Options.Pdf; /** - * Wait briefly for CSS and transition animations to settle before extraction, on - * pages that render in a browser. + * Wait for CSS animations to finish before extracting, on browser-rendered pages. */ settleAnimations?: boolean; @@ -2907,16 +2845,12 @@ export namespace BatchSubmitParams { end?: number; /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. When false, no OCR runs. + * Read scanned PDF pages with OCR; preserve pages that already have text. */ ocr?: boolean; /** - * When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and - * a 400 PDF_SKIPPED is returned. + * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. */ shouldParse?: boolean; @@ -2930,10 +2864,14 @@ export namespace BatchSubmitParams { } /** - * Completion webhook settings. Cannot be combined with webhookUrl. Omitting retry - * preserves legacy delivery; retry: {} opts into durable retries. + * Where to send the batch's final-status event. Omit `retry` for one attempt; `{}` + * uses the default retry schedule. */ export interface Webhook { + /** + * Public HTTP(S) URL that receives batch completion, failure, or cancellation + * events. + */ url: string; /** diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 28b9c457..34aba28d 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -6,11 +6,8 @@ import { RequestOptions } from '../internal/request-options'; export class Brand extends APIResource { /** - * Retrieve logos, backdrops, colors, industry, description, and more. Provide - * exactly one lookup identifier in the request body: a domain, company name, email - * address, stock ticker, transaction descriptor, or direct URL. Note: - * `by_direct_url` fetches brand data only from the provided URL — not from the - * entire internet. + * Retrieve logos, colors, company details, and social links using one lookup + * identifier. A direct URL limits extraction to that page. * * @example * ```ts @@ -25,7 +22,8 @@ export class Brand extends APIResource { } /** - * Search indexed brands by name or domain + * Find up to 10 brands by name or domain, ordered by popularity. Use the returned + * domain to retrieve a full brand profile. * * @example * ```ts @@ -44,9 +42,7 @@ export interface BrandRetrieveResponse { brand: BrandRetrieveResponse.Brand; /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: BrandRetrieveResponse.CacheMetadata; @@ -56,18 +52,18 @@ export interface BrandRetrieveResponse { code: number; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Status of the response, e.g., 'ok' + * Always `ok` on success. */ status: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: BrandRetrieveResponse.KeyMetadata; @@ -146,7 +142,7 @@ export namespace BrandRetrieveResponse { phone?: string; /** - * Language to force for the retrieved brand data. + * Language, e.g. `english`. */ primary_language?: | 'afrikaans' @@ -754,7 +750,7 @@ export namespace BrandRetrieveResponse { type?: 'icon' | 'logo'; /** - * CDN hosted url of the logo (ready for display) + * Hosted logo URL. */ url?: string; } @@ -854,9 +850,7 @@ export namespace BrandRetrieveResponse { } /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -872,11 +866,11 @@ export namespace BrandRetrieveResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -889,8 +883,8 @@ export namespace BrandRetrieveResponse { export interface BrandSearchResponse { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -901,7 +895,7 @@ export interface BrandSearchResponse { results: Array; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: BrandSearchResponse.KeyMetadata; } @@ -926,11 +920,11 @@ export namespace BrandSearchResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -1085,10 +1079,8 @@ export declare namespace BrandRetrieveParams { | null; /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. + * Maximum age of cached brand data in ms. Defaults to 3 months; clamped to 0–1 + * year. `0` refreshes. */ maxAgeMs?: number; @@ -1100,35 +1092,29 @@ export declare namespace BrandRetrieveParams { maxSpeed?: boolean; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveByDomainRequest.TimeoutOpts; } export namespace BrandRetrieveByDomainRequest { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -1275,10 +1261,8 @@ export declare namespace BrandRetrieveParams { | null; /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. + * Maximum age of cached brand data in ms. Defaults to 3 months; clamped to 0–1 + * year. `0` refreshes. */ maxAgeMs?: number; @@ -1290,35 +1274,29 @@ export declare namespace BrandRetrieveParams { maxSpeed?: boolean; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveByNameRequest.TimeoutOpts; } export namespace BrandRetrieveByNameRequest { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -1459,10 +1437,8 @@ export declare namespace BrandRetrieveParams { | null; /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. + * Maximum age of cached brand data in ms. Defaults to 3 months; clamped to 0–1 + * year. `0` refreshes. */ maxAgeMs?: number; @@ -1474,35 +1450,29 @@ export declare namespace BrandRetrieveParams { maxSpeed?: boolean; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveByEmailRequest.TimeoutOpts; } export namespace BrandRetrieveByEmailRequest { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -1643,10 +1613,8 @@ export declare namespace BrandRetrieveParams { | null; /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. + * Maximum age of cached brand data in ms. Defaults to 3 months; clamped to 0–1 + * year. `0` refreshes. */ maxAgeMs?: number; @@ -1658,7 +1626,7 @@ export declare namespace BrandRetrieveParams { maxSpeed?: boolean; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; @@ -1668,30 +1636,24 @@ export declare namespace BrandRetrieveParams { ticker_exchange?: string; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveByTickerRequest.TimeoutOpts; } export namespace BrandRetrieveByTickerRequest { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -1711,35 +1673,29 @@ export declare namespace BrandRetrieveParams { type: 'by_direct_url'; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveByDirectURLRequest.TimeoutOpts; } export namespace BrandRetrieveByDirectURLRequest { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -1915,35 +1871,29 @@ export declare namespace BrandRetrieveParams { phone?: string | number; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveFromTransactionRequest.TimeoutOpts; } export namespace BrandRetrieveFromTransactionRequest { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -1970,8 +1920,7 @@ export interface BrandSearchParams { queryBy?: Array<'name' | 'domain'>; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; diff --git a/src/resources/feedback.ts b/src/resources/feedback.ts index 37a82437..5e1ffdd2 100644 --- a/src/resources/feedback.ts +++ b/src/resources/feedback.ts @@ -5,12 +5,12 @@ import { APIPromise } from '../core/api-promise'; import { RequestOptions } from '../internal/request-options'; /** - * Report bugs, docs mismatches, and friction with any Context.dev API. Submissions cost no credits and use a separate rate limit. + * Report API issues and documentation mismatches. */ export class Feedback extends APIResource { /** - * Report a problem with a Context.dev API call, docs page, SDK, or CLI. Include - * request_id, url, or both. + * Report an API issue or documentation mismatch, including request IDs when + * available. * * @example * ```ts @@ -40,24 +40,24 @@ export interface FeedbackSubmitResponse { feedback_id: string; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: FeedbackSubmitResponse.KeyMetadata; } export namespace FeedbackSubmitResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -86,7 +86,7 @@ export interface FeedbackSubmitParams { request_id?: string; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; diff --git a/src/resources/industry.ts b/src/resources/industry.ts index 3beac749..a82ba60d 100644 --- a/src/resources/industry.ts +++ b/src/resources/industry.ts @@ -6,7 +6,7 @@ import { RequestOptions } from '../internal/request-options'; export class Industry extends APIResource { /** - * Classify any brand into 2022 NAICS industry codes from its domain or name. + * Classify a company into NAICS industry codes. */ retrieveNaics( query: IndustryRetrieveNaicsParams, @@ -16,9 +16,7 @@ export class Industry extends APIResource { } /** - * Classify any brand into Standard Industrial Classification (SIC) codes from its - * domain or name. Choose between the original SIC system (`original_sic`) or the - * latest SIC list maintained by the SEC (`latest_sec`). + * Classify a company into SIC industry codes. */ retrieveSic( query: IndustryRetrieveSicParams, @@ -30,8 +28,8 @@ export class Industry extends APIResource { export interface IndustryRetrieveNaicsResponse { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -46,7 +44,7 @@ export interface IndustryRetrieveNaicsResponse { domain?: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: IndustryRetrieveNaicsResponse.KeyMetadata; @@ -57,7 +55,7 @@ export interface IndustryRetrieveNaicsResponse { partial?: boolean; /** - * Status of the response, e.g., 'ok' + * Always `ok` on success. */ status?: string; @@ -86,11 +84,11 @@ export namespace IndustryRetrieveNaicsResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -103,8 +101,8 @@ export namespace IndustryRetrieveNaicsResponse { export interface IndustryRetrieveSicResponse { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -126,7 +124,7 @@ export interface IndustryRetrieveSicResponse { domain?: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: IndustryRetrieveSicResponse.KeyMetadata; @@ -137,7 +135,7 @@ export interface IndustryRetrieveSicResponse { partial?: boolean; /** - * Status of the response, e.g., 'ok' + * Always `ok` on success. */ status?: string; @@ -184,11 +182,11 @@ export namespace IndustryRetrieveSicResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -219,45 +217,35 @@ export interface IndustryRetrieveNaicsParams { minResults?: number; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: IndustryRetrieveNaicsParams.TimeoutOpts; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace IndustryRetrieveNaicsParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -282,52 +270,40 @@ export interface IndustryRetrieveSicParams { minResults?: number; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: IndustryRetrieveSicParams.TimeoutOpts; /** - * Which SIC dataset to classify against. `original_sic` uses the 1987 Standard - * Industrial Classification system; `latest_sec` uses the current SIC list as - * published by the SEC. Defaults to `original_sic`. + * SIC dataset: `original_sic` (1987) or `latest_sec` (current SEC list). */ type?: 'original_sic' | 'latest_sec'; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace IndustryRetrieveSicParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } diff --git a/src/resources/logs.ts b/src/resources/logs.ts index 74f00c5d..14f71a1c 100644 --- a/src/resources/logs.ts +++ b/src/resources/logs.ts @@ -6,19 +6,19 @@ import { RequestOptions } from '../internal/request-options'; import { path } from '../internal/utils/path'; /** - * Read your organization's API request logs to debug failed calls. These endpoints cost no credits and use a separate rate limit. + * Read your organization's API request logs. */ export class Logs extends APIResource { /** - * Get one logged API call, including its request input and response body. + * Retrieve a request’s metadata, retained input, and response. */ retrieve(requestID: string, options?: RequestOptions): APIPromise { return this._client.get(path`/logs/${requestID}`, options); } /** - * List your organization's API requests, newest first. Defaults to the last 24 - * hours. + * List your organization’s request logs with filters and pagination. Logs also + * include batch settlements and monitor runs. */ list(query: LogListParams | null | undefined = {}, options?: RequestOptions): APIPromise { return this._client.get('/logs', { query, ...options }); @@ -29,13 +29,13 @@ export interface LogRetrieveResponse { data: LogRetrieveResponse.Data; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: LogRetrieveResponse.KeyMetadata; } @@ -68,7 +68,8 @@ export namespace LogRetrieveResponse { latency_ms: number; /** - * HTTP method. + * HTTP method, or `MONITOR` / `BATCH` for monitor-run and batch-settlement + * entries. */ method: string; @@ -107,11 +108,6 @@ export namespace LogRetrieveResponse { */ zdr: boolean; - /** - * Credit usage, included whenever a valid API key is provided. - */ - key_metadata?: Data.KeyMetadata; - /** * The retained JSON response with credentials redacted, or null when unavailable. */ @@ -133,29 +129,14 @@ export namespace LogRetrieveResponse { */ body?: unknown; } - - /** - * Credit usage, included whenever a valid API key is provided. - */ - export interface KeyMetadata { - /** - * Credits used by this request. - */ - credits_consumed: number; - - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -188,13 +169,13 @@ export interface LogListResponse { page: number; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: LogListResponse.KeyMetadata; } @@ -222,7 +203,8 @@ export namespace LogListResponse { latency_ms: number; /** - * HTTP method. + * HTTP method, or `MONITOR` / `BATCH` for monitor-run and batch-settlement + * entries. */ method: string; @@ -258,11 +240,11 @@ export namespace LogListResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index b54dd5bb..11bd5eb5 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -8,13 +8,12 @@ import { RequestOptions } from '../internal/request-options'; import { path } from '../internal/utils/path'; /** - * Monitor pages, sitemaps, and extracted website data for exact or semantic changes. Webhook payloads are documented by the MonitorsChangeDetectedWebhookPayload and MonitorsRunCompletedWebhookPayload schemas. + * Watch websites for exact or meaningful changes. */ export class Monitors extends APIResource { /** - * Creates a monitor. The request body is a union of the supported target/change - * detection combinations. The monitor runs immediately after creation to create - * its initial baseline. + * Watch a page, URL inventory, or extracted website data on a schedule. A run + * starts immediately to capture the baseline. * * @example * ```ts @@ -37,7 +36,7 @@ export class Monitors extends APIResource { } /** - * Get a monitor + * Retrieve a monitor’s configuration and current state. * * @example * ```ts @@ -49,9 +48,8 @@ export class Monitors extends APIResource { } /** - * Updates a monitor. If `target` or `change_detection` changes, the monitor - * creates a new baseline. Unsupported target/change detection combinations are - * rejected. + * Update a monitor. Changing its target or change detection replaces the baseline + * and queues a new baseline run. * * @example * ```ts @@ -76,9 +74,7 @@ export class Monitors extends APIResource { } /** - * Lists monitors for the authenticated organization. Supports free-text search - * (`q` over `search_by` fields, `prefix` or `exact` via `search_type`) plus - * status/type/tag filters. Results are paginated via the opaque `cursor`. + * List your monitors with optional search and filters. * * @example * ```ts @@ -93,7 +89,7 @@ export class Monitors extends APIResource { } /** - * Delete a monitor + * Delete a monitor and stop future runs and webhook retries. * * @example * ```ts @@ -105,8 +101,8 @@ export class Monitors extends APIResource { } /** - * Returns credits charged per monitor over an optional [since, until] window, - * newest spenders first. + * Return usage per monitor, highest first, for up to the 10,000 most recent runs + * in the requested window. * * @example * ```ts @@ -121,7 +117,7 @@ export class Monitors extends APIResource { } /** - * Returns how many monitors the account has and the maximum it allows. + * Retrieve your organization’s monitor allowance and usage. * * @example * ```ts @@ -133,7 +129,7 @@ export class Monitors extends APIResource { } /** - * Returns an account-wide feed of detected changes across monitors. + * List full change records across your monitors, newest first. * * @example * ```ts @@ -148,7 +144,7 @@ export class Monitors extends APIResource { } /** - * Returns an account-wide feed of monitor runs across all monitors. + * List runs across your monitors, newest first. * * @example * ```ts @@ -163,7 +159,7 @@ export class Monitors extends APIResource { } /** - * List changes for a monitor + * List full change records for a monitor, newest first. * * @example * ```ts @@ -181,7 +177,7 @@ export class Monitors extends APIResource { } /** - * List monitor runs + * List a monitor’s runs, newest first. * * @example * ```ts @@ -197,7 +193,7 @@ export class Monitors extends APIResource { } /** - * Get a change + * Retrieve a detected change, including its diff and available evidence. * * @example * ```ts @@ -211,8 +207,7 @@ export class Monitors extends APIResource { } /** - * Fetches one run for a monitor, including lifecycle status, timing, credits - * charged, and any detected change. + * Retrieve the status, timing, and results of one monitor run. * * @example * ```ts @@ -232,9 +227,8 @@ export class Monitors extends APIResource { } /** - * Generates a new signing secret for the monitor's webhook and returns the updated - * monitor (including the new `webhook.secret`). The previous secret stops signing - * deliveries immediately, so update your endpoint before rotating. + * Generate and return a new signing secret. It takes effect immediately for all + * subsequent delivery attempts. * * @example * ```ts @@ -251,8 +245,7 @@ export class Monitors extends APIResource { } /** - * Triggers an immediate run of the monitor outside its normal schedule. The run is - * queued and processed asynchronously. + * Queue a run without changing the regular schedule. Paused monitors return 409. * * @example * ```ts @@ -287,9 +280,7 @@ export interface WebhookDelivery { http_status: number | null; /** - * Delivery outcome. delivered means any 2xx response; rejected means a non-2xx - * response; failed means no HTTP response was received; skipped_unsafe_url means - * the URL failed the public-endpoint safety check. + * Outcome of the delivery attempt. Any 2xx response counts as delivered. */ status: 'delivered' | 'rejected' | 'failed' | 'skipped_unsafe_url'; @@ -307,15 +298,12 @@ export namespace WebhookDelivery { } } -/** - * A newly created monitor plus `initial_run_id`, the id of the baseline run queued - * at creation. - */ export interface MonitorCreateResponse { id: string; /** - * Discriminated union describing how changes are detected. + * How changes are judged. Defaults to `semantic` for extract targets and page + * targets with `instructions`, otherwise `exact`. */ change_detection: | MonitorCreateResponse.MonitorsExactChangeDetection @@ -324,38 +312,32 @@ export interface MonitorCreateResponse { created_at: string; /** - * The baseline run queued by this create call, or null if it could not be queued - * immediately (in which case the baseline runs on the next scheduled tick). Poll - * GET /monitors/{monitor_id}/runs/{run_id}. + * ID of the baseline run queued at creation; null if it will start on the next + * scheduled tick. */ initial_run_id: string | null; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; name: string; /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ - schedule: MonitorCreateResponse.Schedule; + request_id: string; /** - * Monitor lifecycle status. `failed` means the most recent run failed (see the - * monitor's `last_error`); failed monitors keep running on schedule and flip back - * to `active` on the next successful run. Monitors are auto-`paused` after - * repeated consecutive failures or insufficient-credit skips; resume by PATCHing - * status to `active`. + * Current state. Failed monitors keep running; paused monitors must be resumed + * with `status: "active"`. */ status: 'active' | 'paused' | 'failed'; /** - * Discriminated union describing what the monitor watches. + * What to watch: a page, a sitemap, or data extracted from a site. */ target: | MonitorCreateResponse.MonitorsPageTarget @@ -365,10 +347,8 @@ export interface MonitorCreateResponse { updated_at: string; /** - * Current baseline: the last observed value the monitor compares new snapshots - * against. Its shape follows `target.type` (page/sitemap/extract). Only populated - * on GET /monitors/{monitor_id}; null until the first baseline run completes (and - * after a target or change_detection update, which resets the baseline). + * Comparison baseline, included on Retrieve. Null until capture completes or after + * target changes. */ baseline?: | MonitorCreateResponse.MonitorsPageBaseline @@ -376,6 +356,11 @@ export interface MonitorCreateResponse { | MonitorCreateResponse.MonitorsExtractBaseline | null; + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorCreateResponse.KeyMetadata; + last_change_at?: string | null; /** @@ -386,16 +371,25 @@ export interface MonitorCreateResponse { last_run_at?: string | null; /** - * When the next scheduled run is due. + * When the next scheduled run is due; null while paused. */ next_run_at?: string | null; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + schedule?: MonitorCreateResponse.Schedule; + + /** + * Labels for filtering monitors, their changes, and their usage. */ tags?: Array; + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ webhook?: MonitorCreateResponse.Webhook | null; /** @@ -412,37 +406,26 @@ export namespace MonitorCreateResponse { * sitemap targets, this means URL additions and removals. */ export interface MonitorsExactChangeDetection { + /** + * Use `exact` to compare visible text or sitemap URLs. + */ type: 'exact'; } /** - * Detect meaning-level changes to page content, ignoring cosmetic or - * instruction-irrelevant differences. Which changes are meaningful is judged - * against the page or extract target's `instructions` (and an extract target's - * `schema`, when provided). + * Detect meaningful content changes using the target’s instructions and optional + * schema. */ export interface MonitorsSemanticChangeDetection { + /** + * Use `semantic` to judge changes against the target instructions. + */ type: 'semantic'; - confidence_threshold?: number; - } - - /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. - */ - export interface Schedule { /** - * Number of units between runs. The resulting interval (frequency × unit) must be - * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; - * maximum 365 when unit is days). + * Minimum confidence required to report a meaningful change, from 0 to 1. */ - frequency: number; - - type: 'interval'; - - unit: 'minutes' | 'hours' | 'days'; + confidence_threshold?: number; } /** @@ -450,24 +433,24 @@ export namespace MonitorCreateResponse { * detection judges confirmed stable diffs against `instructions`. */ export interface MonitorsPageTarget { + /** + * Use `page` to watch one web page. + */ type: 'page'; + /** + * Public HTTP(S) page URL to monitor. + */ url: string; /** - * CSS selectors for HTML regions to remove before text extraction. Applied after - * include_selectors; exclusion takes precedence when an element matches both. Omit - * or pass an empty array to apply no explicit exclusions. Changing these selectors - * creates a new baseline. + * Remove matching regions after inclusions. Changes create a new baseline. */ exclude_selectors?: Array; /** - * CSS selectors defining the HTML regions to monitor. Matching subtrees are - * combined in document order before text extraction, instead of automatic - * main-content selection. Omit or pass an empty array to use automatic - * main-content extraction. If the filtered page has no usable text, the run fails - * without replacing the baseline. Changing these selectors creates a new baseline. + * Monitor these CSS-selected regions. Empty or omitted uses main content. Changes + * create a new baseline. */ include_selectors?: Array; @@ -484,13 +467,12 @@ export namespace MonitorCreateResponse { } /** - * Watch a sitemap for URL additions and removals. Crawled URLs are normalized - * (lowercased host, no trailing slash/fragment) and scoped to the monitored site - * and its subdomains before comparison. On a detected difference the sitemap is - * re-fetched within the same run and only URLs both observations agree on are - * reported, suppressing transient crawl flaps. + * Watch a site’s URL inventory for confirmed additions and removals. */ export interface MonitorsSitemapTarget { + /** + * Use `sitemap` to watch a site for added or removed URLs. + */ type: 'sitemap'; /** @@ -515,11 +497,8 @@ export namespace MonitorCreateResponse { } /** - * Watch the monitor-relevant pages of a site for meaningful changes. A crawl - * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to - * track; each run re-checks exactly those pages, and confirmed content changes are - * judged for relevance against the monitor's `instructions` (and `schema`, when - * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + * Track relevant pages selected by `schema` and `instructions`; refresh the page + * set periodically. */ export interface MonitorsExtractTarget { /** @@ -528,6 +507,9 @@ export namespace MonitorCreateResponse { */ instructions: string; + /** + * Use `extract` to watch structured data across selected pages. + */ type: 'extract'; /** @@ -535,6 +517,9 @@ export namespace MonitorCreateResponse { */ url: string; + /** + * Allow page discovery on subdomains of the target site. + */ follow_subdomains?: boolean; /** @@ -548,14 +533,8 @@ export namespace MonitorCreateResponse { max_pages?: number; /** - * JSON Schema describing the data you care about. It is used three ways: it guides - * which pages are selected for tracking, it gives the change judge extra context - * on which changes matter (alongside `instructions`), and it defines the shape of - * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most - * about once a day). It is not a response format for changes: change events and - * webhook payloads always contain diffs, summaries, and evidence excerpts — never - * data in this schema's shape. If omitted, a default summary + key-points schema - * is used. + * JSON Schema for page selection and the baseline snapshot. Changes return diffs + * and evidence. */ schema?: { [key: string]: unknown }; } @@ -607,10 +586,8 @@ export namespace MonitorCreateResponse { captured_at: string; /** - * The extracted structured data, matching the monitor's extraction schema (same - * shape as the /web/extract endpoint's `data`). Refreshed when the monitor - * re-discovers its page set (at most about once a day); `null` when no extraction - * has been captured yet. + * Latest structured snapshot matching the extraction schema, refreshed at most + * daily; `null` before capture. */ data: unknown; @@ -620,6 +597,21 @@ export namespace MonitorCreateResponse { urls_analyzed: Array; } + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } + /** * Error from the most recent failed run; null when the last run succeeded. */ @@ -629,18 +621,43 @@ export namespace MonitorCreateResponse { message: string; } + /** + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + export interface Schedule { + /** + * Number of units between runs. The resulting interval (frequency × unit) must be + * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; + * maximum 365 when unit is days). + */ + frequency: number; + + /** + * Use `interval` to run on a repeating schedule. + */ + type: 'interval'; + + /** + * Time unit used with `frequency` to set the run interval. + */ + unit: 'minutes' | 'hours' | 'days'; + } + + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ export interface Webhook { /** - * Webhook URL events are delivered to. Slack incoming webhook URLs are - * automatically formatted as Slack messages. + * Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted + * messages. */ url: string; /** - * Events delivered to this endpoint. `change.detected` fires only when a run - * detects a change; `run.completed` fires on every completed run — including runs - * that detected no change — and embeds the change when one was detected. Defaults - * to `["change.detected"]` when omitted. + * Events to deliver. Defaults to `change.detected`; `run.completed` also includes + * unchanged runs. */ events?: Array<'change.detected' | 'run.completed'>; @@ -650,12 +667,8 @@ export namespace MonitorCreateResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Omitted unless the API key - * has monitors:write permission or full access. Each delivery includes an - * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over - * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time - * compare and reject stale timestamps to prevent replay. Generated by the API; - * cannot be set by clients. + * API-generated signing secret. Visible only with full access or `monitors:write` + * permission. */ secret?: string; } @@ -687,15 +700,12 @@ export namespace MonitorCreateResponse { } } -/** - * A web monitor. `mode` is the constant `web`; behavior is described by `target` - * (page/sitemap/extract) and `change_detection` (exact/semantic). - */ export interface MonitorRetrieveResponse { id: string; /** - * Discriminated union describing how changes are detected. + * How changes are judged. Defaults to `semantic` for extract targets and page + * targets with `instructions`, otherwise `exact`. */ change_detection: | MonitorRetrieveResponse.MonitorsExactChangeDetection @@ -704,31 +714,26 @@ export interface MonitorRetrieveResponse { created_at: string; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; name: string; /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ - schedule: MonitorRetrieveResponse.Schedule; + request_id: string; /** - * Monitor lifecycle status. `failed` means the most recent run failed (see the - * monitor's `last_error`); failed monitors keep running on schedule and flip back - * to `active` on the next successful run. Monitors are auto-`paused` after - * repeated consecutive failures or insufficient-credit skips; resume by PATCHing - * status to `active`. + * Current state. Failed monitors keep running; paused monitors must be resumed + * with `status: "active"`. */ status: 'active' | 'paused' | 'failed'; /** - * Discriminated union describing what the monitor watches. + * What to watch: a page, a sitemap, or data extracted from a site. */ target: | MonitorRetrieveResponse.MonitorsPageTarget @@ -738,10 +743,8 @@ export interface MonitorRetrieveResponse { updated_at: string; /** - * Current baseline: the last observed value the monitor compares new snapshots - * against. Its shape follows `target.type` (page/sitemap/extract). Only populated - * on GET /monitors/{monitor_id}; null until the first baseline run completes (and - * after a target or change_detection update, which resets the baseline). + * Comparison baseline, included on Retrieve. Null until capture completes or after + * target changes. */ baseline?: | MonitorRetrieveResponse.MonitorsPageBaseline @@ -749,6 +752,11 @@ export interface MonitorRetrieveResponse { | MonitorRetrieveResponse.MonitorsExtractBaseline | null; + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorRetrieveResponse.KeyMetadata; + last_change_at?: string | null; /** @@ -759,16 +767,25 @@ export interface MonitorRetrieveResponse { last_run_at?: string | null; /** - * When the next scheduled run is due. + * When the next scheduled run is due; null while paused. */ next_run_at?: string | null; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + schedule?: MonitorRetrieveResponse.Schedule; + + /** + * Labels for filtering monitors, their changes, and their usage. */ tags?: Array; + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ webhook?: MonitorRetrieveResponse.Webhook | null; /** @@ -785,37 +802,26 @@ export namespace MonitorRetrieveResponse { * sitemap targets, this means URL additions and removals. */ export interface MonitorsExactChangeDetection { + /** + * Use `exact` to compare visible text or sitemap URLs. + */ type: 'exact'; } /** - * Detect meaning-level changes to page content, ignoring cosmetic or - * instruction-irrelevant differences. Which changes are meaningful is judged - * against the page or extract target's `instructions` (and an extract target's - * `schema`, when provided). + * Detect meaningful content changes using the target’s instructions and optional + * schema. */ export interface MonitorsSemanticChangeDetection { + /** + * Use `semantic` to judge changes against the target instructions. + */ type: 'semantic'; - confidence_threshold?: number; - } - - /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. - */ - export interface Schedule { /** - * Number of units between runs. The resulting interval (frequency × unit) must be - * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; - * maximum 365 when unit is days). + * Minimum confidence required to report a meaningful change, from 0 to 1. */ - frequency: number; - - type: 'interval'; - - unit: 'minutes' | 'hours' | 'days'; + confidence_threshold?: number; } /** @@ -823,24 +829,24 @@ export namespace MonitorRetrieveResponse { * detection judges confirmed stable diffs against `instructions`. */ export interface MonitorsPageTarget { + /** + * Use `page` to watch one web page. + */ type: 'page'; + /** + * Public HTTP(S) page URL to monitor. + */ url: string; /** - * CSS selectors for HTML regions to remove before text extraction. Applied after - * include_selectors; exclusion takes precedence when an element matches both. Omit - * or pass an empty array to apply no explicit exclusions. Changing these selectors - * creates a new baseline. + * Remove matching regions after inclusions. Changes create a new baseline. */ exclude_selectors?: Array; /** - * CSS selectors defining the HTML regions to monitor. Matching subtrees are - * combined in document order before text extraction, instead of automatic - * main-content selection. Omit or pass an empty array to use automatic - * main-content extraction. If the filtered page has no usable text, the run fails - * without replacing the baseline. Changing these selectors creates a new baseline. + * Monitor these CSS-selected regions. Empty or omitted uses main content. Changes + * create a new baseline. */ include_selectors?: Array; @@ -857,13 +863,12 @@ export namespace MonitorRetrieveResponse { } /** - * Watch a sitemap for URL additions and removals. Crawled URLs are normalized - * (lowercased host, no trailing slash/fragment) and scoped to the monitored site - * and its subdomains before comparison. On a detected difference the sitemap is - * re-fetched within the same run and only URLs both observations agree on are - * reported, suppressing transient crawl flaps. + * Watch a site’s URL inventory for confirmed additions and removals. */ export interface MonitorsSitemapTarget { + /** + * Use `sitemap` to watch a site for added or removed URLs. + */ type: 'sitemap'; /** @@ -888,11 +893,8 @@ export namespace MonitorRetrieveResponse { } /** - * Watch the monitor-relevant pages of a site for meaningful changes. A crawl - * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to - * track; each run re-checks exactly those pages, and confirmed content changes are - * judged for relevance against the monitor's `instructions` (and `schema`, when - * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + * Track relevant pages selected by `schema` and `instructions`; refresh the page + * set periodically. */ export interface MonitorsExtractTarget { /** @@ -901,6 +903,9 @@ export namespace MonitorRetrieveResponse { */ instructions: string; + /** + * Use `extract` to watch structured data across selected pages. + */ type: 'extract'; /** @@ -908,6 +913,9 @@ export namespace MonitorRetrieveResponse { */ url: string; + /** + * Allow page discovery on subdomains of the target site. + */ follow_subdomains?: boolean; /** @@ -921,14 +929,8 @@ export namespace MonitorRetrieveResponse { max_pages?: number; /** - * JSON Schema describing the data you care about. It is used three ways: it guides - * which pages are selected for tracking, it gives the change judge extra context - * on which changes matter (alongside `instructions`), and it defines the shape of - * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most - * about once a day). It is not a response format for changes: change events and - * webhook payloads always contain diffs, summaries, and evidence excerpts — never - * data in this schema's shape. If omitted, a default summary + key-points schema - * is used. + * JSON Schema for page selection and the baseline snapshot. Changes return diffs + * and evidence. */ schema?: { [key: string]: unknown }; } @@ -980,10 +982,8 @@ export namespace MonitorRetrieveResponse { captured_at: string; /** - * The extracted structured data, matching the monitor's extraction schema (same - * shape as the /web/extract endpoint's `data`). Refreshed when the monitor - * re-discovers its page set (at most about once a day); `null` when no extraction - * has been captured yet. + * Latest structured snapshot matching the extraction schema, refreshed at most + * daily; `null` before capture. */ data: unknown; @@ -993,6 +993,21 @@ export namespace MonitorRetrieveResponse { urls_analyzed: Array; } + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } + /** * Error from the most recent failed run; null when the last run succeeded. */ @@ -1002,18 +1017,43 @@ export namespace MonitorRetrieveResponse { message: string; } + /** + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + export interface Schedule { + /** + * Number of units between runs. The resulting interval (frequency × unit) must be + * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; + * maximum 365 when unit is days). + */ + frequency: number; + + /** + * Use `interval` to run on a repeating schedule. + */ + type: 'interval'; + + /** + * Time unit used with `frequency` to set the run interval. + */ + unit: 'minutes' | 'hours' | 'days'; + } + + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ export interface Webhook { /** - * Webhook URL events are delivered to. Slack incoming webhook URLs are - * automatically formatted as Slack messages. + * Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted + * messages. */ url: string; /** - * Events delivered to this endpoint. `change.detected` fires only when a run - * detects a change; `run.completed` fires on every completed run — including runs - * that detected no change — and embeds the change when one was detected. Defaults - * to `["change.detected"]` when omitted. + * Events to deliver. Defaults to `change.detected`; `run.completed` also includes + * unchanged runs. */ events?: Array<'change.detected' | 'run.completed'>; @@ -1023,12 +1063,8 @@ export namespace MonitorRetrieveResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Omitted unless the API key - * has monitors:write permission or full access. Each delivery includes an - * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over - * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time - * compare and reject stale timestamps to prevent replay. Generated by the API; - * cannot be set by clients. + * API-generated signing secret. Visible only with full access or `monitors:write` + * permission. */ secret?: string; } @@ -1060,15 +1096,12 @@ export namespace MonitorRetrieveResponse { } } -/** - * A web monitor. `mode` is the constant `web`; behavior is described by `target` - * (page/sitemap/extract) and `change_detection` (exact/semantic). - */ export interface MonitorUpdateResponse { id: string; /** - * Discriminated union describing how changes are detected. + * How changes are judged. Defaults to `semantic` for extract targets and page + * targets with `instructions`, otherwise `exact`. */ change_detection: | MonitorUpdateResponse.MonitorsExactChangeDetection @@ -1077,31 +1110,26 @@ export interface MonitorUpdateResponse { created_at: string; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; name: string; /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ - schedule: MonitorUpdateResponse.Schedule; + request_id: string; /** - * Monitor lifecycle status. `failed` means the most recent run failed (see the - * monitor's `last_error`); failed monitors keep running on schedule and flip back - * to `active` on the next successful run. Monitors are auto-`paused` after - * repeated consecutive failures or insufficient-credit skips; resume by PATCHing - * status to `active`. + * Current state. Failed monitors keep running; paused monitors must be resumed + * with `status: "active"`. */ status: 'active' | 'paused' | 'failed'; /** - * Discriminated union describing what the monitor watches. + * What to watch: a page, a sitemap, or data extracted from a site. */ target: | MonitorUpdateResponse.MonitorsPageTarget @@ -1111,10 +1139,8 @@ export interface MonitorUpdateResponse { updated_at: string; /** - * Current baseline: the last observed value the monitor compares new snapshots - * against. Its shape follows `target.type` (page/sitemap/extract). Only populated - * on GET /monitors/{monitor_id}; null until the first baseline run completes (and - * after a target or change_detection update, which resets the baseline). + * Comparison baseline, included on Retrieve. Null until capture completes or after + * target changes. */ baseline?: | MonitorUpdateResponse.MonitorsPageBaseline @@ -1122,6 +1148,11 @@ export interface MonitorUpdateResponse { | MonitorUpdateResponse.MonitorsExtractBaseline | null; + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorUpdateResponse.KeyMetadata; + last_change_at?: string | null; /** @@ -1132,16 +1163,25 @@ export interface MonitorUpdateResponse { last_run_at?: string | null; /** - * When the next scheduled run is due. + * When the next scheduled run is due; null while paused. */ next_run_at?: string | null; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + schedule?: MonitorUpdateResponse.Schedule; + + /** + * Labels for filtering monitors, their changes, and their usage. */ tags?: Array; + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ webhook?: MonitorUpdateResponse.Webhook | null; /** @@ -1158,37 +1198,26 @@ export namespace MonitorUpdateResponse { * sitemap targets, this means URL additions and removals. */ export interface MonitorsExactChangeDetection { + /** + * Use `exact` to compare visible text or sitemap URLs. + */ type: 'exact'; } /** - * Detect meaning-level changes to page content, ignoring cosmetic or - * instruction-irrelevant differences. Which changes are meaningful is judged - * against the page or extract target's `instructions` (and an extract target's - * `schema`, when provided). + * Detect meaningful content changes using the target’s instructions and optional + * schema. */ export interface MonitorsSemanticChangeDetection { + /** + * Use `semantic` to judge changes against the target instructions. + */ type: 'semantic'; - confidence_threshold?: number; - } - - /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. - */ - export interface Schedule { /** - * Number of units between runs. The resulting interval (frequency × unit) must be - * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; - * maximum 365 when unit is days). + * Minimum confidence required to report a meaningful change, from 0 to 1. */ - frequency: number; - - type: 'interval'; - - unit: 'minutes' | 'hours' | 'days'; + confidence_threshold?: number; } /** @@ -1196,24 +1225,24 @@ export namespace MonitorUpdateResponse { * detection judges confirmed stable diffs against `instructions`. */ export interface MonitorsPageTarget { + /** + * Use `page` to watch one web page. + */ type: 'page'; + /** + * Public HTTP(S) page URL to monitor. + */ url: string; /** - * CSS selectors for HTML regions to remove before text extraction. Applied after - * include_selectors; exclusion takes precedence when an element matches both. Omit - * or pass an empty array to apply no explicit exclusions. Changing these selectors - * creates a new baseline. + * Remove matching regions after inclusions. Changes create a new baseline. */ exclude_selectors?: Array; /** - * CSS selectors defining the HTML regions to monitor. Matching subtrees are - * combined in document order before text extraction, instead of automatic - * main-content selection. Omit or pass an empty array to use automatic - * main-content extraction. If the filtered page has no usable text, the run fails - * without replacing the baseline. Changing these selectors creates a new baseline. + * Monitor these CSS-selected regions. Empty or omitted uses main content. Changes + * create a new baseline. */ include_selectors?: Array; @@ -1230,13 +1259,12 @@ export namespace MonitorUpdateResponse { } /** - * Watch a sitemap for URL additions and removals. Crawled URLs are normalized - * (lowercased host, no trailing slash/fragment) and scoped to the monitored site - * and its subdomains before comparison. On a detected difference the sitemap is - * re-fetched within the same run and only URLs both observations agree on are - * reported, suppressing transient crawl flaps. + * Watch a site’s URL inventory for confirmed additions and removals. */ export interface MonitorsSitemapTarget { + /** + * Use `sitemap` to watch a site for added or removed URLs. + */ type: 'sitemap'; /** @@ -1261,11 +1289,8 @@ export namespace MonitorUpdateResponse { } /** - * Watch the monitor-relevant pages of a site for meaningful changes. A crawl - * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to - * track; each run re-checks exactly those pages, and confirmed content changes are - * judged for relevance against the monitor's `instructions` (and `schema`, when - * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + * Track relevant pages selected by `schema` and `instructions`; refresh the page + * set periodically. */ export interface MonitorsExtractTarget { /** @@ -1274,6 +1299,9 @@ export namespace MonitorUpdateResponse { */ instructions: string; + /** + * Use `extract` to watch structured data across selected pages. + */ type: 'extract'; /** @@ -1281,6 +1309,9 @@ export namespace MonitorUpdateResponse { */ url: string; + /** + * Allow page discovery on subdomains of the target site. + */ follow_subdomains?: boolean; /** @@ -1294,14 +1325,8 @@ export namespace MonitorUpdateResponse { max_pages?: number; /** - * JSON Schema describing the data you care about. It is used three ways: it guides - * which pages are selected for tracking, it gives the change judge extra context - * on which changes matter (alongside `instructions`), and it defines the shape of - * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most - * about once a day). It is not a response format for changes: change events and - * webhook payloads always contain diffs, summaries, and evidence excerpts — never - * data in this schema's shape. If omitted, a default summary + key-points schema - * is used. + * JSON Schema for page selection and the baseline snapshot. Changes return diffs + * and evidence. */ schema?: { [key: string]: unknown }; } @@ -1353,10 +1378,8 @@ export namespace MonitorUpdateResponse { captured_at: string; /** - * The extracted structured data, matching the monitor's extraction schema (same - * shape as the /web/extract endpoint's `data`). Refreshed when the monitor - * re-discovers its page set (at most about once a day); `null` when no extraction - * has been captured yet. + * Latest structured snapshot matching the extraction schema, refreshed at most + * daily; `null` before capture. */ data: unknown; @@ -1366,6 +1389,21 @@ export namespace MonitorUpdateResponse { urls_analyzed: Array; } + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } + /** * Error from the most recent failed run; null when the last run succeeded. */ @@ -1375,18 +1413,43 @@ export namespace MonitorUpdateResponse { message: string; } + /** + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + export interface Schedule { + /** + * Number of units between runs. The resulting interval (frequency × unit) must be + * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; + * maximum 365 when unit is days). + */ + frequency: number; + + /** + * Use `interval` to run on a repeating schedule. + */ + type: 'interval'; + + /** + * Time unit used with `frequency` to set the run interval. + */ + unit: 'minutes' | 'hours' | 'days'; + } + + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ export interface Webhook { /** - * Webhook URL events are delivered to. Slack incoming webhook URLs are - * automatically formatted as Slack messages. + * Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted + * messages. */ url: string; /** - * Events delivered to this endpoint. `change.detected` fires only when a run - * detects a change; `run.completed` fires on every completed run — including runs - * that detected no change — and embeds the change when one was detected. Defaults - * to `["change.detected"]` when omitted. + * Events to deliver. Defaults to `change.detected`; `run.completed` also includes + * unchanged runs. */ events?: Array<'change.detected' | 'run.completed'>; @@ -1396,12 +1459,8 @@ export namespace MonitorUpdateResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Omitted unless the API key - * has monitors:write permission or full access. Each delivery includes an - * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over - * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time - * compare and reject stale timestamps to prevent replay. Generated by the API; - * cannot be set by clients. + * API-generated signing secret. Visible only with full access or `monitors:write` + * permission. */ secret?: string; } @@ -1439,6 +1498,17 @@ export interface MonitorListResponse { has_more: boolean; next_cursor: string | null; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorListResponse.KeyMetadata; } export namespace MonitorListResponse { @@ -1450,15 +1520,15 @@ export namespace MonitorListResponse { id: string; /** - * Discriminated union describing how changes are detected. + * How changes are judged. Defaults to `semantic` for extract targets and page + * targets with `instructions`, otherwise `exact`. */ change_detection: Data.MonitorsExactChangeDetection | Data.MonitorsSemanticChangeDetection; created_at: string; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; @@ -1472,26 +1542,21 @@ export namespace MonitorListResponse { schedule: Data.Schedule; /** - * Monitor lifecycle status. `failed` means the most recent run failed (see the - * monitor's `last_error`); failed monitors keep running on schedule and flip back - * to `active` on the next successful run. Monitors are auto-`paused` after - * repeated consecutive failures or insufficient-credit skips; resume by PATCHing - * status to `active`. + * Current state. Failed monitors keep running; paused monitors must be resumed + * with `status: "active"`. */ status: 'active' | 'paused' | 'failed'; /** - * Discriminated union describing what the monitor watches. + * What to watch: a page, a sitemap, or data extracted from a site. */ target: Data.MonitorsPageTarget | Data.MonitorsSitemapTarget | Data.MonitorsExtractTarget; updated_at: string; /** - * Current baseline: the last observed value the monitor compares new snapshots - * against. Its shape follows `target.type` (page/sitemap/extract). Only populated - * on GET /monitors/{monitor_id}; null until the first baseline run completes (and - * after a target or change_detection update, which resets the baseline). + * Comparison baseline, included on Retrieve. Null until capture completes or after + * target changes. */ baseline?: Data.MonitorsPageBaseline | Data.MonitorsSitemapBaseline | Data.MonitorsExtractBaseline | null; @@ -1505,16 +1570,18 @@ export namespace MonitorListResponse { last_run_at?: string | null; /** - * When the next scheduled run is due. + * When the next scheduled run is due; null while paused. */ next_run_at?: string | null; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Labels for filtering monitors, their changes, and their usage. */ tags?: Array; + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ webhook?: Data.Webhook | null; /** @@ -1531,18 +1598,25 @@ export namespace MonitorListResponse { * sitemap targets, this means URL additions and removals. */ export interface MonitorsExactChangeDetection { + /** + * Use `exact` to compare visible text or sitemap URLs. + */ type: 'exact'; } /** - * Detect meaning-level changes to page content, ignoring cosmetic or - * instruction-irrelevant differences. Which changes are meaningful is judged - * against the page or extract target's `instructions` (and an extract target's - * `schema`, when provided). + * Detect meaningful content changes using the target’s instructions and optional + * schema. */ export interface MonitorsSemanticChangeDetection { + /** + * Use `semantic` to judge changes against the target instructions. + */ type: 'semantic'; + /** + * Minimum confidence required to report a meaningful change, from 0 to 1. + */ confidence_threshold?: number; } @@ -1559,8 +1633,14 @@ export namespace MonitorListResponse { */ frequency: number; + /** + * Use `interval` to run on a repeating schedule. + */ type: 'interval'; + /** + * Time unit used with `frequency` to set the run interval. + */ unit: 'minutes' | 'hours' | 'days'; } @@ -1569,24 +1649,24 @@ export namespace MonitorListResponse { * detection judges confirmed stable diffs against `instructions`. */ export interface MonitorsPageTarget { + /** + * Use `page` to watch one web page. + */ type: 'page'; + /** + * Public HTTP(S) page URL to monitor. + */ url: string; /** - * CSS selectors for HTML regions to remove before text extraction. Applied after - * include_selectors; exclusion takes precedence when an element matches both. Omit - * or pass an empty array to apply no explicit exclusions. Changing these selectors - * creates a new baseline. + * Remove matching regions after inclusions. Changes create a new baseline. */ exclude_selectors?: Array; /** - * CSS selectors defining the HTML regions to monitor. Matching subtrees are - * combined in document order before text extraction, instead of automatic - * main-content selection. Omit or pass an empty array to use automatic - * main-content extraction. If the filtered page has no usable text, the run fails - * without replacing the baseline. Changing these selectors creates a new baseline. + * Monitor these CSS-selected regions. Empty or omitted uses main content. Changes + * create a new baseline. */ include_selectors?: Array; @@ -1603,13 +1683,12 @@ export namespace MonitorListResponse { } /** - * Watch a sitemap for URL additions and removals. Crawled URLs are normalized - * (lowercased host, no trailing slash/fragment) and scoped to the monitored site - * and its subdomains before comparison. On a detected difference the sitemap is - * re-fetched within the same run and only URLs both observations agree on are - * reported, suppressing transient crawl flaps. + * Watch a site’s URL inventory for confirmed additions and removals. */ export interface MonitorsSitemapTarget { + /** + * Use `sitemap` to watch a site for added or removed URLs. + */ type: 'sitemap'; /** @@ -1634,11 +1713,8 @@ export namespace MonitorListResponse { } /** - * Watch the monitor-relevant pages of a site for meaningful changes. A crawl - * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to - * track; each run re-checks exactly those pages, and confirmed content changes are - * judged for relevance against the monitor's `instructions` (and `schema`, when - * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + * Track relevant pages selected by `schema` and `instructions`; refresh the page + * set periodically. */ export interface MonitorsExtractTarget { /** @@ -1647,6 +1723,9 @@ export namespace MonitorListResponse { */ instructions: string; + /** + * Use `extract` to watch structured data across selected pages. + */ type: 'extract'; /** @@ -1654,6 +1733,9 @@ export namespace MonitorListResponse { */ url: string; + /** + * Allow page discovery on subdomains of the target site. + */ follow_subdomains?: boolean; /** @@ -1667,14 +1749,8 @@ export namespace MonitorListResponse { max_pages?: number; /** - * JSON Schema describing the data you care about. It is used three ways: it guides - * which pages are selected for tracking, it gives the change judge extra context - * on which changes matter (alongside `instructions`), and it defines the shape of - * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most - * about once a day). It is not a response format for changes: change events and - * webhook payloads always contain diffs, summaries, and evidence excerpts — never - * data in this schema's shape. If omitted, a default summary + key-points schema - * is used. + * JSON Schema for page selection and the baseline snapshot. Changes return diffs + * and evidence. */ schema?: { [key: string]: unknown }; } @@ -1726,10 +1802,8 @@ export namespace MonitorListResponse { captured_at: string; /** - * The extracted structured data, matching the monitor's extraction schema (same - * shape as the /web/extract endpoint's `data`). Refreshed when the monitor - * re-discovers its page set (at most about once a day); `null` when no extraction - * has been captured yet. + * Latest structured snapshot matching the extraction schema, refreshed at most + * daily; `null` before capture. */ data: unknown; @@ -1748,18 +1822,19 @@ export namespace MonitorListResponse { message: string; } + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ export interface Webhook { /** - * Webhook URL events are delivered to. Slack incoming webhook URLs are - * automatically formatted as Slack messages. + * Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted + * messages. */ url: string; /** - * Events delivered to this endpoint. `change.detected` fires only when a run - * detects a change; `run.completed` fires on every completed run — including runs - * that detected no change — and embeds the change when one was detected. Defaults - * to `["change.detected"]` when omitted. + * Events to deliver. Defaults to `change.detected`; `run.completed` also includes + * unchanged runs. */ events?: Array<'change.detected' | 'run.completed'>; @@ -1769,12 +1844,8 @@ export namespace MonitorListResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Omitted unless the API key - * has monitors:write permission or full access. Each delivery includes an - * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over - * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time - * compare and reject stale timestamps to prevent replay. Generated by the API; - * cannot be set by clients. + * API-generated signing secret. Visible only with full access or `monitors:write` + * permission. */ secret?: string; } @@ -1805,21 +1876,75 @@ export namespace MonitorListResponse { last_status: 'rejected' | 'failed' | 'skipped_unsafe_url'; } } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } export interface MonitorDeleteResponse { id: string; deleted: boolean; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorDeleteResponse.KeyMetadata; +} + +export namespace MonitorDeleteResponse { + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } export interface MonitorGetCreditUsageResponse { data: Array; + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + /** * Sum of credits across all monitors in the window. */ total_credits: number; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorGetCreditUsageResponse.KeyMetadata; } export namespace MonitorGetCreditUsageResponse { @@ -1841,12 +1966,26 @@ export namespace MonitorGetCreditUsageResponse { */ runs: number; } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } export interface MonitorGetLimitsResponse { /** - * Maximum number of monitors allowed for the account. Defaults to the plan - * allowance unless a custom limit is set for the organization. + * Most monitors you can have: your plan's allowance or a custom limit. */ monitors_limit: number; @@ -1856,9 +1995,38 @@ export interface MonitorGetLimitsResponse { monitors_used: number; /** - * The plan tier the limit was resolved from. + * `starter` means Developer; `pro` means Pro or Growth; `scale` means Scale or + * Enterprise. */ plan: 'free' | 'starter' | 'pro' | 'scale'; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorGetLimitsResponse.KeyMetadata; +} + +export namespace MonitorGetLimitsResponse { + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } export interface MonitorListAccountChangesResponse { @@ -1867,15 +2035,22 @@ export interface MonitorListAccountChangesResponse { has_more: boolean; next_cursor: string | null; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorListAccountChangesResponse.KeyMetadata; } export namespace MonitorListAccountChangesResponse { /** - * A lightweight change summary. `mode` is the constant `web`; `target_type` and - * `change_detection_type` describe the change, and which optional fields are - * present depends on them (e.g. sitemap changes include - * `added_url_count`/`removed_url_count`; semantic changes include - * `confidence`/`importance`). + * Detected change, including applicable diffs, URLs, and supporting evidence. */ export interface Data { id: string; @@ -1885,15 +2060,24 @@ export namespace MonitorListAccountChangesResponse { detected_at: string; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; monitor_id: string; + /** + * The run that detected this change. + */ + run_id: string; + summary: string; + /** + * Labels for filtering monitors, their changes, and their usage. + */ + tags: Array; + target_type: 'page' | 'sitemap' | 'extract'; title: string; @@ -1902,19 +2086,73 @@ export namespace MonitorListAccountChangesResponse { added_url_count?: number; + /** + * At most 500 URLs are included; the corresponding count field is always exact. + */ + added_urls?: Array; + + after_text_excerpt?: string; + + before_text_excerpt?: string; + confidence?: number; + /** + * Text diff between the previous and current page baseline (page targets). + */ + diff?: string; + + evidence?: Array; + importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; + /** + * At most 500 URLs are included; the corresponding count field is always exact. + */ + matched_urls?: Array; + removed_url_count?: number; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * At most 500 URLs are included; the corresponding count field is always exact. */ - tags?: Array; + removed_urls?: Array; + } + + export namespace Data { + export interface Evidence { + /** + * Snapshot of the content after the change. + */ + after: string; + + /** + * Snapshot of the content before the change. + */ + before: string; + + /** + * Optional URL the evidence relates to. Absent for whole-target diffs. + */ + url?: string; + } + } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; } } @@ -1923,7 +2161,18 @@ export interface MonitorListAccountRunsResponse { has_more: boolean; - next_cursor: string | null; + next_cursor: string | null; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorListAccountRunsResponse.KeyMetadata; } export namespace MonitorListAccountRunsResponse { @@ -1948,7 +2197,7 @@ export namespace MonitorListAccountRunsResponse { monitor_id: string; /** - * The first run after monitor creation is a baseline run. + * A baseline run follows creation or a target or detection change. */ run_type: 'baseline' | 'scheduled'; @@ -1981,9 +2230,7 @@ export namespace MonitorListAccountRunsResponse { webhook_deliveries?: Array; /** - * @deprecated Deprecated: use `webhook_deliveries`, which records every attempt - * now that a run can deliver multiple events. Omitted when no webhook was - * attempted, including historical runs created before delivery tracking was added. + * @deprecated Deprecated. Use `webhook_deliveries` for all attempts. */ webhook_delivery?: MonitorsAPI.WebhookDelivery; @@ -2000,6 +2247,21 @@ export namespace MonitorListAccountRunsResponse { message: string; } } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } export interface MonitorListChangesResponse { @@ -2008,15 +2270,22 @@ export interface MonitorListChangesResponse { has_more: boolean; next_cursor: string | null; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorListChangesResponse.KeyMetadata; } export namespace MonitorListChangesResponse { /** - * A lightweight change summary. `mode` is the constant `web`; `target_type` and - * `change_detection_type` describe the change, and which optional fields are - * present depends on them (e.g. sitemap changes include - * `added_url_count`/`removed_url_count`; semantic changes include - * `confidence`/`importance`). + * Detected change, including applicable diffs, URLs, and supporting evidence. */ export interface Data { id: string; @@ -2026,15 +2295,24 @@ export namespace MonitorListChangesResponse { detected_at: string; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; monitor_id: string; + /** + * The run that detected this change. + */ + run_id: string; + summary: string; + /** + * Labels for filtering monitors, their changes, and their usage. + */ + tags: Array; + target_type: 'page' | 'sitemap' | 'extract'; title: string; @@ -2043,19 +2321,73 @@ export namespace MonitorListChangesResponse { added_url_count?: number; + /** + * At most 500 URLs are included; the corresponding count field is always exact. + */ + added_urls?: Array; + + after_text_excerpt?: string; + + before_text_excerpt?: string; + confidence?: number; + /** + * Text diff between the previous and current page baseline (page targets). + */ + diff?: string; + + evidence?: Array; + importance?: 'low' | 'medium' | 'high'; matched_url_count?: number; + /** + * At most 500 URLs are included; the corresponding count field is always exact. + */ + matched_urls?: Array; + removed_url_count?: number; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * At most 500 URLs are included; the corresponding count field is always exact. */ - tags?: Array; + removed_urls?: Array; + } + + export namespace Data { + export interface Evidence { + /** + * Snapshot of the content after the change. + */ + after: string; + + /** + * Snapshot of the content before the change. + */ + before: string; + + /** + * Optional URL the evidence relates to. Absent for whole-target diffs. + */ + url?: string; + } + } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; } } @@ -2065,6 +2397,17 @@ export interface MonitorListRunsResponse { has_more: boolean; next_cursor: string | null; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorListRunsResponse.KeyMetadata; } export namespace MonitorListRunsResponse { @@ -2089,7 +2432,7 @@ export namespace MonitorListRunsResponse { monitor_id: string; /** - * The first run after monitor creation is a baseline run. + * A baseline run follows creation or a target or detection change. */ run_type: 'baseline' | 'scheduled'; @@ -2122,9 +2465,7 @@ export namespace MonitorListRunsResponse { webhook_deliveries?: Array; /** - * @deprecated Deprecated: use `webhook_deliveries`, which records every attempt - * now that a run can deliver multiple events. Omitted when no webhook was - * attempted, including historical runs created before delivery tracking was added. + * @deprecated Deprecated. Use `webhook_deliveries` for all attempts. */ webhook_delivery?: MonitorsAPI.WebhookDelivery; @@ -2141,15 +2482,23 @@ export namespace MonitorListRunsResponse { message: string; } } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } -/** - * A detected change. `mode` is the constant `web`; `target_type` and - * `change_detection_type` describe the change, and which optional fields are - * present depends on them (page: `diff` + excerpts; sitemap: - * `added_urls`/`removed_urls`; semantic: - * `confidence`/`importance`/`evidence`/`matched_urls`). - */ export interface MonitorRetrieveChangeResponse { id: string; @@ -2158,13 +2507,18 @@ export interface MonitorRetrieveChangeResponse { detected_at: string; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; monitor_id: string; + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + /** * The run that detected this change. */ @@ -2173,8 +2527,7 @@ export interface MonitorRetrieveChangeResponse { summary: string; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Labels for filtering monitors, their changes, and their usage. */ tags: Array; @@ -2206,6 +2559,11 @@ export interface MonitorRetrieveChangeResponse { importance?: 'low' | 'medium' | 'high'; + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorRetrieveChangeResponse.KeyMetadata; + matched_url_count?: number; /** @@ -2238,6 +2596,21 @@ export namespace MonitorRetrieveChangeResponse { */ url?: string; } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } export interface MonitorRetrieveRunResponse { @@ -2261,7 +2634,13 @@ export interface MonitorRetrieveRunResponse { monitor_id: string; /** - * The first run after monitor creation is a baseline run. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * A baseline run follows creation or a target or detection change. */ run_type: 'baseline' | 'scheduled'; @@ -2279,6 +2658,11 @@ export interface MonitorRetrieveRunResponse { error?: MonitorRetrieveRunResponse.Error | null; + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorRetrieveRunResponse.KeyMetadata; + /** * Why a skipped run never executed; null unless status is `skipped`. */ @@ -2294,9 +2678,7 @@ export interface MonitorRetrieveRunResponse { webhook_deliveries?: Array; /** - * @deprecated Deprecated: use `webhook_deliveries`, which records every attempt - * now that a run can deliver multiple events. Omitted when no webhook was - * attempted, including historical runs created before delivery tracking was added. + * @deprecated Deprecated. Use `webhook_deliveries` for all attempts. */ webhook_delivery?: WebhookDelivery; @@ -2312,17 +2694,29 @@ export namespace MonitorRetrieveRunResponse { message: string; } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } -/** - * A web monitor. `mode` is the constant `web`; behavior is described by `target` - * (page/sitemap/extract) and `change_detection` (exact/semantic). - */ export interface MonitorRotateWebhookSecretResponse { id: string; /** - * Discriminated union describing how changes are detected. + * How changes are judged. Defaults to `semantic` for extract targets and page + * targets with `instructions`, otherwise `exact`. */ change_detection: | MonitorRotateWebhookSecretResponse.MonitorsExactChangeDetection @@ -2331,31 +2725,26 @@ export interface MonitorRotateWebhookSecretResponse { created_at: string; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode: 'web'; name: string; /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ - schedule: MonitorRotateWebhookSecretResponse.Schedule; + request_id: string; /** - * Monitor lifecycle status. `failed` means the most recent run failed (see the - * monitor's `last_error`); failed monitors keep running on schedule and flip back - * to `active` on the next successful run. Monitors are auto-`paused` after - * repeated consecutive failures or insufficient-credit skips; resume by PATCHing - * status to `active`. + * Current state. Failed monitors keep running; paused monitors must be resumed + * with `status: "active"`. */ status: 'active' | 'paused' | 'failed'; /** - * Discriminated union describing what the monitor watches. + * What to watch: a page, a sitemap, or data extracted from a site. */ target: | MonitorRotateWebhookSecretResponse.MonitorsPageTarget @@ -2365,10 +2754,8 @@ export interface MonitorRotateWebhookSecretResponse { updated_at: string; /** - * Current baseline: the last observed value the monitor compares new snapshots - * against. Its shape follows `target.type` (page/sitemap/extract). Only populated - * on GET /monitors/{monitor_id}; null until the first baseline run completes (and - * after a target or change_detection update, which resets the baseline). + * Comparison baseline, included on Retrieve. Null until capture completes or after + * target changes. */ baseline?: | MonitorRotateWebhookSecretResponse.MonitorsPageBaseline @@ -2376,6 +2763,11 @@ export interface MonitorRotateWebhookSecretResponse { | MonitorRotateWebhookSecretResponse.MonitorsExtractBaseline | null; + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorRotateWebhookSecretResponse.KeyMetadata; + last_change_at?: string | null; /** @@ -2386,16 +2778,25 @@ export interface MonitorRotateWebhookSecretResponse { last_run_at?: string | null; /** - * When the next scheduled run is due. + * When the next scheduled run is due; null while paused. */ next_run_at?: string | null; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + schedule?: MonitorRotateWebhookSecretResponse.Schedule; + + /** + * Labels for filtering monitors, their changes, and their usage. */ tags?: Array; + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ webhook?: MonitorRotateWebhookSecretResponse.Webhook | null; /** @@ -2412,37 +2813,26 @@ export namespace MonitorRotateWebhookSecretResponse { * sitemap targets, this means URL additions and removals. */ export interface MonitorsExactChangeDetection { + /** + * Use `exact` to compare visible text or sitemap URLs. + */ type: 'exact'; } /** - * Detect meaning-level changes to page content, ignoring cosmetic or - * instruction-irrelevant differences. Which changes are meaningful is judged - * against the page or extract target's `instructions` (and an extract target's - * `schema`, when provided). + * Detect meaningful content changes using the target’s instructions and optional + * schema. */ export interface MonitorsSemanticChangeDetection { + /** + * Use `semantic` to judge changes against the target instructions. + */ type: 'semantic'; - confidence_threshold?: number; - } - - /** - * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. - * every 6 hours or every 2 days. The total interval (frequency × unit) must be - * between 10 minutes and 1 year. - */ - export interface Schedule { /** - * Number of units between runs. The resulting interval (frequency × unit) must be - * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; - * maximum 365 when unit is days). + * Minimum confidence required to report a meaningful change, from 0 to 1. */ - frequency: number; - - type: 'interval'; - - unit: 'minutes' | 'hours' | 'days'; + confidence_threshold?: number; } /** @@ -2450,24 +2840,24 @@ export namespace MonitorRotateWebhookSecretResponse { * detection judges confirmed stable diffs against `instructions`. */ export interface MonitorsPageTarget { + /** + * Use `page` to watch one web page. + */ type: 'page'; + /** + * Public HTTP(S) page URL to monitor. + */ url: string; /** - * CSS selectors for HTML regions to remove before text extraction. Applied after - * include_selectors; exclusion takes precedence when an element matches both. Omit - * or pass an empty array to apply no explicit exclusions. Changing these selectors - * creates a new baseline. + * Remove matching regions after inclusions. Changes create a new baseline. */ exclude_selectors?: Array; /** - * CSS selectors defining the HTML regions to monitor. Matching subtrees are - * combined in document order before text extraction, instead of automatic - * main-content selection. Omit or pass an empty array to use automatic - * main-content extraction. If the filtered page has no usable text, the run fails - * without replacing the baseline. Changing these selectors creates a new baseline. + * Monitor these CSS-selected regions. Empty or omitted uses main content. Changes + * create a new baseline. */ include_selectors?: Array; @@ -2484,13 +2874,12 @@ export namespace MonitorRotateWebhookSecretResponse { } /** - * Watch a sitemap for URL additions and removals. Crawled URLs are normalized - * (lowercased host, no trailing slash/fragment) and scoped to the monitored site - * and its subdomains before comparison. On a detected difference the sitemap is - * re-fetched within the same run and only URLs both observations agree on are - * reported, suppressing transient crawl flaps. + * Watch a site’s URL inventory for confirmed additions and removals. */ export interface MonitorsSitemapTarget { + /** + * Use `sitemap` to watch a site for added or removed URLs. + */ type: 'sitemap'; /** @@ -2515,11 +2904,8 @@ export namespace MonitorRotateWebhookSecretResponse { } /** - * Watch the monitor-relevant pages of a site for meaningful changes. A crawl - * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to - * track; each run re-checks exactly those pages, and confirmed content changes are - * judged for relevance against the monitor's `instructions` (and `schema`, when - * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + * Track relevant pages selected by `schema` and `instructions`; refresh the page + * set periodically. */ export interface MonitorsExtractTarget { /** @@ -2528,6 +2914,9 @@ export namespace MonitorRotateWebhookSecretResponse { */ instructions: string; + /** + * Use `extract` to watch structured data across selected pages. + */ type: 'extract'; /** @@ -2535,6 +2924,9 @@ export namespace MonitorRotateWebhookSecretResponse { */ url: string; + /** + * Allow page discovery on subdomains of the target site. + */ follow_subdomains?: boolean; /** @@ -2548,14 +2940,8 @@ export namespace MonitorRotateWebhookSecretResponse { max_pages?: number; /** - * JSON Schema describing the data you care about. It is used three ways: it guides - * which pages are selected for tracking, it gives the change judge extra context - * on which changes matter (alongside `instructions`), and it defines the shape of - * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most - * about once a day). It is not a response format for changes: change events and - * webhook payloads always contain diffs, summaries, and evidence excerpts — never - * data in this schema's shape. If omitted, a default summary + key-points schema - * is used. + * JSON Schema for page selection and the baseline snapshot. Changes return diffs + * and evidence. */ schema?: { [key: string]: unknown }; } @@ -2607,10 +2993,8 @@ export namespace MonitorRotateWebhookSecretResponse { captured_at: string; /** - * The extracted structured data, matching the monitor's extraction schema (same - * shape as the /web/extract endpoint's `data`). Refreshed when the monitor - * re-discovers its page set (at most about once a day); `null` when no extraction - * has been captured yet. + * Latest structured snapshot matching the extraction schema, refreshed at most + * daily; `null` before capture. */ data: unknown; @@ -2620,6 +3004,21 @@ export namespace MonitorRotateWebhookSecretResponse { urls_analyzed: Array; } + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } + /** * Error from the most recent failed run; null when the last run succeeded. */ @@ -2629,18 +3028,43 @@ export namespace MonitorRotateWebhookSecretResponse { message: string; } + /** + * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. + * every 6 hours or every 2 days. The total interval (frequency × unit) must be + * between 10 minutes and 1 year. + */ + export interface Schedule { + /** + * Number of units between runs. The resulting interval (frequency × unit) must be + * at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; + * maximum 365 when unit is days). + */ + frequency: number; + + /** + * Use `interval` to run on a repeating schedule. + */ + type: 'interval'; + + /** + * Time unit used with `frequency` to set the run interval. + */ + unit: 'minutes' | 'hours' | 'days'; + } + + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ export interface Webhook { /** - * Webhook URL events are delivered to. Slack incoming webhook URLs are - * automatically formatted as Slack messages. + * Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted + * messages. */ url: string; /** - * Events delivered to this endpoint. `change.detected` fires only when a run - * detects a change; `run.completed` fires on every completed run — including runs - * that detected no change — and embeds the change when one was detected. Defaults - * to `["change.detected"]` when omitted. + * Events to deliver. Defaults to `change.detected`; `run.completed` also includes + * unchanged runs. */ events?: Array<'change.detected' | 'run.completed'>; @@ -2650,12 +3074,8 @@ export namespace MonitorRotateWebhookSecretResponse { retry?: WebhooksAPI.RetryConfig; /** - * Signing secret used to verify webhook authenticity. Omitted unless the API key - * has monitors:write permission or full access. Each delivery includes an - * `X-Context-Signature: t=,v1=` header, where the HMAC is SHA-256 over - * `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time - * compare and reject stale timestamps to prevent replay. Generated by the API; - * cannot be set by clients. + * API-generated signing secret. Visible only with full access or `monitors:write` + * permission. */ secret?: string; } @@ -2693,17 +3113,47 @@ export interface MonitorRunResponse { queued: boolean; /** - * The queued run. Poll GET /monitors/{monitor_id}/runs or use it to correlate - * results. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * ID of the queued run; pass it to Retrieve a monitor run. */ run_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: MonitorRunResponse.KeyMetadata; +} + +export namespace MonitorRunResponse { + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } } export interface MonitorCreateParams { + /** + * Display name for the monitor. + */ name: string; /** - * Discriminated union describing what the monitor watches. + * What to watch: a page, a sitemap, or data extracted from a site. */ target: | MonitorCreateParams.MonitorsPageTarget @@ -2711,15 +3161,15 @@ export interface MonitorCreateParams { | MonitorCreateParams.MonitorsExtractTarget; /** - * Discriminated union describing how changes are detected. + * How changes are judged. Defaults to `semantic` for extract targets and page + * targets with `instructions`, otherwise `exact`. */ change_detection?: | MonitorCreateParams.MonitorsExactChangeDetection | MonitorCreateParams.MonitorsSemanticChangeDetection; /** - * Top-level monitor category. Always `web` today; the concrete behavior is - * described by `target` and `change_detection`. + * Always `web`. Optional. */ mode?: 'web'; @@ -2731,11 +3181,13 @@ export interface MonitorCreateParams { schedule?: MonitorCreateParams.Schedule; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Labels for filtering monitors, their changes, and their usage. */ tags?: Array; + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ webhook?: MonitorCreateParams.Webhook | null; } @@ -2745,24 +3197,24 @@ export namespace MonitorCreateParams { * detection judges confirmed stable diffs against `instructions`. */ export interface MonitorsPageTarget { + /** + * Use `page` to watch one web page. + */ type: 'page'; + /** + * Public HTTP(S) page URL to monitor. + */ url: string; /** - * CSS selectors for HTML regions to remove before text extraction. Applied after - * include_selectors; exclusion takes precedence when an element matches both. Omit - * or pass an empty array to apply no explicit exclusions. Changing these selectors - * creates a new baseline. + * Remove matching regions after inclusions. Changes create a new baseline. */ exclude_selectors?: Array; /** - * CSS selectors defining the HTML regions to monitor. Matching subtrees are - * combined in document order before text extraction, instead of automatic - * main-content selection. Omit or pass an empty array to use automatic - * main-content extraction. If the filtered page has no usable text, the run fails - * without replacing the baseline. Changing these selectors creates a new baseline. + * Monitor these CSS-selected regions. Empty or omitted uses main content. Changes + * create a new baseline. */ include_selectors?: Array; @@ -2779,13 +3231,12 @@ export namespace MonitorCreateParams { } /** - * Watch a sitemap for URL additions and removals. Crawled URLs are normalized - * (lowercased host, no trailing slash/fragment) and scoped to the monitored site - * and its subdomains before comparison. On a detected difference the sitemap is - * re-fetched within the same run and only URLs both observations agree on are - * reported, suppressing transient crawl flaps. + * Watch a site’s URL inventory for confirmed additions and removals. */ export interface MonitorsSitemapTarget { + /** + * Use `sitemap` to watch a site for added or removed URLs. + */ type: 'sitemap'; /** @@ -2810,11 +3261,8 @@ export namespace MonitorCreateParams { } /** - * Watch the monitor-relevant pages of a site for meaningful changes. A crawl - * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to - * track; each run re-checks exactly those pages, and confirmed content changes are - * judged for relevance against the monitor's `instructions` (and `schema`, when - * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + * Track relevant pages selected by `schema` and `instructions`; refresh the page + * set periodically. */ export interface MonitorsExtractTarget { /** @@ -2823,6 +3271,9 @@ export namespace MonitorCreateParams { */ instructions: string; + /** + * Use `extract` to watch structured data across selected pages. + */ type: 'extract'; /** @@ -2830,6 +3281,9 @@ export namespace MonitorCreateParams { */ url: string; + /** + * Allow page discovery on subdomains of the target site. + */ follow_subdomains?: boolean; /** @@ -2843,14 +3297,8 @@ export namespace MonitorCreateParams { max_pages?: number; /** - * JSON Schema describing the data you care about. It is used three ways: it guides - * which pages are selected for tracking, it gives the change judge extra context - * on which changes matter (alongside `instructions`), and it defines the shape of - * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most - * about once a day). It is not a response format for changes: change events and - * webhook payloads always contain diffs, summaries, and evidence excerpts — never - * data in this schema's shape. If omitted, a default summary + key-points schema - * is used. + * JSON Schema for page selection and the baseline snapshot. Changes return diffs + * and evidence. */ schema?: { [key: string]: unknown }; } @@ -2860,18 +3308,25 @@ export namespace MonitorCreateParams { * sitemap targets, this means URL additions and removals. */ export interface MonitorsExactChangeDetection { + /** + * Use `exact` to compare visible text or sitemap URLs. + */ type: 'exact'; } /** - * Detect meaning-level changes to page content, ignoring cosmetic or - * instruction-irrelevant differences. Which changes are meaningful is judged - * against the page or extract target's `instructions` (and an extract target's - * `schema`, when provided). + * Detect meaningful content changes using the target’s instructions and optional + * schema. */ export interface MonitorsSemanticChangeDetection { + /** + * Use `semantic` to judge changes against the target instructions. + */ type: 'semantic'; + /** + * Minimum confidence required to report a meaningful change, from 0 to 1. + */ confidence_threshold?: number; } @@ -2888,23 +3343,30 @@ export namespace MonitorCreateParams { */ frequency: number; + /** + * Use `interval` to run on a repeating schedule. + */ type: 'interval'; + /** + * Time unit used with `frequency` to set the run interval. + */ unit: 'minutes' | 'hours' | 'days'; } + /** + * Webhook destination and delivery settings. Null means no webhook is configured. + */ export interface Webhook { /** - * Webhook URL events are delivered to. Slack incoming webhook URLs are - * automatically formatted as Slack messages. + * Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted + * messages. */ url: string; /** - * Events delivered to this endpoint. `change.detected` fires only when a run - * detects a change; `run.completed` fires on every completed run — including runs - * that detected no change — and embeds the change when one was detected. Defaults - * to `["change.detected"]` when omitted. + * Events to deliver. Defaults to `change.detected`; `run.completed` also includes + * unchanged runs. */ events?: Array<'change.detected' | 'run.completed'>; @@ -2917,12 +3379,16 @@ export namespace MonitorCreateParams { export interface MonitorUpdateParams { /** - * Discriminated union describing how changes are detected. + * How changes are judged. Defaults to `semantic` for extract targets and page + * targets with `instructions`, otherwise `exact`. */ change_detection?: | MonitorUpdateParams.MonitorsExactChangeDetection | MonitorUpdateParams.MonitorsSemanticChangeDetection; + /** + * Display name for the monitor. + */ name?: string; /** @@ -2932,16 +3398,18 @@ export interface MonitorUpdateParams { */ schedule?: MonitorUpdateParams.Schedule; + /** + * Set `paused` to stop scheduled runs or `active` to resume them. + */ status?: 'active' | 'paused'; /** - * User-defined tags for grouping and filtering monitors and their changes. - * Duplicates are removed. + * Labels for filtering monitors, their changes, and their usage. */ tags?: Array; /** - * Discriminated union describing what the monitor watches. + * What to watch: a page, a sitemap, or data extracted from a site. */ target?: | MonitorUpdateParams.MonitorsPageTarget @@ -2949,7 +3417,7 @@ export interface MonitorUpdateParams { | MonitorUpdateParams.MonitorsExtractTarget; /** - * Set to null to remove the webhook. + * Set to null to remove the webhook. Changing `url` issues a new secret. */ webhook?: MonitorUpdateParams.Webhook | null; } @@ -2960,18 +3428,25 @@ export namespace MonitorUpdateParams { * sitemap targets, this means URL additions and removals. */ export interface MonitorsExactChangeDetection { + /** + * Use `exact` to compare visible text or sitemap URLs. + */ type: 'exact'; } /** - * Detect meaning-level changes to page content, ignoring cosmetic or - * instruction-irrelevant differences. Which changes are meaningful is judged - * against the page or extract target's `instructions` (and an extract target's - * `schema`, when provided). + * Detect meaningful content changes using the target’s instructions and optional + * schema. */ export interface MonitorsSemanticChangeDetection { + /** + * Use `semantic` to judge changes against the target instructions. + */ type: 'semantic'; + /** + * Minimum confidence required to report a meaningful change, from 0 to 1. + */ confidence_threshold?: number; } @@ -2988,8 +3463,14 @@ export namespace MonitorUpdateParams { */ frequency: number; + /** + * Use `interval` to run on a repeating schedule. + */ type: 'interval'; + /** + * Time unit used with `frequency` to set the run interval. + */ unit: 'minutes' | 'hours' | 'days'; } @@ -2998,24 +3479,24 @@ export namespace MonitorUpdateParams { * detection judges confirmed stable diffs against `instructions`. */ export interface MonitorsPageTarget { + /** + * Use `page` to watch one web page. + */ type: 'page'; + /** + * Public HTTP(S) page URL to monitor. + */ url: string; /** - * CSS selectors for HTML regions to remove before text extraction. Applied after - * include_selectors; exclusion takes precedence when an element matches both. Omit - * or pass an empty array to apply no explicit exclusions. Changing these selectors - * creates a new baseline. + * Remove matching regions after inclusions. Changes create a new baseline. */ exclude_selectors?: Array; /** - * CSS selectors defining the HTML regions to monitor. Matching subtrees are - * combined in document order before text extraction, instead of automatic - * main-content selection. Omit or pass an empty array to use automatic - * main-content extraction. If the filtered page has no usable text, the run fails - * without replacing the baseline. Changing these selectors creates a new baseline. + * Monitor these CSS-selected regions. Empty or omitted uses main content. Changes + * create a new baseline. */ include_selectors?: Array; @@ -3032,13 +3513,12 @@ export namespace MonitorUpdateParams { } /** - * Watch a sitemap for URL additions and removals. Crawled URLs are normalized - * (lowercased host, no trailing slash/fragment) and scoped to the monitored site - * and its subdomains before comparison. On a detected difference the sitemap is - * re-fetched within the same run and only URLs both observations agree on are - * reported, suppressing transient crawl flaps. + * Watch a site’s URL inventory for confirmed additions and removals. */ export interface MonitorsSitemapTarget { + /** + * Use `sitemap` to watch a site for added or removed URLs. + */ type: 'sitemap'; /** @@ -3063,11 +3543,8 @@ export namespace MonitorUpdateParams { } /** - * Watch the monitor-relevant pages of a site for meaningful changes. A crawl - * guided by `schema`/`instructions` selects up to `max_pages` relevant pages to - * track; each run re-checks exactly those pages, and confirmed content changes are - * judged for relevance against the monitor's `instructions` (and `schema`, when - * provided). The tracked page set is refreshed by a periodic re-discovery crawl. + * Track relevant pages selected by `schema` and `instructions`; refresh the page + * set periodically. */ export interface MonitorsExtractTarget { /** @@ -3076,6 +3553,9 @@ export namespace MonitorUpdateParams { */ instructions: string; + /** + * Use `extract` to watch structured data across selected pages. + */ type: 'extract'; /** @@ -3083,6 +3563,9 @@ export namespace MonitorUpdateParams { */ url: string; + /** + * Allow page discovery on subdomains of the target site. + */ follow_subdomains?: boolean; /** @@ -3096,33 +3579,25 @@ export namespace MonitorUpdateParams { max_pages?: number; /** - * JSON Schema describing the data you care about. It is used three ways: it guides - * which pages are selected for tracking, it gives the change judge extra context - * on which changes matter (alongside `instructions`), and it defines the shape of - * the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most - * about once a day). It is not a response format for changes: change events and - * webhook payloads always contain diffs, summaries, and evidence excerpts — never - * data in this schema's shape. If omitted, a default summary + key-points schema - * is used. + * JSON Schema for page selection and the baseline snapshot. Changes return diffs + * and evidence. */ schema?: { [key: string]: unknown }; } /** - * Set to null to remove the webhook. + * Set to null to remove the webhook. Changing `url` issues a new secret. */ export interface Webhook { /** - * Webhook URL events are delivered to. Slack incoming webhook URLs are - * automatically formatted as Slack messages. + * Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted + * messages. */ url: string; /** - * Events delivered to this endpoint. `change.detected` fires only when a run - * detects a change; `run.completed` fires on every completed run — including runs - * that detected no change — and embeds the change when one was detected. Defaults - * to `["change.detected"]` when omitted. + * Events to deliver. Defaults to `change.detected`; `run.completed` also includes + * unchanged runs. */ events?: Array<'change.detected' | 'run.completed'>; @@ -3155,8 +3630,8 @@ export interface MonitorListParams { q?: string; /** - * Comma-separated fields to search with `q`. Defaults to all of them. Note - * `instructions` only exists on extract monitors. + * Fields to search with `q`. Defaults to all fields; page and extract targets can + * have instructions. */ search_by?: Array<'name' | 'url' | 'instructions' | 'tags'> | null; @@ -3303,6 +3778,9 @@ export interface MonitorListRunsParams { } export interface MonitorRetrieveRunParams { + /** + * ID of the monitor. + */ monitor_id: string; } diff --git a/src/resources/news.ts b/src/resources/news.ts index e5f72573..c857c1bc 100644 --- a/src/resources/news.ts +++ b/src/resources/news.ts @@ -5,23 +5,19 @@ import { APIPromise } from '../core/api-promise'; import { RequestOptions } from '../internal/request-options'; /** - * Search live first-party RSS and free historical news data by company identity. + * Search live and historical news about a company. */ export class News extends APIResource { /** - * Searches live and historical company news for one company, identified in - * searchBy by name, domain, ticker (optionally disambiguated by exchange), or - * ISIN. Results can be filtered by one of publisher domain, publisher country, - * article language, or article type, optionally combined with a published-at date - * range, and include stable story IDs, source metadata, verified entity relevance, - * and cursor pagination. + * Find company news by name, domain, ticker, or ISIN. Filter articles and continue + * through results with a cursor. * * @example * ```ts * const response = await client.news.search({ * searchBy: { - * entity: { name: 'xx', type: 'name' }, * type: 'entity', + * entity: { type: 'domain', domain: 'stripe.com' }, * }, * }); * ``` @@ -54,13 +50,13 @@ export interface NewsSearchResponse { next_cursor: string | null; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: NewsSearchResponse.KeyMetadata; } @@ -182,11 +178,11 @@ export namespace NewsSearchResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -226,7 +222,7 @@ export interface NewsSearchParams { sortBy?: NewsSearchParams.SortBy; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; } @@ -261,6 +257,9 @@ export namespace NewsSearchParams { */ name: string; + /** + * Use `name` to identify the company by name. + */ type: 'name'; } @@ -273,6 +272,9 @@ export namespace NewsSearchParams { */ domain: string; + /** + * Use `domain` to identify the company by website domain. + */ type: 'domain'; } @@ -285,6 +287,9 @@ export namespace NewsSearchParams { */ ticker: string; + /** + * Use `ticker` to identify a publicly traded company. + */ type: 'ticker'; /** @@ -375,6 +380,9 @@ export namespace NewsSearchParams { */ isin: string; + /** + * Use `isin` to identify the company by its securities identifier. + */ type: 'isin'; } } diff --git a/src/resources/parse.ts b/src/resources/parse.ts index cf7f74e7..19dc04e4 100644 --- a/src/resources/parse.ts +++ b/src/resources/parse.ts @@ -8,8 +8,7 @@ import { RequestOptions } from '../internal/request-options'; export class Parse extends APIResource { /** - * Converts raw text, source code, web/data, PDF, Microsoft Office, and image bytes - * into LLM-usable Markdown. + * Convert uploaded file bytes into Markdown and optional HTML. */ handle( body: Uploadable, @@ -55,8 +54,8 @@ export interface ParseHandleResponse { markdown: string; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -112,18 +111,18 @@ export interface ParseHandleResponse { | 'pnm'; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: ParseHandleResponse.KeyMetadata; } export namespace ParseHandleResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -227,11 +226,8 @@ export interface ParseHandleParams { includeLinks?: boolean; /** - * Query param: When true for PDF inputs, OCR the selected pages that have no - * usable text layer (scans), replacing each recovered page's text with the OCR - * result while pages with a real text layer keep it. pdf.start/pdf.end limit the - * inclusive page range. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. When false, no OCR runs. + * Query param: Read text from images and scanned PDF pages. PDF page ranges still + * apply. */ ocr?: boolean; @@ -247,8 +243,8 @@ export interface ParseHandleParams { shortenBase64Images?: boolean; /** - * Query param: Comma-separated tags for tracking request usage. Up to 20 tags, - * each 1-50 characters. + * Query param: Comma-separated labels for filtering usage, e.g. + * `production,team-alpha`. */ tags?: Array; @@ -258,11 +254,8 @@ export interface ParseHandleParams { useMainContentOnly?: boolean; /** - * Query param: Set to enabled to bypass shared caches and omit request and - * response content from retained usage logs. Asset uploads are skipped, so hosted - * image URLs are omitted. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * Query param: `enabled` turns on zero data retention. Returns 403 + * `ZDR_NOT_ENABLED` unless your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } diff --git a/src/resources/people.ts b/src/resources/people.ts index 9ebccb35..e20303b5 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -6,10 +6,8 @@ import { RequestOptions } from '../internal/request-options'; export class People extends APIResource { /** - * Finds and normalizes the best available person candidate from additive identity - * clues, then assigns an identity match score from 0 to 100. Available on all paid - * plans. Successful requests cost 20 credits. Disposable and free email addresses - * (like gmail.com, yahoo.com) will throw a 422 error. + * Find a person from identity clues and return their profile with a match score. + * Requires a paid plan; free or disposable email addresses return 422. * * @example * ```ts @@ -39,13 +37,13 @@ export interface PersonEnrichResponse { | PersonEnrichResponse.PersonEnrichmentNotFoundMatch; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: PersonEnrichResponse.KeyMetadata; @@ -265,11 +263,11 @@ export namespace PersonEnrichResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -281,95 +279,160 @@ export namespace PersonEnrichResponse { } export interface PersonEnrichParams { + /** + * Company context to help identify the person. Provide a name or domain. + */ company?: PersonEnrichParams.Company; + /** + * Education history to help distinguish people with similar names. + */ education?: Array; + /** + * Email address of the person to find. + */ email?: string; + /** + * Location context to help identify the person. Provide a city, region, or + * country. + */ location?: PersonEnrichParams.Location; + /** + * Person name. Without an email or person-profile URL, provide both first and last + * name plus company, education, or location. + */ name?: PersonEnrichParams.Name; + /** + * Public profile URLs for the person. A person-profile URL can identify the person + * without a name. + */ social_urls?: Array; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: PersonEnrichParams.TimeoutOpts; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace PersonEnrichParams { + /** + * Company context to help identify the person. Provide a name or domain. + */ export interface Company { + /** + * Website domain of a company associated with the person. + */ domain?: string; + /** + * Name of a company associated with the person. + */ name?: string; } export interface Education { + /** + * Degree or qualification earned. + */ degree?: string; + /** + * Subject or major studied. + */ field_of_study?: string; + /** + * Four-digit graduation year. + */ graduation_year?: number; + /** + * School or university, identified by name or domain. + */ institution?: Education.Institution; } export namespace Education { + /** + * School or university, identified by name or domain. + */ export interface Institution { + /** + * Website domain of the school or university. + */ domain?: string; + /** + * Name of the school or university. + */ name?: string; } } + /** + * Location context to help identify the person. Provide a city, region, or + * country. + */ export interface Location { + /** + * City associated with the person. + */ city?: string; + /** + * Country associated with the person. + */ country?: string; + /** + * State, province, or region associated with the person. + */ region?: string; } + /** + * Person name. Without an email or person-profile URL, provide both first and last + * name plus company, education, or location. + */ export interface Name { + /** + * First or given name. + */ first?: string; + /** + * Last or family name. + */ last?: string; } /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } diff --git a/src/resources/utility.ts b/src/resources/utility.ts index 683b587c..566199d9 100644 --- a/src/resources/utility.ts +++ b/src/resources/utility.ts @@ -6,16 +6,12 @@ import { RequestOptions } from '../internal/request-options'; export class Utility extends APIResource { /** - * Signal that you may fetch data soon to improve latency. The type field selects - * what to prefetch ('brand' queues a brand data fetch, 'styleguide' queues a - * styleguide extraction) and identifier carries exactly one lookup key: a domain, - * or an email whose domain is extracted and validated (free email providers and - * disposable email addresses are not allowed). + * Queue brand or styleguide data so a later lookup can return sooner. * * @example * ```ts * const response = await client.utility.prefetch({ - * identifier: { domain: 'xxx' }, + * identifier: { domain: 'stripe.com' }, * type: 'brand', * }); * ``` @@ -27,8 +23,8 @@ export class Utility extends APIResource { export interface UtilityPrefetchResponse { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -38,7 +34,7 @@ export interface UtilityPrefetchResponse { domain?: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: UtilityPrefetchResponse.KeyMetadata; @@ -48,7 +44,7 @@ export interface UtilityPrefetchResponse { message?: string; /** - * Status of the response, e.g., 'ok' + * Always `ok` on success. */ status?: string; @@ -60,11 +56,11 @@ export interface UtilityPrefetchResponse { export namespace UtilityPrefetchResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -84,20 +80,17 @@ export interface UtilityPrefetchParams { | UtilityPrefetchParams.UtilityPrefetchEmailIdentifier; /** - * What to prefetch: 'brand' warms the brand data cache, 'styleguide' warms the - * styleguide cache. + * Data to prefetch. */ type: 'brand' | 'styleguide'; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: UtilityPrefetchParams.TimeoutOpts; } @@ -108,7 +101,7 @@ export namespace UtilityPrefetchParams { */ export interface UtilityPrefetchDomainIdentifier { /** - * Domain name to prefetch data for + * Domain, e.g. `stripe.com`. */ domain: string; } @@ -126,19 +119,16 @@ export namespace UtilityPrefetchParams { } /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. This endpoint supports "fail": return 408 - * REQUEST_TIMEOUT without charging credits. + * Only "fail" is supported: return 408 at the deadline. */ behavior?: 'fail'; } diff --git a/src/resources/web.ts b/src/resources/web.ts index 5462aeb7..1a0de436 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -6,11 +6,8 @@ import { RequestOptions } from '../internal/request-options'; export class Web extends APIResource { /** - * Researches the live web and returns a sourced answer in your requested JSON - * shape. Select fast for a smaller research budget at 10 credits or ultra for - * deeper reasoning at 100 credits. Defaults to ultra. Fast research is limited to - * 30 seconds and ultra to 50 seconds; timeoutOpts.milliseconds can shorten either - * deadline. + * Research the web and return a sourced answer in your JSON shape. Choose `fast` + * for a short task or `ultra` for deeper research. * * @example * ```ts @@ -47,8 +44,7 @@ export class Web extends APIResource { } /** - * Extract a comprehensive design system from a website including colors, - * typography, spacing, shadows, and UI components. + * Extract colors, typography, spacing, and component styles from a website. * * @example * ```ts @@ -63,19 +59,13 @@ export class Web extends APIResource { } /** - * Discovers URLs using the same sitemap crawl, filters, and limits as - * /web/scrape/sitemap. Each URL includes its available title, description, - * keywords, and language. URLs without stored enrichment are returned immediately - * with only the URL and queued for background HTML scraping, so later requests can - * include their metadata. Responses are never cached as a whole; every request - * reads the current per-URL enrichment. Zero data retention and credential-bearing - * discovery requests return URLs without reading or storing shared enrichment or - * queuing background scrapes. Costs 1 credit, or 2 credits with search. + * Discover a site's URLs, with page titles, descriptions, keywords, and language + * when available. Metadata can be missing on newly discovered URLs. * * @example * ```ts * const response = await client.web.mapUrls({ - * domain: 'xxx', + * domain: 'stripe.com', * }); * ``` */ @@ -84,31 +74,13 @@ export class Web extends APIResource { } /** - * Reuse cached outputs independently and capture missing formats in one page - * visit. Each cache key includes only the settings that affect that output. HTML - * is shared with Markdown, parsed fields, product data, highlights, and JSON - * extraction. Cached outputs can come from different visits within maxAgeMs; use 0 - * for a fresh capture. HTML-only requests use the existing fast acquisition path. - * Highlights return Markdown excerpts most relevant to highlightsParams.query. - * Requests with at least one successful output cost one base credit, including - * cache hits, or two with browser actions. All-failed responses are unbilled - * except missing pages, which retain the base price and the one-credit product - * charge when product was requested. Highlights add 3 credits when passages are - * returned. JSON extraction runs an LLM over nonempty page Markdown and adds four - * credits only when its result is returned successfully. PDF OCR adds one credit - * per recovered page on fresh extraction. Product adds one credit when its - * successful result is returned, plus six if that result used the specialized - * model. Original response bytes and screenshots are limited to 20 MiB each, - * screenshots to 40 megapixels, and the combined response to 60 MiB. An oversized - * output has success: false and data: null. If the combined response exceeds its - * limit, the largest outputs are marked failed until the remaining outputs fit. - * Valid captured pieces may still be cached when omitted to meet the response size - * limit. + * Returns the outputs you enable in `formats` from one visit to a URL. Each output + * reports its own `success`, so a failed output does not fail the request. * * @example * ```ts * const response = await client.web.scrape({ - * formats: { html: true }, + * formats: { markdown: true }, * url: 'https://example.com', * }); * ``` @@ -133,11 +105,14 @@ export class Web extends APIResource { } /** - * Search the web and optionally scrape each result to Markdown in one round-trip. + * Search the web and optionally return page content with each result. * * @example * ```ts - * const response = await client.web.search({ query: 'x' }); + * const response = await client.web.search({ + * query: 'Stripe API authentication', + * numResults: 10, + * }); * ``` */ search(body: WebSearchParams, options?: RequestOptions): APIPromise { @@ -145,13 +120,14 @@ export class Web extends APIResource { } /** - * Performs a crawl starting from a given URL, extracts page content as Markdown, - * and returns results for all crawled pages. + * Crawl a website and return page content as Markdown. Use a batch for crawls + * beyond 500 pages. * * @example * ```ts * const response = await client.web.webCrawlMd({ * url: 'https://example.com', + * maxPages: 10, * }); * ``` */ @@ -173,7 +149,7 @@ export interface WebAnswersResponse { sources: Array; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebAnswersResponse.KeyMetadata; @@ -186,11 +162,11 @@ export interface WebAnswersResponse { export namespace WebAnswersResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -213,8 +189,8 @@ export interface WebExtractCompetitorsResponse { domain: string; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -229,7 +205,7 @@ export interface WebExtractCompetitorsResponse { target: WebExtractCompetitorsResponse.Target; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebExtractCompetitorsResponse.KeyMetadata; @@ -299,11 +275,11 @@ export namespace WebExtractCompetitorsResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -316,15 +292,13 @@ export namespace WebExtractCompetitorsResponse { export interface WebExtractStyleguideResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: WebExtractStyleguideResponse.CacheMetadata; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -339,21 +313,18 @@ export interface WebExtractStyleguideResponse { domain?: string; /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. + * `loaded`, or `still-loading` when capture ended before the page finished + * loading. */ finalDOMState?: 'loaded' | 'still-loading'; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebExtractStyleguideResponse.KeyMetadata; /** - * Status of the response, e.g., 'ok' + * Always `ok` on success. */ status?: string; @@ -365,9 +336,7 @@ export interface WebExtractStyleguideResponse { export namespace WebExtractStyleguideResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -383,11 +352,11 @@ export namespace WebExtractStyleguideResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -525,7 +494,7 @@ export namespace WebExtractStyleguideResponse { minHeight: string; /** - * Sampled minimum width of the button box (typically px) + * Minimum width (usually px). */ minWidth: string; @@ -586,7 +555,7 @@ export namespace WebExtractStyleguideResponse { minHeight: string; /** - * Sampled minimum width of the button box (typically px) + * Minimum width (usually px). */ minWidth: string; @@ -647,7 +616,7 @@ export namespace WebExtractStyleguideResponse { minHeight: string; /** - * Sampled minimum width of the button box (typically px) + * Minimum width (usually px). */ minWidth: string; @@ -790,7 +759,7 @@ export namespace WebExtractStyleguideResponse { fontFallbacks: Array; /** - * Primary face (first family in the computed stack) + * First font in the stack. */ fontFamily: string; @@ -810,7 +779,7 @@ export namespace WebExtractStyleguideResponse { fontFallbacks: Array; /** - * Primary face (first family in the computed stack) + * First font in the stack. */ fontFamily: string; @@ -830,7 +799,7 @@ export namespace WebExtractStyleguideResponse { fontFallbacks: Array; /** - * Primary face (first family in the computed stack) + * First font in the stack. */ fontFamily: string; @@ -850,7 +819,7 @@ export namespace WebExtractStyleguideResponse { fontFallbacks: Array; /** - * Primary face (first family in the computed stack) + * First font in the stack. */ fontFamily: string; @@ -871,7 +840,7 @@ export namespace WebExtractStyleguideResponse { fontFallbacks: Array; /** - * Primary face (first family in the computed stack) + * First font in the stack. */ fontFamily: string; @@ -891,8 +860,8 @@ export interface WebMapURLsResponse { domain: string; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -901,7 +870,7 @@ export interface WebMapURLsResponse { urls: Array; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebMapURLsResponse.KeyMetadata; @@ -922,11 +891,11 @@ export namespace WebMapURLsResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -939,22 +908,18 @@ export namespace WebMapURLsResponse { export interface WebScrapeResponse { /** - * Original HTTP response body. Waiting, actions, and content filters never change - * it. + * The original HTTP response body, unchanged by waits, actions, and filters. */ bytes: WebScrapeResponse.Bytes; /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: WebScrapeResponse.CacheMetadata; /** - * Relevant Markdown excerpts for your question or topic, in page order. Headings - * in square brackets supply necessary context; ellipses mark omitted portions. - * Empty when the page has no text. + * Relevant Markdown excerpts in page order. `[Heading]` adds context; `…` marks + * omitted text. */ highlights: WebScrapeResponse.Highlights; @@ -964,12 +929,12 @@ export interface WebScrapeResponse { html: WebScrapeResponse.HTML; /** - * Images after content filters. Empty when none are found. + * Images after content filters. `[]` when none are found. */ images: WebScrapeResponse.Images; /** - * Page data extracted using your schema. + * Object matching `jsonParams.schema`. */ json: WebScrapeResponse.Json; @@ -979,12 +944,13 @@ export interface WebScrapeResponse { markdown: WebScrapeResponse.Markdown; /** - * Page details, when available. + * Page metadata. Fields are omitted when not found. */ metadata: WebScrapeResponse.Metadata; /** - * Fields produced by parseParams.rules, after shared content filters. + * Fields from `parseParams.rules`, after content filters. Unmatched fields are + * `null` (`[]` for lists). */ parsed: WebScrapeResponse.Parsed; @@ -994,13 +960,13 @@ export interface WebScrapeResponse { product: WebScrapeResponse.Product; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * An image data URL. Use directly as an image src. + * Screenshot as a base64 image data URL. */ screenshot: WebScrapeResponse.Screenshot; @@ -1010,24 +976,20 @@ export interface WebScrapeResponse { url: string; /** - * Present when at least one requested output succeeds while another fails, or when - * successful outputs come from a page that is still loading or images returned - * before processing finished. Absent when every requested output fails. Check each - * output's success field for its result. Valid captured pieces may be cached - * independently; failed retrievals and incomplete captures are not cached. + * True when at least one requested output succeeds but the response has failed or + * incomplete outputs. Absent when all requested outputs fail. */ isPartial?: true; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebScrapeResponse.KeyMetadata; } export namespace WebScrapeResponse { /** - * Original HTTP response body. Waiting, actions, and content filters never change - * it. + * The original HTTP response body, unchanged by waits, actions, and filters. */ export interface Bytes { data: Bytes.Data | null; @@ -1035,7 +997,7 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } @@ -1043,8 +1005,7 @@ export namespace WebScrapeResponse { export namespace Bytes { export interface Data { /** - * Original response body as base64, after HTTP decompression. Maximum decoded - * size: 20 MiB. + * Body as base64, after HTTP decompression. Up to 20 MiB decoded. */ base64: string; @@ -1053,9 +1014,7 @@ export namespace WebScrapeResponse { } /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -1071,9 +1030,8 @@ export namespace WebScrapeResponse { } /** - * Relevant Markdown excerpts for your question or topic, in page order. Headings - * in square brackets supply necessary context; ellipses mark omitted portions. - * Empty when the page has no text. + * Relevant Markdown excerpts in page order. `[Heading]` adds context; `…` marks + * omitted text. */ export interface Highlights { data: Array | null; @@ -1081,7 +1039,7 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } @@ -1095,13 +1053,13 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } /** - * Images after content filters. Empty when none are found. + * Images after content filters. `[]` when none are found. */ export interface Images { data: Array | null; @@ -1109,7 +1067,7 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } @@ -1137,8 +1095,8 @@ export namespace WebScrapeResponse { | 'other'; /** - * Hosted copy when file enrichment is requested and zdr is disabled. Valid for 24 - * hours from the original capture. + * Hosted image URL, valid for 24 hours after capture. Requires `file` enrichment + * and ZDR disabled. */ fileUrl?: string; @@ -1149,7 +1107,7 @@ export namespace WebScrapeResponse { } /** - * Page data extracted using your schema. + * Object matching `jsonParams.schema`. */ export interface Json { data: { [key: string]: unknown } | null; @@ -1157,7 +1115,7 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } @@ -1171,13 +1129,13 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } /** - * Page details, when available. + * Page metadata. Fields are omitted when not found. */ export interface Metadata { /** @@ -1211,8 +1169,7 @@ export namespace WebScrapeResponse { favicon?: string; /** - * Page headings (h1–h6) in document order, extracted from the unfiltered document. - * Capped at the first 500 headings. Omitted when the page has none. + * Up to 500 h1–h6 headings in document order, before content filtering. */ headings?: Array; @@ -1309,7 +1266,8 @@ export namespace WebScrapeResponse { } /** - * Fields produced by parseParams.rules, after shared content filters. + * Fields from `parseParams.rules`, after content filters. Unmatched fields are + * `null` (`[]` for lists). */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1317,7 +1275,7 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } @@ -1331,7 +1289,7 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } @@ -1470,7 +1428,7 @@ export namespace WebScrapeResponse { } /** - * An image data URL. Use directly as an image src. + * Screenshot as a base64 image data URL. */ export interface Screenshot { data: string | null; @@ -1478,17 +1436,17 @@ export namespace WebScrapeResponse { requested: boolean; /** - * True when retrieved, false when retrieval failed, and null when not requested. + * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -1501,15 +1459,13 @@ export namespace WebScrapeResponse { export interface WebScreenshotResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: WebScreenshotResponse.CacheMetadata; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; @@ -1524,11 +1480,8 @@ export interface WebScreenshotResponse { domain?: string; /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. + * `loaded`, or `still-loading` when capture ended before the page finished + * loading. */ finalDOMState?: 'loaded' | 'still-loading'; @@ -1538,7 +1491,7 @@ export interface WebScreenshotResponse { height?: number; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebScreenshotResponse.KeyMetadata; @@ -1554,7 +1507,7 @@ export interface WebScreenshotResponse { screenshotType?: 'viewport' | 'fullPage'; /** - * Status of the response, e.g., 'ok' + * Always `ok` on success. */ status?: string; @@ -1566,9 +1519,7 @@ export interface WebScreenshotResponse { export namespace WebScreenshotResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -1584,11 +1535,11 @@ export namespace WebScreenshotResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -1601,9 +1552,7 @@ export namespace WebScreenshotResponse { export interface WebSearchResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: WebSearchResponse.CacheMetadata; @@ -1613,15 +1562,15 @@ export interface WebSearchResponse { query: string; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; results: Array; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebSearchResponse.KeyMetadata; @@ -1635,9 +1584,7 @@ export interface WebSearchResponse { export namespace WebSearchResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -1697,22 +1644,19 @@ export namespace WebSearchResponse { markdown: string | null; /** - * How complete the returned content is. `loaded` means the page finished the waits - * the request asked for. `still-loading` only occurs with - * timeoutOpts.behavior=return-partial: the timeoutOpts.milliseconds deadline was - * reached first, so the content reflects the DOM at that moment and late-rendering - * parts may be missing. Partial results are billed at the base request cost. + * `loaded`, or `still-loading` when capture ended before the page finished + * loading. */ finalDOMState?: 'loaded' | 'still-loading'; } } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -1725,24 +1669,22 @@ export namespace WebSearchResponse { export interface WebWebCrawlMdResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ cache_metadata: WebWebCrawlMdResponse.CacheMetadata; metadata: WebWebCrawlMdResponse.Metadata; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; results: Array; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: WebWebCrawlMdResponse.KeyMetadata; @@ -1756,9 +1698,7 @@ export interface WebWebCrawlMdResponse { export namespace WebWebCrawlMdResponse { /** - * Cache outcome for this response. Composite responses are hits only when every - * cache-controlled fetch contributing to the output was a hit; age_ms is the - * oldest contributing hit. + * Whether this response came from cache. */ export interface CacheMetadata { /** @@ -1973,11 +1913,11 @@ export namespace WebWebCrawlMdResponse { } /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -1990,66 +1930,51 @@ export namespace WebWebCrawlMdResponse { export interface WebAnswersParams { /** - * What to research and answer, in plain language. Naming a domain in the task (for - * example "pricing on context.dev") makes the agent read that site before it - * searches. + * Research task. Name a domain to have it read before searching. */ task: string; /** - * An example object with placeholder values (for example {"pricing_page_url": "", - * "plans": [{"name": "", "price": 0}]}). Object keys and value types are - * preserved; unknown values may be null. Empty arrays accept any JSON items. - * Defaults to {"result": ""}. Maximum 8 levels, 500 values, and 16000 characters. + * Example answer object, not JSON Schema. Up to 8 levels, 500 values, and 16000 + * characters; unknowns may be null. */ json_format?: { [key: string]: unknown }; /** - * Research level: fast uses a smaller model and research budget for 10 credits; - * ultra uses deeper reasoning and research for 100 credits. Defaults to ultra. - * Only successful requests consume credits. + * `fast` for short tasks; `ultra` for deeper research (default). */ mode?: 'fast' | 'ultra'; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: WebAnswersParams.TimeoutOpts; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace WebAnswersParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -2068,45 +1993,35 @@ export interface WebExtractCompetitorsParams { numCompetitors?: number; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: WebExtractCompetitorsParams.TimeoutOpts; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace WebExtractCompetitorsParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -2120,10 +2035,7 @@ export interface WebExtractStyleguideParams { colorScheme?: 'light' | 'dark'; /** - * A specific URL to fetch the styleguide from directly, bypassing domain - * resolution (e.g., 'https://example.com/design-system'). When provided, the - * styleguide is extracted from this exact URL. You must provide either 'domain' or - * 'directUrl', but not both. + * Exact URL to inspect. Provide either `domain` or `directUrl`, not both. */ directUrl?: string; @@ -2135,54 +2047,41 @@ export interface WebExtractStyleguideParams { domain?: string; /** - * Maximum age in milliseconds for cached brand data before the API performs a hard - * refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard - * refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) - * are clamped to 1 year. + * Maximum age of cached brand data in ms. Defaults to 3 months; clamped to 0–1 + * year. `0` refreshes. */ maxAgeMs?: number | null; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: WebExtractStyleguideParams.TimeoutOpts; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace WebExtractStyleguideParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. "return-partial" requires at least 5000 ms. */ behavior?: 'fail' | 'return-partial'; } @@ -2190,52 +2089,43 @@ export namespace WebExtractStyleguideParams { export interface WebMapURLsParams { /** - * Domain to build a sitemap for + * Domain to map, e.g. `stripe.com`. */ domain: string; /** - * Optional outbound HTTP headers forwarded only to the target URL, sent as - * deep-object query params such as headers[X-Custom]=value. When provided, caching - * is bypassed: the result is neither read from nor written to cache. + * HTTP headers for the target origin. Non-empty headers bypass caching. */ headers?: { [key: string]: string }; /** - * When true, discover and include public pages and sitemaps on subdomains of the - * requested domain. Defaults to false. + * Include URLs on subdomains. */ includeSubdomains?: boolean; /** - * Maximum number of links to return from the sitemap crawl. Defaults to 10,000. - * Minimum is 1, maximum is 100,000. + * Maximum number of URLs to return. */ maxLinks?: number; /** - * Optional search phrase. When provided, the crawled sitemap is filtered to the - * pages whose URLs are about that phrase, most relevant first, and the request - * costs 2 credits instead of 1. + * Filter URLs by a topic or phrase, most relevant first. */ search?: string; /** - * Optional explicit sitemap URL. When provided, exactly this sitemap is crawled - * instead of discovering the domain's sitemaps. + * Fetch this sitemap instead of discovering sitemaps. Must belong to the domain or + * a subdomain. */ sitemapUrl?: string; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: WebMapURLsParams.TimeoutOpts; @@ -2246,32 +2136,25 @@ export interface WebMapURLsParams { urlRegex?: string; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace WebMapURLsParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -2279,17 +2162,17 @@ export namespace WebMapURLsParams { export interface WebScrapeParams { /** - * Outputs to return. Enable at least one; omitted formats are false. + * Outputs to return. Set at least one to `true`. */ formats: WebScrapeParams.Formats; /** - * The URL to scrape. + * Public HTTP or HTTPS URL to scrape. */ url: string; /** - * Highlight options. Requires formats.highlights: true. + * Required when `formats.highlights` is `true`. */ highlightsParams?: WebScrapeParams.HighlightsParams; @@ -2304,15 +2187,13 @@ export interface WebScrapeParams { jsonParams?: WebScrapeParams.JsonParams; /** - * Markdown options. Requires formats.markdown: true. + * Markdown options. Requires `formats.markdown`. */ markdownParams?: WebScrapeParams.MarkdownParams; /** - * Maximum age of each cached output. Defaults to 1 day; 0 fetches fresh and - * updates the requested outputs. Compatible outputs are shared with the individual - * scrape endpoints. Image results with hosted files refresh after 23 hours; other - * outputs retain their own freshness. + * Maximum age of a cached output, in milliseconds. `0` fetches fresh. Defaults to + * 1 day. */ maxAgeMs?: number; @@ -2332,8 +2213,7 @@ export interface WebScrapeParams { screenshotParams?: WebScrapeParams.ScreenshotParams; /** - * Shared browser and content settings. Content filters leave screenshots and - * original bytes unchanged. + * Browser and content settings shared by all outputs. */ sharedParams?: WebScrapeParams.SharedParams; @@ -2343,30 +2223,20 @@ export interface WebScrapeParams { tags?: Array; /** - * Total deadline, including navigation, actions, waiting, and all outputs. - * Defaults to 60000 milliseconds with behavior fail. Individual outputs have - * internal deadlines that reserve time to return completed outputs; timed-out - * outputs have success: false and data: null under either behavior. The overall - * request deadline remains enforced: fail returns an error if that deadline is - * reached. Use return-partial to allow the current page state and available - * outputs when the page is still loading. Partial responses set isPartial. Failed - * retrievals and incomplete captures are not cached; valid captured pieces may be - * cached independently. Fixed waits must fit before a response reserve of up to - * 5000 milliseconds (at most one quarter of the timeout) when using - * return-partial. + * Deadline for the whole request. Defaults to 60000 ms with `fail`. Fixed waits + * must end before it. */ timeoutOpts?: WebScrapeParams.TimeoutOpts; /** - * Zero data retention. Bypasses caches and uploads; excludes request/response - * content and tags from logs. Must be enabled for your organization. + * `enabled` turns on zero data retention. Your organization must have ZDR enabled. */ zdr?: 'enabled' | 'disabled'; } export namespace WebScrapeParams { /** - * Outputs to return. Enable at least one; omitted formats are false. + * Outputs to return. Set at least one to `true`. */ export interface Formats { /** @@ -2375,9 +2245,7 @@ export namespace WebScrapeParams { bytes?: boolean; /** - * Relevant Markdown excerpts for your question or topic, preserving code, lists, - * and tables, with headings included when needed for context. Adds 3 credits when - * passages are returned. + * Markdown excerpts relevant to `highlightsParams.query`. */ highlights?: boolean; @@ -2392,8 +2260,7 @@ export namespace WebScrapeParams { images?: boolean; /** - * Page data extracted using your schema. Adds 4 credits when extraction succeeds - * and its result is returned. + * An object matching `jsonParams.schema`, extracted from the page. */ json?: boolean; @@ -2403,24 +2270,23 @@ export namespace WebScrapeParams { markdown?: boolean; /** - * Fields selected by parseParams.rules. + * Fields extracted with `parseParams.rules`, returned as `parsed`. */ parse?: boolean; /** - * Product details such as name, price, and availability. Adds 1 credit when its - * successful result is returned or the target page is missing. + * Product details such as name, price, and availability. */ product?: boolean; /** - * An inline image of the page. + * A screenshot of the page. */ screenshot?: boolean; } /** - * Highlight options. Requires formats.highlights: true. + * Required when `formats.highlights` is `true`. */ export interface HighlightsParams { /** @@ -2429,7 +2295,7 @@ export namespace WebScrapeParams { query: string; /** - * Maximum combined length of the returned passages, in characters. + * Maximum combined length of returned passages. */ maxCharacters?: number; } @@ -2439,14 +2305,12 @@ export namespace WebScrapeParams { */ export interface ImageParams { /** - * For visual duplicates, keep the largest image. + * Set `visual` to drop visual duplicates, keeping the largest copy. */ dedupe?: 'none' | 'visual'; /** - * Add dimensions, a visual category, or a hosted file URL. Each image has a - * maximum processing time of 30000 milliseconds, bounded by the remaining request - * deadline. + * Extra data per image: `dimensions`, `classification`, or a hosted `file` URL. */ enrich?: Array<'dimensions' | 'classification' | 'file'>; } @@ -2456,31 +2320,34 @@ export namespace WebScrapeParams { */ export interface JsonParams { /** - * JSON Schema for the returned object. Must describe a top-level object; at most - * 50 KB serialized. Optional fields the page does not state are omitted, or null - * when their type allows null, while required non-nullable fields always receive a - * best-effort value, so prefer nullable or optional fields for data a page may - * omit. Zod users can pass the output of z.toJSONSchema(). + * JSON Schema for a top-level object, up to 50 KB. Use optional or nullable fields + * for missing facts. */ schema: { [key: string]: unknown }; /** - * Optional guidance on which facts to prioritize or how to interpret schema - * fields. + * Extra guidance, such as which facts to prefer or how to read a field. */ instructions?: string; } /** - * Markdown options. Requires formats.markdown: true. + * Markdown options. Requires `formats.markdown`. */ export interface MarkdownParams { + /** + * Include images in the Markdown using image syntax with URLs and alt text. + */ includeImages?: boolean; + /** + * Keep link URLs in the Markdown. Set false to return link text without URLs. + */ includeLinks?: boolean; /** - * Base64 images use placeholders by default. Requires includeImages: true. + * How base64 images appear: `placeholder` (default) or `preserve`. Requires + * `includeImages`. */ inlineImages?: 'placeholder' | 'preserve'; } @@ -2490,18 +2357,28 @@ export namespace WebScrapeParams { */ export interface ParseParams { /** - * Map field names to CSS selectors or rules. Missing items return null; missing - * lists return []. + * Field names mapped to CSS selectors (`h1`, `a@href`) or rule objects. Max 100 + * fields, 5 levels. */ rules: { [key: string]: string | ParseParams.UnionMember1 }; } export namespace ParseParams { export interface UnionMember1 { + /** + * CSS selector to match within the current page or parent rule. + */ selector: string; + /** + * Return text, HTML, an attribute such as `@href`, or nested field rules. Defaults + * to text. + */ output?: 'text' | 'html' | string | unknown; + /** + * Return the first match with `item` or all matches with `list`. + */ type?: 'item' | 'list'; } } @@ -2511,11 +2388,7 @@ export namespace WebScrapeParams { */ export interface ProductParams { /** - * Extract the product with a specialized model when the page has no structured - * product data. Adds six credits when the model verdict is returned successfully. - * If the fallback fails, the product output has success: false and data: null with - * no fallback charge; other outputs remain available. Request deadlines and client - * disconnects still apply. + * Use an AI model when the page has no structured product data. */ useAIFallback?: boolean; } @@ -2525,17 +2398,21 @@ export namespace WebScrapeParams { */ export interface ScreenshotParams { /** - * Viewport, full page, one visible element, or a rectangle. Maximum 40 megapixels. + * What to capture: `viewport`, `fullPage`, one element, or a rectangle. Max 40 + * megapixels. */ area?: 'viewport' | 'fullPage' | ScreenshotParams.Element | ScreenshotParams.Rectangle; + /** + * Image format for the screenshot. + */ format?: 'png' | 'jpeg' | 'webp'; } export namespace ScreenshotParams { export interface Element { /** - * Must match one visible element. + * CSS selector matching exactly one visible element. */ selector: string; } @@ -2544,66 +2421,76 @@ export namespace WebScrapeParams { * Pixels from the document origin. */ export interface Rectangle { + /** + * Height of the capture in pixels. + */ height: number; + /** + * Width of the capture in pixels. + */ width: number; + /** + * Left edge of the capture, in pixels from the document origin. + */ x: number; + /** + * Top edge of the capture, in pixels from the document origin. + */ y: number; } } /** - * Shared browser and content settings. Content filters leave screenshots and - * original bytes unchanged. + * Browser and content settings shared by all outputs. */ export interface SharedParams { /** - * Run in order before capture. A failed action fails the request. Bypasses - * caching. + * Browser steps run in order before capture. Requires a paid plan. Skips the + * cache. */ actions?: Array; /** - * Supported two-letter country code, case-insensitive. Applies to every output, - * including image downloads. + * Proxy country as a two-letter code, such as `US`. Case-insensitive. */ country?: string; /** - * Dismiss cookie banners by accepting cookies before actions. + * Accept cookie banners before actions and capture. */ dismissCookies?: boolean; /** - * Dismiss other popups before actions. + * Close other popups before actions and capture. */ dismissPopups?: boolean; /** - * Remove matching content. Exclusions win. + * Remove elements matching these CSS selectors. Overrides `includeSelectors`. */ excludeSelectors?: Array; /** - * Headers for the target origin. Requests with custom headers bypass caching. + * HTTP headers to send to the target site. Requests with headers skip the cache. */ headers?: { [key: string]: string }; /** - * Include iframe content in extraction. Screenshots show visible frames - * regardless. + * Include iframe content in HTML and text outputs. Screenshots always show visible + * frames. */ includeFrames?: boolean; /** - * Keep matching content after mainContentOnly. + * Keep only elements matching these CSS selectors. */ includeSelectors?: Array; /** - * Keep only main content in HTML, Markdown, images, and parsed fields. + * Keep only the main content. Doesn't affect `screenshot`, `bytes`, or `product`. */ mainContentOnly?: boolean; @@ -2613,42 +2500,61 @@ export namespace WebScrapeParams { parsers?: SharedParams.Parsers; /** - * Settle animations before capture. Defaults to true with screenshots, otherwise - * false. + * Wait for CSS animations to finish before capture. Defaults to `true` when + * `screenshot` is requested. */ settleAnimations?: boolean; /** - * Override the browser color scheme. + * Emulate a light or dark color scheme. */ theme?: 'light' | 'dark'; /** - * Browser dimensions in pixels. + * Browser size in pixels. Omit for 1920 × 1080. When provided, missing dimensions + * default to 1440 × 900. */ viewport?: SharedParams.Viewport; /** - * After actions, wait this many milliseconds or until a CSS selector is visible. - * Defaults to 500 ms, or 2000 ms with frames or an XML URL. Set 0 to skip. + * Milliseconds, or a CSS selector to wait for, after actions. Defaults to 500 + * (2000 with frames or XML). */ waitFor?: number | string; } export namespace SharedParams { export interface Perform { + /** + * One browser instruction, such as clicking a button or entering text. + */ action: string; + /** + * Use `perform` for a plain-language browser instruction. + */ type: 'perform'; } export interface Scroll { + /** + * Use `scroll` to move through the page or a container. + */ type: 'scroll'; + /** + * Distance per scroll: pixels, one `viewport`, or `max` to reach the end. + */ amount?: number | 'viewport' | 'max'; + /** + * Direction to scroll. + */ direction?: 'down' | 'up' | 'left' | 'right'; + /** + * Maximum number of scroll steps for this action. + */ maxScrolls?: number; /** @@ -2658,14 +2564,26 @@ export namespace WebScrapeParams { } export interface Wait { + /** + * Time to pause in milliseconds before the next action. + */ milliseconds: number; + /** + * Use `wait` to pause for a fixed duration. + */ type: 'wait'; } export interface WaitFor { + /** + * CSS selector to wait for before continuing. + */ selector: string; + /** + * Use `waitFor` to wait for a matching element. + */ type: 'waitFor'; } @@ -2674,23 +2592,23 @@ export namespace WebScrapeParams { */ export interface Parsers { /** - * PDF text options for HTML, Markdown, and parsed fields. + * PDF page range and OCR. */ pdf?: Parsers.Pdf; } export namespace Parsers { /** - * PDF text options for HTML, Markdown, and parsed fields. + * PDF page range and OCR. */ export interface Pdf { /** - * Last page to parse. Must be at least startPage. + * Last page to parse. Must be at least `startPage`. */ endPage?: number; /** - * Read text from scanned pages. + * Set `auto` to read scanned pages with OCR. */ ocr?: 'off' | 'auto'; @@ -2702,40 +2620,35 @@ export namespace WebScrapeParams { } /** - * Browser dimensions in pixels. + * Browser size in pixels. Omit for 1920 × 1080. When provided, missing dimensions + * default to 1440 × 900. */ export interface Viewport { + /** + * Browser viewport height in pixels. + */ height?: number; + /** + * Browser viewport width in pixels. + */ width?: number; } } /** - * Total deadline, including navigation, actions, waiting, and all outputs. - * Defaults to 60000 milliseconds with behavior fail. Individual outputs have - * internal deadlines that reserve time to return completed outputs; timed-out - * outputs have success: false and data: null under either behavior. The overall - * request deadline remains enforced: fail returns an error if that deadline is - * reached. Use return-partial to allow the current page state and available - * outputs when the page is still loading. Partial responses set isPartial. Failed - * retrievals and incomplete captures are not cached; valid captured pieces may be - * cached independently. Fixed waits must fit before a response reserve of up to - * 5000 milliseconds (at most one quarter of the timeout) when using - * return-partial. + * Deadline for the whole request. Defaults to 60000 ms with `fail`. Fixed waits + * must end before it. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. "return-partial" requires at least 5000 ms. */ behavior?: 'fail' | 'return-partial'; } @@ -2758,8 +2671,7 @@ export interface WebScreenshotParams { colorScheme?: 'light' | 'dark'; /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). + * Fetch from this country (ISO 3166-1 alpha-2). */ country?: | 'ad' @@ -3033,15 +2945,12 @@ export interface WebScreenshotParams { scrollOffset?: number | null; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: WebScreenshotParams.TimeoutOpts; @@ -3060,33 +2969,25 @@ export interface WebScreenshotParams { waitForMs?: number | null; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace WebScreenshotParams { /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. "return-partial" requires at least 5000 ms. */ behavior?: 'fail' | 'return-partial'; } @@ -3387,28 +3288,23 @@ export interface WebSearchParams { numResults?: number; /** - * Expand the query into multiple parallel variants for broader recall. + * Currently has no effect. */ queryFanout?: boolean; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: WebSearchParams.TimeoutOpts; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Asset uploads are skipped, so hosted image URLs are - * omitted. Requires zero data retention to be enabled for your organization - * (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. - * Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } @@ -3455,9 +3351,7 @@ export namespace WebSearchParams { shortenBase64Images?: boolean; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: MarkdownOptions.TimeoutOpts; @@ -3496,43 +3390,34 @@ export namespace WebSearchParams { } /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. "return-partial" requires milliseconds of at - * least 5000. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. "return-partial" requires at least 5000 ms. */ behavior?: 'fail' | 'return-partial'; } } /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } @@ -3540,13 +3425,12 @@ export namespace WebSearchParams { export interface WebWebCrawlMdParams { /** - * The starting URL for the crawl (must include http:// or https:// protocol) + * Start URL, including `http://` or `https://`. */ url: string; /** - * Fetch the target page through a residential proxy in this country (ISO 3166-1 - * alpha-2). + * Fetch from this country (ISO 3166-1 alpha-2). */ country?: | 'ad' @@ -3755,9 +3639,7 @@ export interface WebWebCrawlMdParams { | 'zw'; /** - * CSS selectors to remove before each crawled page is converted to Markdown. - * Applied after includeSelectors. Exclusion takes precedence: an element matching - * both is removed. Examples: "nav", "footer", ".ad-banner", "[aria-hidden=true]". + * Remove matching elements after inclusions. Exclusions take precedence. */ excludeSelectors?: Array; @@ -3785,17 +3667,12 @@ export interface WebWebCrawlMdParams { includeLinks?: boolean; /** - * CSS selectors. When provided, only matching HTML subtrees (and their - * descendants) are kept before each crawled page is converted to Markdown. When - * omitted, the entire document is kept. Examples: "article.main", "#content", - * "[role=main]". + * Keep matching HTML subtrees before converting each page to Markdown. */ includeSelectors?: Array; /** - * Return a cached result if a prior scrape for the same parameters exists and is - * younger than this many milliseconds. Defaults to 1 day (86400000 ms) when - * omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh. + * Maximum cache age in milliseconds. Defaults to 1 day; `0` fetches fresh. */ maxAgeMs?: number; @@ -3805,20 +3682,18 @@ export interface WebWebCrawlMdParams { maxDepth?: number; /** - * Maximum number of pages to crawl. Hard cap: 500. + * Maximum pages to crawl. */ maxPages?: number; /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ pdf?: WebWebCrawlMdParams.Pdf; /** - * When true, waits briefly for CSS and transition animations to settle before - * extracting each crawled page. Defaults to false. This adds a bit of latency in - * exchange for more stable output on animated pages. + * Wait briefly for CSS animations and transitions to settle before reading each + * page. */ settleAnimations?: boolean; @@ -3828,22 +3703,18 @@ export interface WebWebCrawlMdParams { shortenBase64Images?: boolean; /** - * Soft time budget for the crawl in milliseconds. After each scrape, the crawler - * checks the elapsed time and, if exceeded, returns the pages collected so far - * instead of continuing. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 - * (80s). + * Soft crawl deadline in milliseconds. Returns pages collected before the next + * deadline check. */ stopAfterMs?: number; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ timeoutOpts?: WebWebCrawlMdParams.TimeoutOpts; @@ -3867,18 +3738,15 @@ export interface WebWebCrawlMdParams { waitForMs?: number; /** - * Set to enabled to bypass shared caches and omit request and response content - * from retained usage logs. Requires zero data retention to be enabled for your - * organization (contact support@context.dev), otherwise the request fails with - * ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true. + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } export namespace WebWebCrawlMdParams { /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ export interface Pdf { /** @@ -3888,10 +3756,7 @@ export namespace WebWebCrawlMdParams { end?: number; /** - * When true, OCR the selected PDF pages that have no usable text layer (scans), - * replacing each recovered page's text with the OCR result while pages with a real - * text layer keep it. Billed at 1 credit per page OCR actually recovered, on top - * of the base request cost. + * Read scanned PDF pages with OCR; preserve pages that already contain text. */ ocr?: boolean; @@ -3908,21 +3773,17 @@ export namespace WebWebCrawlMdParams { } /** - * Optional request deadline and behavior on timeout. For GET requests, use - * timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded - * timeoutOpts object. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** - * Request deadline in milliseconds. Maximum: 300000 (5 minutes). + * Deadline in milliseconds. */ milliseconds: number; /** - * What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging - * credits. "return-partial" returns usable results collected so far; if none are - * available, the request still fails without charging credits. Partial results are - * not cached as complete results. + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. */ behavior?: 'fail' | 'return-partial'; } diff --git a/src/resources/webhooks/deliveries.ts b/src/resources/webhooks/deliveries.ts index 89b1f012..f8ac98f4 100644 --- a/src/resources/webhooks/deliveries.ts +++ b/src/resources/webhooks/deliveries.ts @@ -8,11 +8,11 @@ import { RequestOptions } from '../../internal/request-options'; import { path } from '../../internal/utils/path'; /** - * Inspect and retry webhook deliveries. These endpoints cost no credits. + * Inspect and retry batch and monitor webhook deliveries. */ export class Deliveries extends APIResource { /** - * Get a webhook delivery, including its status and latest attempt. + * Retrieve a webhook delivery’s status and original payload. * * @example * ```ts @@ -30,7 +30,7 @@ export class Deliveries extends APIResource { } /** - * List your batch or monitor webhook deliveries, newest first. + * List batch and monitor webhook deliveries from the last 30 days. * * @example * ```ts @@ -46,7 +46,7 @@ export class Deliveries extends APIResource { } /** - * List delivery attempts, newest first. + * List a delivery’s attempts, newest first. * * @example * ```ts @@ -65,7 +65,8 @@ export class Deliveries extends APIResource { } /** - * Retry a webhook delivery within seven days of creation. + * Resend the original payload using the source’s current URL and secret. Available + * for 7 days after the event. * * @example * ```ts @@ -118,7 +119,7 @@ export interface Attempt { started_at: string; /** - * What started this attempt. + * `initial`, `automatic` (scheduled retry), or `manual` (Retry endpoint). */ trigger: 'initial' | 'automatic' | 'manual'; @@ -192,7 +193,7 @@ export interface Delivery { retry: WebhooksAPI.RetryConfig; /** - * Manual retry deadline, seven days after event creation. + * Last time you can retry manually (7 days after the event). */ retry_expires_at: string; @@ -202,7 +203,8 @@ export interface Delivery { source: Delivery.Batch | Delivery.Monitor; /** - * Current delivery status. + * `pending`, `delivering`, `retrying`, `delivered`, `failed`, or `cancelled` + * (source or its webhook was removed). */ status: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; @@ -235,7 +237,7 @@ export namespace Delivery { batch_id: string; /** - * Delivery source. + * Which deliveries to list: `batch` or `monitor`. */ type: 'batch'; } @@ -252,7 +254,7 @@ export namespace Delivery { run_id: string; /** - * Delivery source. + * Which deliveries to list: `batch` or `monitor`. */ type: 'monitor'; } @@ -290,7 +292,7 @@ export interface DeliverySummary { next_attempt_at: string | null; /** - * Manual retry deadline, seven days after event creation. + * Last time you can retry manually (7 days after the event). */ retry_expires_at: string; @@ -300,7 +302,8 @@ export interface DeliverySummary { source: DeliverySummary.Batch | DeliverySummary.Monitor; /** - * Current delivery status. + * `pending`, `delivering`, `retrying`, `delivered`, `failed`, or `cancelled` + * (source or its webhook was removed). */ status: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; @@ -333,7 +336,7 @@ export namespace DeliverySummary { batch_id: string; /** - * Delivery source. + * Which deliveries to list: `batch` or `monitor`. */ type: 'batch'; } @@ -350,7 +353,7 @@ export namespace DeliverySummary { run_id: string; /** - * Delivery source. + * Which deliveries to list: `batch` or `monitor`. */ type: 'monitor'; } @@ -358,24 +361,24 @@ export namespace DeliverySummary { export interface DeliveryRetrieveResponse extends Delivery { /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: DeliveryRetrieveResponse.KeyMetadata; } export namespace DeliveryRetrieveResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -403,24 +406,24 @@ export interface DeliveryListResponse { next_cursor: string | null; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: DeliveryListResponse.KeyMetadata; } export namespace DeliveryListResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -448,24 +451,24 @@ export interface DeliveryListAttemptsResponse { next_cursor: string | null; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: DeliveryListAttemptsResponse.KeyMetadata; } export namespace DeliveryListAttemptsResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -483,24 +486,24 @@ export interface DeliveryRetryResponse { id: string; /** - * Unique id of this API call, also sent in the X-Request-Id response header. Quote - * it when contacting support about a failed request. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ request_id: string; /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ key_metadata?: DeliveryRetryResponse.KeyMetadata; } export namespace DeliveryRetryResponse { /** - * Credit usage, included whenever a valid API key is provided. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** - * Credits used by this request. + * Credits charged for this request. */ credits_consumed: number; @@ -513,8 +516,7 @@ export namespace DeliveryRetryResponse { export interface DeliveryRetrieveParams { /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; } @@ -554,7 +556,7 @@ export declare namespace DeliveryListParams { status?: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; } @@ -596,7 +598,7 @@ export declare namespace DeliveryListParams { status?: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'failed' | 'cancelled'; /** - * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + * Labels for filtering usage in the dashboard. */ tags?: Array; } @@ -614,21 +616,19 @@ export interface DeliveryListAttemptsParams { limit?: number; /** - * Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 - * characters. + * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ tags?: Array; } export interface DeliveryRetryParams { /** - * Body param: Resend a delivery that already succeeded. + * Body param: Resend even if the delivery already succeeded. Defaults to false. */ force?: boolean; /** - * Body param: Optional tags for tracking usage. Up to 20 tags, each 1 to 50 - * characters. + * Body param: Labels for filtering usage in the dashboard. */ tags?: Array; diff --git a/tests/api-resources/news.test.ts b/tests/api-resources/news.test.ts index 0cc48978..7f486ac7 100644 --- a/tests/api-resources/news.test.ts +++ b/tests/api-resources/news.test.ts @@ -12,7 +12,7 @@ describe('resource news', () => { test.skip('search: only required params', async () => { const responsePromise = client.news.search({ searchBy: { - entity: { name: 'xx', type: 'name' }, + entity: { domain: 'stripe.com', type: 'domain' }, type: 'entity', }, }); @@ -29,7 +29,7 @@ describe('resource news', () => { test.skip('search: required and optional params', async () => { const response = await client.news.search({ searchBy: { - entity: { name: 'xx', type: 'name' }, + entity: { domain: 'stripe.com', type: 'domain' }, type: 'entity', }, cursor: 'cursor', diff --git a/tests/api-resources/utility.test.ts b/tests/api-resources/utility.test.ts index 120bfd69..28ff7a74 100644 --- a/tests/api-resources/utility.test.ts +++ b/tests/api-resources/utility.test.ts @@ -11,7 +11,7 @@ describe('resource utility', () => { // Mock server tests are disabled test.skip('prefetch: only required params', async () => { const responsePromise = client.utility.prefetch({ - identifier: { domain: 'xxx' }, + identifier: { domain: 'stripe.com' }, type: 'brand', }); const rawResponse = await responsePromise.asResponse(); @@ -26,7 +26,7 @@ describe('resource utility', () => { // Mock server tests are disabled test.skip('prefetch: required and optional params', async () => { const response = await client.utility.prefetch({ - identifier: { domain: 'xxx' }, + identifier: { domain: 'stripe.com' }, type: 'brand', tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 9e58d141..b6ace8ef 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -90,7 +90,7 @@ describe('resource web', () => { // Mock server tests are disabled test.skip('mapUrls: only required params', async () => { - const responsePromise = client.web.mapUrls({ domain: 'xxx' }); + const responsePromise = client.web.mapUrls({ domain: 'stripe.com' }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -103,7 +103,7 @@ describe('resource web', () => { // Mock server tests are disabled test.skip('mapUrls: required and optional params', async () => { const response = await client.web.mapUrls({ - domain: 'xxx', + domain: 'stripe.com', headers: { foo: 'J!' }, includeSubdomains: true, maxLinks: 1, @@ -245,7 +245,7 @@ describe('resource web', () => { // Mock server tests are disabled test.skip('search: only required params', async () => { - const responsePromise = client.web.search({ query: 'x' }); + const responsePromise = client.web.search({ query: 'Stripe API authentication' }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -258,7 +258,7 @@ describe('resource web', () => { // Mock server tests are disabled test.skip('search: required and optional params', async () => { const response = await client.web.search({ - query: 'x', + query: 'Stripe API authentication', country: 'af', excludeDomains: ['string'], freshness: 'last_24_hours', @@ -312,7 +312,7 @@ describe('resource web', () => { includeSelectors: ['string'], maxAgeMs: 0, maxDepth: 0, - maxPages: 1, + maxPages: 10, pdf: { end: 1, ocr: true, From 6016dfc6625cfcb648e803dd5896b5c04cedb29e Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 27 Sep 2026 09:04:06 +0000 Subject: [PATCH 095/232] seal --- src/resources/web.ts | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/resources/web.ts b/src/resources/web.ts index 1a0de436..46e1967c 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1118,6 +1118,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Cause of a failed JSON extraction, when available. + */ + error_code?: string; + + /** + * Explanation of the JSON extraction failure and possible next steps. + */ + message?: string; } /** From 51b131b2c12a8903abeca139a66c070c64040304 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 27 Sep 2026 09:04:06 +0000 Subject: [PATCH 096/232] fix(scrape): resolve extracted URLs from source references (#1333) Stainless-Generated-From: 6016dfc6625cfcb648e803dd5896b5c04cedb29e --- src/resources/web.ts | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/resources/web.ts b/src/resources/web.ts index 1a0de436..46e1967c 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1118,6 +1118,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Cause of a failed JSON extraction, when available. + */ + error_code?: string; + + /** + * Explanation of the JSON extraction failure and possible next steps. + */ + message?: string; } /** From 6cbbe6125e03a2fca8c7e8e3fe7ee15c7bbe9e81 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 27 Sep 2026 09:18:35 +0000 Subject: [PATCH 097/232] seal --- src/resources/batch.ts | 12 ++++++++---- src/resources/web.ts | 2 +- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 011368c2..c8ecbb91 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -1658,7 +1658,8 @@ export namespace BatchSubmitParams { includeSelectors?: Array | null; /** - * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. + * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 + * year (31536000000 ms). `0` fetches fresh. */ maxAgeMs?: number | null; @@ -1987,7 +1988,8 @@ export namespace BatchSubmitParams { includeSelectors?: Array | null; /** - * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. + * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 + * year (31536000000 ms). `0` fetches fresh. */ maxAgeMs?: number | null; @@ -2410,7 +2412,8 @@ export namespace BatchSubmitParams { includeSelectors?: Array | null; /** - * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. + * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 + * year (31536000000 ms). `0` fetches fresh. */ maxAgeMs?: number | null; @@ -2806,7 +2809,8 @@ export namespace BatchSubmitParams { includeSelectors?: Array | null; /** - * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. + * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 + * year (31536000000 ms). `0` fetches fresh. */ maxAgeMs?: number | null; diff --git a/src/resources/web.ts b/src/resources/web.ts index 46e1967c..77b87f27 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2203,7 +2203,7 @@ export interface WebScrapeParams { /** * Maximum age of a cached output, in milliseconds. `0` fetches fresh. Defaults to - * 1 day. + * 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). */ maxAgeMs?: number; From 56cf963833d23e8e663cea0cb241007b4f4e99f2 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 27 Sep 2026 09:18:36 +0000 Subject: [PATCH 098/232] feat(scrape): default cache age to three days and allow one year (#1339) Stainless-Generated-From: 6cbbe6125e03a2fca8c7e8e3fe7ee15c7bbe9e81 --- src/resources/batch.ts | 12 ++++++++---- src/resources/web.ts | 2 +- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 011368c2..c8ecbb91 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -1658,7 +1658,8 @@ export namespace BatchSubmitParams { includeSelectors?: Array | null; /** - * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. + * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 + * year (31536000000 ms). `0` fetches fresh. */ maxAgeMs?: number | null; @@ -1987,7 +1988,8 @@ export namespace BatchSubmitParams { includeSelectors?: Array | null; /** - * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. + * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 + * year (31536000000 ms). `0` fetches fresh. */ maxAgeMs?: number | null; @@ -2410,7 +2412,8 @@ export namespace BatchSubmitParams { includeSelectors?: Array | null; /** - * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. + * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 + * year (31536000000 ms). `0` fetches fresh. */ maxAgeMs?: number | null; @@ -2806,7 +2809,8 @@ export namespace BatchSubmitParams { includeSelectors?: Array | null; /** - * Maximum cache age in milliseconds. Defaults to 1 day. `0` fetches fresh. + * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 + * year (31536000000 ms). `0` fetches fresh. */ maxAgeMs?: number | null; diff --git a/src/resources/web.ts b/src/resources/web.ts index 46e1967c..77b87f27 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2203,7 +2203,7 @@ export interface WebScrapeParams { /** * Maximum age of a cached output, in milliseconds. `0` fetches fresh. Defaults to - * 1 day. + * 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). */ maxAgeMs?: number; From f5c8911507f828a350ecec7c0b58e6dc8253a497 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 27 Sep 2026 09:29:10 +0000 Subject: [PATCH 099/232] seal --- src/resources/web.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 77b87f27..3c918230 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -74,8 +74,8 @@ export class Web extends APIResource { } /** - * Returns the outputs you enable in `formats` from one visit to a URL. Each output - * reports its own `success`, so a failed output does not fail the request. + * Scrape anything from a URL on the internet. Returns the outputs you enable in + * formats. Handles PDFs, DOCX, PPT, XLSX, and 40 other file formats. * * @example * ```ts From 84ace2adbccb99145ab5930a3cca20aa6b71eeb7 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 27 Sep 2026 09:29:10 +0000 Subject: [PATCH 100/232] docs(scrape): rename endpoint to Scrape Anything (#1341) Stainless-Generated-From: f5c8911507f828a350ecec7c0b58e6dc8253a497 --- src/resources/web.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 77b87f27..3c918230 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -74,8 +74,8 @@ export class Web extends APIResource { } /** - * Returns the outputs you enable in `formats` from one visit to a URL. Each output - * reports its own `success`, so a failed output does not fail the request. + * Scrape anything from a URL on the internet. Returns the outputs you enable in + * formats. Handles PDFs, DOCX, PPT, XLSX, and 40 other file formats. * * @example * ```ts From 444273f1a5db3891dc39454f026cf53817edcde4 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 27 Sep 2026 09:44:06 +0000 Subject: [PATCH 101/232] seal --- src/resources/web.ts | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 3c918230..e35918a7 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -143,8 +143,9 @@ export interface WebAnswersResponse { json_content: { [key: string]: unknown }; /** - * URLs that supplied search results or readable page content, in first-seen order. - * Unreadable pages are excluded. + * Public evidence URLs from searches, pages, or company/profile records, in + * first-seen order. A listed URL may identify a record without its page being + * read. */ sources: Array; @@ -1940,7 +1941,8 @@ export namespace WebWebCrawlMdResponse { export interface WebAnswersParams { /** - * Research task. Name a domain to have it read before searching. + * Research task. The agent selects company/profile lookups, web searches, or page + * reads. Include domains or URLs to focus the research. */ task: string; @@ -1951,7 +1953,8 @@ export interface WebAnswersParams { json_format?: { [key: string]: unknown }; /** - * `fast` for short tasks; `ultra` for deeper research (default). + * `fast` prioritizes speed, with extra verification for people and companies; + * `ultra` supports deeper research (default). */ mode?: 'fast' | 'ultra'; From 8c27f11e9869c560e48733e7eea567bcaac4f68b Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 27 Sep 2026 09:44:06 +0000 Subject: [PATCH 102/232] feat(answers): route people and company research with faster answers (#1336) Stainless-Generated-From: 444273f1a5db3891dc39454f026cf53817edcde4 --- src/resources/web.ts | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 3c918230..e35918a7 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -143,8 +143,9 @@ export interface WebAnswersResponse { json_content: { [key: string]: unknown }; /** - * URLs that supplied search results or readable page content, in first-seen order. - * Unreadable pages are excluded. + * Public evidence URLs from searches, pages, or company/profile records, in + * first-seen order. A listed URL may identify a record without its page being + * read. */ sources: Array; @@ -1940,7 +1941,8 @@ export namespace WebWebCrawlMdResponse { export interface WebAnswersParams { /** - * Research task. Name a domain to have it read before searching. + * Research task. The agent selects company/profile lookups, web searches, or page + * reads. Include domains or URLs to focus the research. */ task: string; @@ -1951,7 +1953,8 @@ export interface WebAnswersParams { json_format?: { [key: string]: unknown }; /** - * `fast` for short tasks; `ultra` for deeper research (default). + * `fast` prioritizes speed, with extra verification for people and companies; + * `ultra` supports deeper research (default). */ mode?: 'fast' | 'ultra'; From 4664d73c95dd545201741ec178628c36d593a544 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 28 Sep 2026 04:33:31 +0000 Subject: [PATCH 103/232] seal --- src/resources/web.ts | 84 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 82 insertions(+), 2 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index e35918a7..d5e69785 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1001,6 +1001,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } export namespace Bytes { @@ -1043,6 +1053,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } /** @@ -1057,6 +1077,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } /** @@ -1071,6 +1101,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } export namespace Images { @@ -1121,12 +1161,12 @@ export namespace WebScrapeResponse { success: boolean | null; /** - * Cause of a failed JSON extraction, when available. + * Why the output failed. Present only when `success` is `false`. */ error_code?: string; /** - * Explanation of the JSON extraction failure and possible next steps. + * Explanation of the failure and possible next steps. */ message?: string; } @@ -1143,6 +1183,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } /** @@ -1289,6 +1339,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } /** @@ -1303,6 +1363,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } export namespace Product { @@ -1450,6 +1520,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } /** From b552101be2e060deff5ab065ec7dc557bf439f18 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 28 Sep 2026 04:33:32 +0000 Subject: [PATCH 104/232] feat(api): explain failed scrape outputs and fix agent-reported bugs (#1360) Stainless-Generated-From: 4664d73c95dd545201741ec178628c36d593a544 --- src/resources/web.ts | 84 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 82 insertions(+), 2 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index e35918a7..d5e69785 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1001,6 +1001,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } export namespace Bytes { @@ -1043,6 +1053,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } /** @@ -1057,6 +1077,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } /** @@ -1071,6 +1101,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } export namespace Images { @@ -1121,12 +1161,12 @@ export namespace WebScrapeResponse { success: boolean | null; /** - * Cause of a failed JSON extraction, when available. + * Why the output failed. Present only when `success` is `false`. */ error_code?: string; /** - * Explanation of the JSON extraction failure and possible next steps. + * Explanation of the failure and possible next steps. */ message?: string; } @@ -1143,6 +1183,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } /** @@ -1289,6 +1339,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } /** @@ -1303,6 +1363,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } export namespace Product { @@ -1450,6 +1520,16 @@ export namespace WebScrapeResponse { * `true` if returned, `false` if it failed, `null` if not requested. */ success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } /** From 9c4d8c6a032ab485a2dacb8e596641e69b910dad Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 28 Sep 2026 05:44:02 +0000 Subject: [PATCH 105/232] feat(monitors): support browser actions on page monitors (#1365) Stainless-Generated-From: 3c1d56316bc5f96f02a6e0640763a367e5d3cf13 --- src/resources/monitors.ts | 532 +++++++++++++++++++++++++++ tests/api-resources/monitors.test.ts | 1 + 2 files changed, 533 insertions(+) diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index 11bd5eb5..454a7a40 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -443,6 +443,17 @@ export namespace MonitorCreateResponse { */ url: string; + /** + * Optional browser actions executed in array order after the page loads, before + * content is captured, on every run. Requires a paid plan. Maximum: 5 actions. + * Changes create a new baseline. + */ + actions?: Array< + | MonitorsPageTarget.WebScrapeWaitAction + | MonitorsPageTarget.WebScrapePerformAction + | MonitorsPageTarget.WebScrapeScrollAction + > | null; + /** * Remove matching regions after inclusions. Changes create a new baseline. */ @@ -466,6 +477,71 @@ export namespace MonitorCreateResponse { normalize_whitespace?: boolean; } + export namespace MonitorsPageTarget { + /** + * Pause for a fixed number of milliseconds before continuing to the next action. + */ + export interface WebScrapeWaitAction { + /** + * Use `wait` to pause for a fixed duration. + */ + do: 'wait'; + + /** + * Time to pause in milliseconds before the next action. + */ + timeMs: number; + } + + /** + * Resolve and perform one natural-language browser action. + */ + export interface WebScrapePerformAction { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + do: 'perform'; + } + + /** + * Scroll the page or a selected scrollable container, waiting adaptively for + * content and dimensions to settle after each iteration. + */ + export interface WebScrapeScrollAction { + /** + * Use `scroll` to move through the page or a container. + */ + do: 'scroll'; + + /** + * Pixels per scroll, one visible viewport, or the current scroll boundary. + * Defaults to viewport. + */ + amount?: number | 'viewport' | 'max'; + + /** + * CSS selector for the first matching scroll container. Defaults to the page. + */ + container?: string; + + /** + * Direction to scroll. Defaults to down. + */ + direction?: 'up' | 'down' | 'left' | 'right'; + + /** + * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop + * changing. Defaults to 1. + */ + maxScrolls?: number; + } + } + /** * Watch a site’s URL inventory for confirmed additions and removals. */ @@ -839,6 +915,17 @@ export namespace MonitorRetrieveResponse { */ url: string; + /** + * Optional browser actions executed in array order after the page loads, before + * content is captured, on every run. Requires a paid plan. Maximum: 5 actions. + * Changes create a new baseline. + */ + actions?: Array< + | MonitorsPageTarget.WebScrapeWaitAction + | MonitorsPageTarget.WebScrapePerformAction + | MonitorsPageTarget.WebScrapeScrollAction + > | null; + /** * Remove matching regions after inclusions. Changes create a new baseline. */ @@ -862,6 +949,71 @@ export namespace MonitorRetrieveResponse { normalize_whitespace?: boolean; } + export namespace MonitorsPageTarget { + /** + * Pause for a fixed number of milliseconds before continuing to the next action. + */ + export interface WebScrapeWaitAction { + /** + * Use `wait` to pause for a fixed duration. + */ + do: 'wait'; + + /** + * Time to pause in milliseconds before the next action. + */ + timeMs: number; + } + + /** + * Resolve and perform one natural-language browser action. + */ + export interface WebScrapePerformAction { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + do: 'perform'; + } + + /** + * Scroll the page or a selected scrollable container, waiting adaptively for + * content and dimensions to settle after each iteration. + */ + export interface WebScrapeScrollAction { + /** + * Use `scroll` to move through the page or a container. + */ + do: 'scroll'; + + /** + * Pixels per scroll, one visible viewport, or the current scroll boundary. + * Defaults to viewport. + */ + amount?: number | 'viewport' | 'max'; + + /** + * CSS selector for the first matching scroll container. Defaults to the page. + */ + container?: string; + + /** + * Direction to scroll. Defaults to down. + */ + direction?: 'up' | 'down' | 'left' | 'right'; + + /** + * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop + * changing. Defaults to 1. + */ + maxScrolls?: number; + } + } + /** * Watch a site’s URL inventory for confirmed additions and removals. */ @@ -1235,6 +1387,17 @@ export namespace MonitorUpdateResponse { */ url: string; + /** + * Optional browser actions executed in array order after the page loads, before + * content is captured, on every run. Requires a paid plan. Maximum: 5 actions. + * Changes create a new baseline. + */ + actions?: Array< + | MonitorsPageTarget.WebScrapeWaitAction + | MonitorsPageTarget.WebScrapePerformAction + | MonitorsPageTarget.WebScrapeScrollAction + > | null; + /** * Remove matching regions after inclusions. Changes create a new baseline. */ @@ -1258,6 +1421,71 @@ export namespace MonitorUpdateResponse { normalize_whitespace?: boolean; } + export namespace MonitorsPageTarget { + /** + * Pause for a fixed number of milliseconds before continuing to the next action. + */ + export interface WebScrapeWaitAction { + /** + * Use `wait` to pause for a fixed duration. + */ + do: 'wait'; + + /** + * Time to pause in milliseconds before the next action. + */ + timeMs: number; + } + + /** + * Resolve and perform one natural-language browser action. + */ + export interface WebScrapePerformAction { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + do: 'perform'; + } + + /** + * Scroll the page or a selected scrollable container, waiting adaptively for + * content and dimensions to settle after each iteration. + */ + export interface WebScrapeScrollAction { + /** + * Use `scroll` to move through the page or a container. + */ + do: 'scroll'; + + /** + * Pixels per scroll, one visible viewport, or the current scroll boundary. + * Defaults to viewport. + */ + amount?: number | 'viewport' | 'max'; + + /** + * CSS selector for the first matching scroll container. Defaults to the page. + */ + container?: string; + + /** + * Direction to scroll. Defaults to down. + */ + direction?: 'up' | 'down' | 'left' | 'right'; + + /** + * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop + * changing. Defaults to 1. + */ + maxScrolls?: number; + } + } + /** * Watch a site’s URL inventory for confirmed additions and removals. */ @@ -1659,6 +1887,17 @@ export namespace MonitorListResponse { */ url: string; + /** + * Optional browser actions executed in array order after the page loads, before + * content is captured, on every run. Requires a paid plan. Maximum: 5 actions. + * Changes create a new baseline. + */ + actions?: Array< + | MonitorsPageTarget.WebScrapeWaitAction + | MonitorsPageTarget.WebScrapePerformAction + | MonitorsPageTarget.WebScrapeScrollAction + > | null; + /** * Remove matching regions after inclusions. Changes create a new baseline. */ @@ -1682,6 +1921,71 @@ export namespace MonitorListResponse { normalize_whitespace?: boolean; } + export namespace MonitorsPageTarget { + /** + * Pause for a fixed number of milliseconds before continuing to the next action. + */ + export interface WebScrapeWaitAction { + /** + * Use `wait` to pause for a fixed duration. + */ + do: 'wait'; + + /** + * Time to pause in milliseconds before the next action. + */ + timeMs: number; + } + + /** + * Resolve and perform one natural-language browser action. + */ + export interface WebScrapePerformAction { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + do: 'perform'; + } + + /** + * Scroll the page or a selected scrollable container, waiting adaptively for + * content and dimensions to settle after each iteration. + */ + export interface WebScrapeScrollAction { + /** + * Use `scroll` to move through the page or a container. + */ + do: 'scroll'; + + /** + * Pixels per scroll, one visible viewport, or the current scroll boundary. + * Defaults to viewport. + */ + amount?: number | 'viewport' | 'max'; + + /** + * CSS selector for the first matching scroll container. Defaults to the page. + */ + container?: string; + + /** + * Direction to scroll. Defaults to down. + */ + direction?: 'up' | 'down' | 'left' | 'right'; + + /** + * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop + * changing. Defaults to 1. + */ + maxScrolls?: number; + } + } + /** * Watch a site’s URL inventory for confirmed additions and removals. */ @@ -2850,6 +3154,17 @@ export namespace MonitorRotateWebhookSecretResponse { */ url: string; + /** + * Optional browser actions executed in array order after the page loads, before + * content is captured, on every run. Requires a paid plan. Maximum: 5 actions. + * Changes create a new baseline. + */ + actions?: Array< + | MonitorsPageTarget.WebScrapeWaitAction + | MonitorsPageTarget.WebScrapePerformAction + | MonitorsPageTarget.WebScrapeScrollAction + > | null; + /** * Remove matching regions after inclusions. Changes create a new baseline. */ @@ -2873,6 +3188,71 @@ export namespace MonitorRotateWebhookSecretResponse { normalize_whitespace?: boolean; } + export namespace MonitorsPageTarget { + /** + * Pause for a fixed number of milliseconds before continuing to the next action. + */ + export interface WebScrapeWaitAction { + /** + * Use `wait` to pause for a fixed duration. + */ + do: 'wait'; + + /** + * Time to pause in milliseconds before the next action. + */ + timeMs: number; + } + + /** + * Resolve and perform one natural-language browser action. + */ + export interface WebScrapePerformAction { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + do: 'perform'; + } + + /** + * Scroll the page or a selected scrollable container, waiting adaptively for + * content and dimensions to settle after each iteration. + */ + export interface WebScrapeScrollAction { + /** + * Use `scroll` to move through the page or a container. + */ + do: 'scroll'; + + /** + * Pixels per scroll, one visible viewport, or the current scroll boundary. + * Defaults to viewport. + */ + amount?: number | 'viewport' | 'max'; + + /** + * CSS selector for the first matching scroll container. Defaults to the page. + */ + container?: string; + + /** + * Direction to scroll. Defaults to down. + */ + direction?: 'up' | 'down' | 'left' | 'right'; + + /** + * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop + * changing. Defaults to 1. + */ + maxScrolls?: number; + } + } + /** * Watch a site’s URL inventory for confirmed additions and removals. */ @@ -3207,6 +3587,17 @@ export namespace MonitorCreateParams { */ url: string; + /** + * Optional browser actions executed in array order after the page loads, before + * content is captured, on every run. Requires a paid plan. Maximum: 5 actions. + * Changes create a new baseline. + */ + actions?: Array< + | MonitorsPageTarget.WebScrapeWaitAction + | MonitorsPageTarget.WebScrapePerformAction + | MonitorsPageTarget.WebScrapeScrollAction + > | null; + /** * Remove matching regions after inclusions. Changes create a new baseline. */ @@ -3230,6 +3621,71 @@ export namespace MonitorCreateParams { normalize_whitespace?: boolean; } + export namespace MonitorsPageTarget { + /** + * Pause for a fixed number of milliseconds before continuing to the next action. + */ + export interface WebScrapeWaitAction { + /** + * Use `wait` to pause for a fixed duration. + */ + do: 'wait'; + + /** + * Time to pause in milliseconds before the next action. + */ + timeMs: number; + } + + /** + * Resolve and perform one natural-language browser action. + */ + export interface WebScrapePerformAction { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + do: 'perform'; + } + + /** + * Scroll the page or a selected scrollable container, waiting adaptively for + * content and dimensions to settle after each iteration. + */ + export interface WebScrapeScrollAction { + /** + * Use `scroll` to move through the page or a container. + */ + do: 'scroll'; + + /** + * Pixels per scroll, one visible viewport, or the current scroll boundary. + * Defaults to viewport. + */ + amount?: number | 'viewport' | 'max'; + + /** + * CSS selector for the first matching scroll container. Defaults to the page. + */ + container?: string; + + /** + * Direction to scroll. Defaults to down. + */ + direction?: 'up' | 'down' | 'left' | 'right'; + + /** + * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop + * changing. Defaults to 1. + */ + maxScrolls?: number; + } + } + /** * Watch a site’s URL inventory for confirmed additions and removals. */ @@ -3489,6 +3945,17 @@ export namespace MonitorUpdateParams { */ url: string; + /** + * Optional browser actions executed in array order after the page loads, before + * content is captured, on every run. Requires a paid plan. Maximum: 5 actions. + * Changes create a new baseline. + */ + actions?: Array< + | MonitorsPageTarget.WebScrapeWaitAction + | MonitorsPageTarget.WebScrapePerformAction + | MonitorsPageTarget.WebScrapeScrollAction + > | null; + /** * Remove matching regions after inclusions. Changes create a new baseline. */ @@ -3512,6 +3979,71 @@ export namespace MonitorUpdateParams { normalize_whitespace?: boolean; } + export namespace MonitorsPageTarget { + /** + * Pause for a fixed number of milliseconds before continuing to the next action. + */ + export interface WebScrapeWaitAction { + /** + * Use `wait` to pause for a fixed duration. + */ + do: 'wait'; + + /** + * Time to pause in milliseconds before the next action. + */ + timeMs: number; + } + + /** + * Resolve and perform one natural-language browser action. + */ + export interface WebScrapePerformAction { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + do: 'perform'; + } + + /** + * Scroll the page or a selected scrollable container, waiting adaptively for + * content and dimensions to settle after each iteration. + */ + export interface WebScrapeScrollAction { + /** + * Use `scroll` to move through the page or a container. + */ + do: 'scroll'; + + /** + * Pixels per scroll, one visible viewport, or the current scroll boundary. + * Defaults to viewport. + */ + amount?: number | 'viewport' | 'max'; + + /** + * CSS selector for the first matching scroll container. Defaults to the page. + */ + container?: string; + + /** + * Direction to scroll. Defaults to down. + */ + direction?: 'up' | 'down' | 'left' | 'right'; + + /** + * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop + * changing. Defaults to 1. + */ + maxScrolls?: number; + } + } + /** * Watch a site’s URL inventory for confirmed additions and removals. */ diff --git a/tests/api-resources/monitors.test.ts b/tests/api-resources/monitors.test.ts index d93ec765..720bf284 100644 --- a/tests/api-resources/monitors.test.ts +++ b/tests/api-resources/monitors.test.ts @@ -30,6 +30,7 @@ describe('resource monitors', () => { target: { type: 'page', url: 'https://acme.com/pricing', + actions: [{ do: 'wait', timeMs: 0 }], exclude_selectors: ['.carousel', '[id^="TA_"]'], include_selectors: ['#attraction-details'], instructions: From 3c1d56316bc5f96f02a6e0640763a367e5d3cf13 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 28 Sep 2026 05:44:02 +0000 Subject: [PATCH 106/232] seal --- src/resources/monitors.ts | 532 +++++++++++++++++++++++++++ tests/api-resources/monitors.test.ts | 1 + 2 files changed, 533 insertions(+) diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index 11bd5eb5..454a7a40 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -443,6 +443,17 @@ export namespace MonitorCreateResponse { */ url: string; + /** + * Optional browser actions executed in array order after the page loads, before + * content is captured, on every run. Requires a paid plan. Maximum: 5 actions. + * Changes create a new baseline. + */ + actions?: Array< + | MonitorsPageTarget.WebScrapeWaitAction + | MonitorsPageTarget.WebScrapePerformAction + | MonitorsPageTarget.WebScrapeScrollAction + > | null; + /** * Remove matching regions after inclusions. Changes create a new baseline. */ @@ -466,6 +477,71 @@ export namespace MonitorCreateResponse { normalize_whitespace?: boolean; } + export namespace MonitorsPageTarget { + /** + * Pause for a fixed number of milliseconds before continuing to the next action. + */ + export interface WebScrapeWaitAction { + /** + * Use `wait` to pause for a fixed duration. + */ + do: 'wait'; + + /** + * Time to pause in milliseconds before the next action. + */ + timeMs: number; + } + + /** + * Resolve and perform one natural-language browser action. + */ + export interface WebScrapePerformAction { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + do: 'perform'; + } + + /** + * Scroll the page or a selected scrollable container, waiting adaptively for + * content and dimensions to settle after each iteration. + */ + export interface WebScrapeScrollAction { + /** + * Use `scroll` to move through the page or a container. + */ + do: 'scroll'; + + /** + * Pixels per scroll, one visible viewport, or the current scroll boundary. + * Defaults to viewport. + */ + amount?: number | 'viewport' | 'max'; + + /** + * CSS selector for the first matching scroll container. Defaults to the page. + */ + container?: string; + + /** + * Direction to scroll. Defaults to down. + */ + direction?: 'up' | 'down' | 'left' | 'right'; + + /** + * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop + * changing. Defaults to 1. + */ + maxScrolls?: number; + } + } + /** * Watch a site’s URL inventory for confirmed additions and removals. */ @@ -839,6 +915,17 @@ export namespace MonitorRetrieveResponse { */ url: string; + /** + * Optional browser actions executed in array order after the page loads, before + * content is captured, on every run. Requires a paid plan. Maximum: 5 actions. + * Changes create a new baseline. + */ + actions?: Array< + | MonitorsPageTarget.WebScrapeWaitAction + | MonitorsPageTarget.WebScrapePerformAction + | MonitorsPageTarget.WebScrapeScrollAction + > | null; + /** * Remove matching regions after inclusions. Changes create a new baseline. */ @@ -862,6 +949,71 @@ export namespace MonitorRetrieveResponse { normalize_whitespace?: boolean; } + export namespace MonitorsPageTarget { + /** + * Pause for a fixed number of milliseconds before continuing to the next action. + */ + export interface WebScrapeWaitAction { + /** + * Use `wait` to pause for a fixed duration. + */ + do: 'wait'; + + /** + * Time to pause in milliseconds before the next action. + */ + timeMs: number; + } + + /** + * Resolve and perform one natural-language browser action. + */ + export interface WebScrapePerformAction { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + do: 'perform'; + } + + /** + * Scroll the page or a selected scrollable container, waiting adaptively for + * content and dimensions to settle after each iteration. + */ + export interface WebScrapeScrollAction { + /** + * Use `scroll` to move through the page or a container. + */ + do: 'scroll'; + + /** + * Pixels per scroll, one visible viewport, or the current scroll boundary. + * Defaults to viewport. + */ + amount?: number | 'viewport' | 'max'; + + /** + * CSS selector for the first matching scroll container. Defaults to the page. + */ + container?: string; + + /** + * Direction to scroll. Defaults to down. + */ + direction?: 'up' | 'down' | 'left' | 'right'; + + /** + * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop + * changing. Defaults to 1. + */ + maxScrolls?: number; + } + } + /** * Watch a site’s URL inventory for confirmed additions and removals. */ @@ -1235,6 +1387,17 @@ export namespace MonitorUpdateResponse { */ url: string; + /** + * Optional browser actions executed in array order after the page loads, before + * content is captured, on every run. Requires a paid plan. Maximum: 5 actions. + * Changes create a new baseline. + */ + actions?: Array< + | MonitorsPageTarget.WebScrapeWaitAction + | MonitorsPageTarget.WebScrapePerformAction + | MonitorsPageTarget.WebScrapeScrollAction + > | null; + /** * Remove matching regions after inclusions. Changes create a new baseline. */ @@ -1258,6 +1421,71 @@ export namespace MonitorUpdateResponse { normalize_whitespace?: boolean; } + export namespace MonitorsPageTarget { + /** + * Pause for a fixed number of milliseconds before continuing to the next action. + */ + export interface WebScrapeWaitAction { + /** + * Use `wait` to pause for a fixed duration. + */ + do: 'wait'; + + /** + * Time to pause in milliseconds before the next action. + */ + timeMs: number; + } + + /** + * Resolve and perform one natural-language browser action. + */ + export interface WebScrapePerformAction { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + do: 'perform'; + } + + /** + * Scroll the page or a selected scrollable container, waiting adaptively for + * content and dimensions to settle after each iteration. + */ + export interface WebScrapeScrollAction { + /** + * Use `scroll` to move through the page or a container. + */ + do: 'scroll'; + + /** + * Pixels per scroll, one visible viewport, or the current scroll boundary. + * Defaults to viewport. + */ + amount?: number | 'viewport' | 'max'; + + /** + * CSS selector for the first matching scroll container. Defaults to the page. + */ + container?: string; + + /** + * Direction to scroll. Defaults to down. + */ + direction?: 'up' | 'down' | 'left' | 'right'; + + /** + * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop + * changing. Defaults to 1. + */ + maxScrolls?: number; + } + } + /** * Watch a site’s URL inventory for confirmed additions and removals. */ @@ -1659,6 +1887,17 @@ export namespace MonitorListResponse { */ url: string; + /** + * Optional browser actions executed in array order after the page loads, before + * content is captured, on every run. Requires a paid plan. Maximum: 5 actions. + * Changes create a new baseline. + */ + actions?: Array< + | MonitorsPageTarget.WebScrapeWaitAction + | MonitorsPageTarget.WebScrapePerformAction + | MonitorsPageTarget.WebScrapeScrollAction + > | null; + /** * Remove matching regions after inclusions. Changes create a new baseline. */ @@ -1682,6 +1921,71 @@ export namespace MonitorListResponse { normalize_whitespace?: boolean; } + export namespace MonitorsPageTarget { + /** + * Pause for a fixed number of milliseconds before continuing to the next action. + */ + export interface WebScrapeWaitAction { + /** + * Use `wait` to pause for a fixed duration. + */ + do: 'wait'; + + /** + * Time to pause in milliseconds before the next action. + */ + timeMs: number; + } + + /** + * Resolve and perform one natural-language browser action. + */ + export interface WebScrapePerformAction { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + do: 'perform'; + } + + /** + * Scroll the page or a selected scrollable container, waiting adaptively for + * content and dimensions to settle after each iteration. + */ + export interface WebScrapeScrollAction { + /** + * Use `scroll` to move through the page or a container. + */ + do: 'scroll'; + + /** + * Pixels per scroll, one visible viewport, or the current scroll boundary. + * Defaults to viewport. + */ + amount?: number | 'viewport' | 'max'; + + /** + * CSS selector for the first matching scroll container. Defaults to the page. + */ + container?: string; + + /** + * Direction to scroll. Defaults to down. + */ + direction?: 'up' | 'down' | 'left' | 'right'; + + /** + * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop + * changing. Defaults to 1. + */ + maxScrolls?: number; + } + } + /** * Watch a site’s URL inventory for confirmed additions and removals. */ @@ -2850,6 +3154,17 @@ export namespace MonitorRotateWebhookSecretResponse { */ url: string; + /** + * Optional browser actions executed in array order after the page loads, before + * content is captured, on every run. Requires a paid plan. Maximum: 5 actions. + * Changes create a new baseline. + */ + actions?: Array< + | MonitorsPageTarget.WebScrapeWaitAction + | MonitorsPageTarget.WebScrapePerformAction + | MonitorsPageTarget.WebScrapeScrollAction + > | null; + /** * Remove matching regions after inclusions. Changes create a new baseline. */ @@ -2873,6 +3188,71 @@ export namespace MonitorRotateWebhookSecretResponse { normalize_whitespace?: boolean; } + export namespace MonitorsPageTarget { + /** + * Pause for a fixed number of milliseconds before continuing to the next action. + */ + export interface WebScrapeWaitAction { + /** + * Use `wait` to pause for a fixed duration. + */ + do: 'wait'; + + /** + * Time to pause in milliseconds before the next action. + */ + timeMs: number; + } + + /** + * Resolve and perform one natural-language browser action. + */ + export interface WebScrapePerformAction { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + do: 'perform'; + } + + /** + * Scroll the page or a selected scrollable container, waiting adaptively for + * content and dimensions to settle after each iteration. + */ + export interface WebScrapeScrollAction { + /** + * Use `scroll` to move through the page or a container. + */ + do: 'scroll'; + + /** + * Pixels per scroll, one visible viewport, or the current scroll boundary. + * Defaults to viewport. + */ + amount?: number | 'viewport' | 'max'; + + /** + * CSS selector for the first matching scroll container. Defaults to the page. + */ + container?: string; + + /** + * Direction to scroll. Defaults to down. + */ + direction?: 'up' | 'down' | 'left' | 'right'; + + /** + * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop + * changing. Defaults to 1. + */ + maxScrolls?: number; + } + } + /** * Watch a site’s URL inventory for confirmed additions and removals. */ @@ -3207,6 +3587,17 @@ export namespace MonitorCreateParams { */ url: string; + /** + * Optional browser actions executed in array order after the page loads, before + * content is captured, on every run. Requires a paid plan. Maximum: 5 actions. + * Changes create a new baseline. + */ + actions?: Array< + | MonitorsPageTarget.WebScrapeWaitAction + | MonitorsPageTarget.WebScrapePerformAction + | MonitorsPageTarget.WebScrapeScrollAction + > | null; + /** * Remove matching regions after inclusions. Changes create a new baseline. */ @@ -3230,6 +3621,71 @@ export namespace MonitorCreateParams { normalize_whitespace?: boolean; } + export namespace MonitorsPageTarget { + /** + * Pause for a fixed number of milliseconds before continuing to the next action. + */ + export interface WebScrapeWaitAction { + /** + * Use `wait` to pause for a fixed duration. + */ + do: 'wait'; + + /** + * Time to pause in milliseconds before the next action. + */ + timeMs: number; + } + + /** + * Resolve and perform one natural-language browser action. + */ + export interface WebScrapePerformAction { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + do: 'perform'; + } + + /** + * Scroll the page or a selected scrollable container, waiting adaptively for + * content and dimensions to settle after each iteration. + */ + export interface WebScrapeScrollAction { + /** + * Use `scroll` to move through the page or a container. + */ + do: 'scroll'; + + /** + * Pixels per scroll, one visible viewport, or the current scroll boundary. + * Defaults to viewport. + */ + amount?: number | 'viewport' | 'max'; + + /** + * CSS selector for the first matching scroll container. Defaults to the page. + */ + container?: string; + + /** + * Direction to scroll. Defaults to down. + */ + direction?: 'up' | 'down' | 'left' | 'right'; + + /** + * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop + * changing. Defaults to 1. + */ + maxScrolls?: number; + } + } + /** * Watch a site’s URL inventory for confirmed additions and removals. */ @@ -3489,6 +3945,17 @@ export namespace MonitorUpdateParams { */ url: string; + /** + * Optional browser actions executed in array order after the page loads, before + * content is captured, on every run. Requires a paid plan. Maximum: 5 actions. + * Changes create a new baseline. + */ + actions?: Array< + | MonitorsPageTarget.WebScrapeWaitAction + | MonitorsPageTarget.WebScrapePerformAction + | MonitorsPageTarget.WebScrapeScrollAction + > | null; + /** * Remove matching regions after inclusions. Changes create a new baseline. */ @@ -3512,6 +3979,71 @@ export namespace MonitorUpdateParams { normalize_whitespace?: boolean; } + export namespace MonitorsPageTarget { + /** + * Pause for a fixed number of milliseconds before continuing to the next action. + */ + export interface WebScrapeWaitAction { + /** + * Use `wait` to pause for a fixed duration. + */ + do: 'wait'; + + /** + * Time to pause in milliseconds before the next action. + */ + timeMs: number; + } + + /** + * Resolve and perform one natural-language browser action. + */ + export interface WebScrapePerformAction { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + do: 'perform'; + } + + /** + * Scroll the page or a selected scrollable container, waiting adaptively for + * content and dimensions to settle after each iteration. + */ + export interface WebScrapeScrollAction { + /** + * Use `scroll` to move through the page or a container. + */ + do: 'scroll'; + + /** + * Pixels per scroll, one visible viewport, or the current scroll boundary. + * Defaults to viewport. + */ + amount?: number | 'viewport' | 'max'; + + /** + * CSS selector for the first matching scroll container. Defaults to the page. + */ + container?: string; + + /** + * Direction to scroll. Defaults to down. + */ + direction?: 'up' | 'down' | 'left' | 'right'; + + /** + * Maximum scroll iterations. Stops early when scrolling and scrollable extent stop + * changing. Defaults to 1. + */ + maxScrolls?: number; + } + } + /** * Watch a site’s URL inventory for confirmed additions and removals. */ diff --git a/tests/api-resources/monitors.test.ts b/tests/api-resources/monitors.test.ts index d93ec765..720bf284 100644 --- a/tests/api-resources/monitors.test.ts +++ b/tests/api-resources/monitors.test.ts @@ -30,6 +30,7 @@ describe('resource monitors', () => { target: { type: 'page', url: 'https://acme.com/pricing', + actions: [{ do: 'wait', timeMs: 0 }], exclude_selectors: ['.carousel', '[id^="TA_"]'], include_selectors: ['#attraction-details'], instructions: From 9a4d3cfbd20e9181b84b5b60079cc232f0b94ae0 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 28 Sep 2026 23:28:50 +0000 Subject: [PATCH 107/232] feat(search): add highlights to web search and bill page reads per 10 results (#1387) Stainless-Generated-From: c278a6a392bbce41f07951ed979fa71f85b99071 --- src/resources/web.ts | 52 ++++++++++++++++++++++++++++++--- tests/api-resources/web.test.ts | 1 + 2 files changed, 49 insertions(+), 4 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index d5e69785..4a755b22 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -105,7 +105,8 @@ export class Web extends APIResource { } /** - * Search the web and optionally return page content with each result. + * Search the web and optionally return page content or relevant passages with each + * result. * * @example * ```ts @@ -1697,6 +1698,11 @@ export namespace WebSearchResponse { */ description: string; + /** + * Highlights status and passages for this result. + */ + highlights: Result.Highlights; + /** * Markdown scrape status and content for this result. */ @@ -1719,6 +1725,22 @@ export namespace WebSearchResponse { } export namespace Result { + /** + * Highlights status and passages for this result. + */ + export interface Highlights { + /** + * Per-result highlights outcome. Inspect this before reading `highlights`. + */ + code: 'SUCCESS' | 'NOT_REQUESTED' | 'TIMEOUT' | 'CONTENT_TOO_LARGE' | 'WEBSITE_ACCESS_ERROR' | 'ERROR'; + + /** + * Passages relevant to the query, in page order. Null unless + * highlightsOptions.enabled is true and the page was read. + */ + highlights: Array | null; + } + /** * Markdown scrape status and content for this result. */ @@ -3364,6 +3386,12 @@ export interface WebSearchParams { */ freshness?: 'last_24_hours' | 'last_week' | 'last_month' | 'last_year'; + /** + * Passages from each result page that are relevant to the query. Pages are read + * with the `markdownOptions` settings. + */ + highlightsOptions?: WebSearchParams.HighlightsOptions; + /** * Allowlist — only return results from these domains. Example: ["arxiv.org", * "github.com"]. @@ -3403,12 +3431,28 @@ export interface WebSearchParams { } export namespace WebSearchParams { + /** + * Passages from each result page that are relevant to the query. Pages are read + * with the `markdownOptions` settings. + */ + export interface HighlightsOptions { + /** + * Return relevant passages for each result. Adds 1 credit per 10 results. + */ + enabled?: boolean; + + /** + * Maximum combined length of passages per result. + */ + maxCharacters?: number; + } + /** * Inline Markdown scraping for each result. Set `enabled: true` to activate. */ export interface MarkdownOptions { /** - * Scrape each result to Markdown. Off by default to keep search cheap and fast. + * Scrape each result to Markdown. Adds 1 credit per 10 results. */ enabled?: boolean; @@ -3428,8 +3472,8 @@ export namespace WebSearchParams { includeLinks?: boolean; /** - * Cache TTL in ms for scraped Markdown keyed by URL + options. Default 1 day, max - * 30 days. Set to 0 to force a fresh scrape. + * Cache TTL in ms for scraped Markdown keyed by URL + options. Default 15 days, + * max 30 days. Set to 0 to force a fresh scrape. */ maxAgeMs?: number; diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index b6ace8ef..1a3328eb 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -262,6 +262,7 @@ describe('resource web', () => { country: 'af', excludeDomains: ['string'], freshness: 'last_24_hours', + highlightsOptions: { enabled: true, maxCharacters: 100 }, includeDomains: ['string'], markdownOptions: { enabled: true, From c278a6a392bbce41f07951ed979fa71f85b99071 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 28 Sep 2026 23:28:50 +0000 Subject: [PATCH 108/232] seal --- src/resources/web.ts | 52 ++++++++++++++++++++++++++++++--- tests/api-resources/web.test.ts | 1 + 2 files changed, 49 insertions(+), 4 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index d5e69785..4a755b22 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -105,7 +105,8 @@ export class Web extends APIResource { } /** - * Search the web and optionally return page content with each result. + * Search the web and optionally return page content or relevant passages with each + * result. * * @example * ```ts @@ -1697,6 +1698,11 @@ export namespace WebSearchResponse { */ description: string; + /** + * Highlights status and passages for this result. + */ + highlights: Result.Highlights; + /** * Markdown scrape status and content for this result. */ @@ -1719,6 +1725,22 @@ export namespace WebSearchResponse { } export namespace Result { + /** + * Highlights status and passages for this result. + */ + export interface Highlights { + /** + * Per-result highlights outcome. Inspect this before reading `highlights`. + */ + code: 'SUCCESS' | 'NOT_REQUESTED' | 'TIMEOUT' | 'CONTENT_TOO_LARGE' | 'WEBSITE_ACCESS_ERROR' | 'ERROR'; + + /** + * Passages relevant to the query, in page order. Null unless + * highlightsOptions.enabled is true and the page was read. + */ + highlights: Array | null; + } + /** * Markdown scrape status and content for this result. */ @@ -3364,6 +3386,12 @@ export interface WebSearchParams { */ freshness?: 'last_24_hours' | 'last_week' | 'last_month' | 'last_year'; + /** + * Passages from each result page that are relevant to the query. Pages are read + * with the `markdownOptions` settings. + */ + highlightsOptions?: WebSearchParams.HighlightsOptions; + /** * Allowlist — only return results from these domains. Example: ["arxiv.org", * "github.com"]. @@ -3403,12 +3431,28 @@ export interface WebSearchParams { } export namespace WebSearchParams { + /** + * Passages from each result page that are relevant to the query. Pages are read + * with the `markdownOptions` settings. + */ + export interface HighlightsOptions { + /** + * Return relevant passages for each result. Adds 1 credit per 10 results. + */ + enabled?: boolean; + + /** + * Maximum combined length of passages per result. + */ + maxCharacters?: number; + } + /** * Inline Markdown scraping for each result. Set `enabled: true` to activate. */ export interface MarkdownOptions { /** - * Scrape each result to Markdown. Off by default to keep search cheap and fast. + * Scrape each result to Markdown. Adds 1 credit per 10 results. */ enabled?: boolean; @@ -3428,8 +3472,8 @@ export namespace WebSearchParams { includeLinks?: boolean; /** - * Cache TTL in ms for scraped Markdown keyed by URL + options. Default 1 day, max - * 30 days. Set to 0 to force a fresh scrape. + * Cache TTL in ms for scraped Markdown keyed by URL + options. Default 15 days, + * max 30 days. Set to 0 to force a fresh scrape. */ maxAgeMs?: number; diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index b6ace8ef..1a3328eb 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -262,6 +262,7 @@ describe('resource web', () => { country: 'af', excludeDomains: ['string'], freshness: 'last_24_hours', + highlightsOptions: { enabled: true, maxCharacters: 100 }, includeDomains: ['string'], markdownOptions: { enabled: true, From d5f9ce1b09edf45122372dfcbd1cebaa6108b90e Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 29 Sep 2026 05:24:24 +0000 Subject: [PATCH 109/232] fix(api): document search domain limits and clarify scrape parameter errors (#1388) Stainless-Generated-From: 65eea2aed5bb36f2fb3d961175ca99f2655b5c3b --- src/resources/web.ts | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 4a755b22..43278c50 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2287,7 +2287,7 @@ export interface WebScrapeParams { url: string; /** - * Required when `formats.highlights` is `true`. + * Requires `formats.highlights: true`; required when it is set. */ highlightsParams?: WebScrapeParams.HighlightsParams; @@ -2297,7 +2297,7 @@ export interface WebScrapeParams { imageParams?: WebScrapeParams.ImageParams; /** - * Required when formats.json is true. + * Requires `formats.json: true`; required when it is set. */ jsonParams?: WebScrapeParams.JsonParams; @@ -2313,7 +2313,7 @@ export interface WebScrapeParams { maxAgeMs?: number; /** - * Required when formats.parse is true. + * Requires `formats.parse: true`; required when it is set. */ parseParams?: WebScrapeParams.ParseParams; @@ -2401,7 +2401,7 @@ export namespace WebScrapeParams { } /** - * Required when `formats.highlights` is `true`. + * Requires `formats.highlights: true`; required when it is set. */ export interface HighlightsParams { /** @@ -2431,12 +2431,12 @@ export namespace WebScrapeParams { } /** - * Required when formats.json is true. + * Requires `formats.json: true`; required when it is set. */ export interface JsonParams { /** - * JSON Schema for a top-level object, up to 50 KB. Use optional or nullable fields - * for missing facts. + * JSON Schema (not an example object) for a top-level object, up to 50 KB. Use + * optional or nullable fields for missing facts. */ schema: { [key: string]: unknown }; @@ -2468,7 +2468,7 @@ export namespace WebScrapeParams { } /** - * Required when formats.parse is true. + * Requires `formats.parse: true`; required when it is set. */ export interface ParseParams { /** @@ -3376,8 +3376,8 @@ export interface WebSearchParams { | 'zw'; /** - * Blocklist — drop results from these domains. Example: ["pinterest.com", - * "reddit.com"]. + * Blocklist — drop results from these domains. Up to 100 domains. Example: + * ["pinterest.com", "reddit.com"]. */ excludeDomains?: Array; @@ -3393,8 +3393,8 @@ export interface WebSearchParams { highlightsOptions?: WebSearchParams.HighlightsOptions; /** - * Allowlist — only return results from these domains. Example: ["arxiv.org", - * "github.com"]. + * Allowlist — only return results from these domains. Up to 100 domains. Example: + * ["arxiv.org", "github.com"]. */ includeDomains?: Array; From 65eea2aed5bb36f2fb3d961175ca99f2655b5c3b Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 29 Sep 2026 05:24:24 +0000 Subject: [PATCH 110/232] seal --- src/resources/web.ts | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 4a755b22..43278c50 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2287,7 +2287,7 @@ export interface WebScrapeParams { url: string; /** - * Required when `formats.highlights` is `true`. + * Requires `formats.highlights: true`; required when it is set. */ highlightsParams?: WebScrapeParams.HighlightsParams; @@ -2297,7 +2297,7 @@ export interface WebScrapeParams { imageParams?: WebScrapeParams.ImageParams; /** - * Required when formats.json is true. + * Requires `formats.json: true`; required when it is set. */ jsonParams?: WebScrapeParams.JsonParams; @@ -2313,7 +2313,7 @@ export interface WebScrapeParams { maxAgeMs?: number; /** - * Required when formats.parse is true. + * Requires `formats.parse: true`; required when it is set. */ parseParams?: WebScrapeParams.ParseParams; @@ -2401,7 +2401,7 @@ export namespace WebScrapeParams { } /** - * Required when `formats.highlights` is `true`. + * Requires `formats.highlights: true`; required when it is set. */ export interface HighlightsParams { /** @@ -2431,12 +2431,12 @@ export namespace WebScrapeParams { } /** - * Required when formats.json is true. + * Requires `formats.json: true`; required when it is set. */ export interface JsonParams { /** - * JSON Schema for a top-level object, up to 50 KB. Use optional or nullable fields - * for missing facts. + * JSON Schema (not an example object) for a top-level object, up to 50 KB. Use + * optional or nullable fields for missing facts. */ schema: { [key: string]: unknown }; @@ -2468,7 +2468,7 @@ export namespace WebScrapeParams { } /** - * Required when formats.parse is true. + * Requires `formats.parse: true`; required when it is set. */ export interface ParseParams { /** @@ -3376,8 +3376,8 @@ export interface WebSearchParams { | 'zw'; /** - * Blocklist — drop results from these domains. Example: ["pinterest.com", - * "reddit.com"]. + * Blocklist — drop results from these domains. Up to 100 domains. Example: + * ["pinterest.com", "reddit.com"]. */ excludeDomains?: Array; @@ -3393,8 +3393,8 @@ export interface WebSearchParams { highlightsOptions?: WebSearchParams.HighlightsOptions; /** - * Allowlist — only return results from these domains. Example: ["arxiv.org", - * "github.com"]. + * Allowlist — only return results from these domains. Up to 100 domains. Example: + * ["arxiv.org", "github.com"]. */ includeDomains?: Array; From 47f5a8e7dda03ff3d4507d3e45030d2e05ec3a69 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 29 Sep 2026 07:15:50 +0000 Subject: [PATCH 111/232] feat(web-search): extend page cache defaults (#1408) Stainless-Generated-From: 9fde92d5575461ded642d08378c27a6b3b474bc5 --- src/resources/web.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 43278c50..338a7fc4 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -3472,8 +3472,10 @@ export namespace WebSearchParams { includeLinks?: boolean; /** - * Cache TTL in ms for scraped Markdown keyed by URL + options. Default 15 days, - * max 30 days. Set to 0 to force a fresh scrape. + * Maximum cache age in milliseconds for result page content. Defaults to 180 days + * (15552000000 ms) when Markdown is requested, or 365 days (31536000000 ms) when + * only highlights are requested. Explicit values override either default. Maximum: + * 365 days. Set to 0 to force a fresh scrape. */ maxAgeMs?: number; From 9fde92d5575461ded642d08378c27a6b3b474bc5 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 29 Sep 2026 07:15:50 +0000 Subject: [PATCH 112/232] seal --- src/resources/web.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 43278c50..338a7fc4 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -3472,8 +3472,10 @@ export namespace WebSearchParams { includeLinks?: boolean; /** - * Cache TTL in ms for scraped Markdown keyed by URL + options. Default 15 days, - * max 30 days. Set to 0 to force a fresh scrape. + * Maximum cache age in milliseconds for result page content. Defaults to 180 days + * (15552000000 ms) when Markdown is requested, or 365 days (31536000000 ms) when + * only highlights are requested. Explicit values override either default. Maximum: + * 365 days. Set to 0 to force a fresh scrape. */ maxAgeMs?: number; From 11c44cce574547084902d5cecfd2657d975994d7 Mon Sep 17 00:00:00 2001 From: contextualbeer Date: Tue, 29 Sep 2026 09:17:45 +0200 Subject: [PATCH 113/232] release: 3.3.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 24 ++++++++++++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 27 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 95a37e3e..6110c0f0 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.2.0" + ".": "3.3.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 21b367fc..edcd7321 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,29 @@ # Changelog +## [3.3.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.2.0...v3.3.0) (2026-09-29) + + +### Features + +* **answers:** route people and company research with faster answers ([#1336](https://github.com/context-dot-dev/context-typescript-sdk/issues/1336)) ([8c27f11](https://github.com/context-dot-dev/context-typescript-sdk/commit/8c27f11e9869c560e48733e7eea567bcaac4f68b)) +* **api:** explain failed scrape outputs and fix agent-reported bugs ([#1360](https://github.com/context-dot-dev/context-typescript-sdk/issues/1360)) ([b552101](https://github.com/context-dot-dev/context-typescript-sdk/commit/b552101be2e060deff5ab065ec7dc557bf439f18)) +* **monitors:** support browser actions on page monitors ([#1365](https://github.com/context-dot-dev/context-typescript-sdk/issues/1365)) ([9c4d8c6](https://github.com/context-dot-dev/context-typescript-sdk/commit/9c4d8c6a032ab485a2dacb8e596641e69b910dad)) +* **scrape:** default cache age to three days and allow one year ([#1339](https://github.com/context-dot-dev/context-typescript-sdk/issues/1339)) ([56cf963](https://github.com/context-dot-dev/context-typescript-sdk/commit/56cf963833d23e8e663cea0cb241007b4f4e99f2)) +* **search:** add highlights to web search and bill page reads per 10 results ([#1387](https://github.com/context-dot-dev/context-typescript-sdk/issues/1387)) ([9a4d3cf](https://github.com/context-dot-dev/context-typescript-sdk/commit/9a4d3cfbd20e9181b84b5b60079cc232f0b94ae0)) +* **web-search:** extend page cache defaults ([#1408](https://github.com/context-dot-dev/context-typescript-sdk/issues/1408)) ([47f5a8e](https://github.com/context-dot-dev/context-typescript-sdk/commit/47f5a8e7dda03ff3d4507d3e45030d2e05ec3a69)) + + +### Bug Fixes + +* **api:** document search domain limits and clarify scrape parameter errors ([#1388](https://github.com/context-dot-dev/context-typescript-sdk/issues/1388)) ([d5f9ce1](https://github.com/context-dot-dev/context-typescript-sdk/commit/d5f9ce1b09edf45122372dfcbd1cebaa6108b90e)) +* **scrape:** resolve extracted URLs from source references ([#1333](https://github.com/context-dot-dev/context-typescript-sdk/issues/1333)) ([51b131b](https://github.com/context-dot-dev/context-typescript-sdk/commit/51b131b2c12a8903abeca139a66c070c64040304)) + + +### Documentation + +* **openapi:** complete concise API reference metadata ([#1329](https://github.com/context-dot-dev/context-typescript-sdk/issues/1329)) ([790d1f4](https://github.com/context-dot-dev/context-typescript-sdk/commit/790d1f42e0cd523501a3e7d038be664c64929765)) +* **scrape:** rename endpoint to Scrape Anything ([#1341](https://github.com/context-dot-dev/context-typescript-sdk/issues/1341)) ([84ace2a](https://github.com/context-dot-dev/context-typescript-sdk/commit/84ace2adbccb99145ab5930a3cca20aa6b71eeb7)) + ## [3.2.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.1.0...v3.2.0) (2026-09-27) diff --git a/package.json b/package.json index 500c5e4b..84c532f0 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.2.0", + "version": "3.3.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 9ca3e095..ab2e905d 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.2.0'; // x-release-please-version +export const VERSION = '3.3.0'; // x-release-please-version From bc3912b90e614a3889f8cd0449d6501bbed5c28e Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 29 Sep 2026 20:34:43 +0000 Subject: [PATCH 114/232] feat(scrape): default POST /web/scrape deadline to 90s (#1428) Stainless-Generated-From: 0390127639eff4d41a6fdb16f00c70be8ed5c060 --- src/resources/web.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 338a7fc4..37e99d3a 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2338,7 +2338,7 @@ export interface WebScrapeParams { tags?: Array; /** - * Deadline for the whole request. Defaults to 60000 ms with `fail`. Fixed waits + * Deadline for the whole request. Defaults to 90000 ms with `fail`. Fixed waits * must end before it. */ timeoutOpts?: WebScrapeParams.TimeoutOpts; @@ -2752,7 +2752,7 @@ export namespace WebScrapeParams { } /** - * Deadline for the whole request. Defaults to 60000 ms with `fail`. Fixed waits + * Deadline for the whole request. Defaults to 90000 ms with `fail`. Fixed waits * must end before it. */ export interface TimeoutOpts { From 0390127639eff4d41a6fdb16f00c70be8ed5c060 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 29 Sep 2026 20:34:43 +0000 Subject: [PATCH 115/232] seal --- .release-please-manifest.json | 2 +- CHANGELOG.md | 24 ++++++++++++++++++++++++ package.json | 2 +- src/resources/web.ts | 4 ++-- src/version.ts | 2 +- 5 files changed, 29 insertions(+), 5 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 95a37e3e..6110c0f0 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.2.0" + ".": "3.3.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 21b367fc..edcd7321 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,29 @@ # Changelog +## [3.3.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.2.0...v3.3.0) (2026-09-29) + + +### Features + +* **answers:** route people and company research with faster answers ([#1336](https://github.com/context-dot-dev/context-typescript-sdk/issues/1336)) ([8c27f11](https://github.com/context-dot-dev/context-typescript-sdk/commit/8c27f11e9869c560e48733e7eea567bcaac4f68b)) +* **api:** explain failed scrape outputs and fix agent-reported bugs ([#1360](https://github.com/context-dot-dev/context-typescript-sdk/issues/1360)) ([b552101](https://github.com/context-dot-dev/context-typescript-sdk/commit/b552101be2e060deff5ab065ec7dc557bf439f18)) +* **monitors:** support browser actions on page monitors ([#1365](https://github.com/context-dot-dev/context-typescript-sdk/issues/1365)) ([9c4d8c6](https://github.com/context-dot-dev/context-typescript-sdk/commit/9c4d8c6a032ab485a2dacb8e596641e69b910dad)) +* **scrape:** default cache age to three days and allow one year ([#1339](https://github.com/context-dot-dev/context-typescript-sdk/issues/1339)) ([56cf963](https://github.com/context-dot-dev/context-typescript-sdk/commit/56cf963833d23e8e663cea0cb241007b4f4e99f2)) +* **search:** add highlights to web search and bill page reads per 10 results ([#1387](https://github.com/context-dot-dev/context-typescript-sdk/issues/1387)) ([9a4d3cf](https://github.com/context-dot-dev/context-typescript-sdk/commit/9a4d3cfbd20e9181b84b5b60079cc232f0b94ae0)) +* **web-search:** extend page cache defaults ([#1408](https://github.com/context-dot-dev/context-typescript-sdk/issues/1408)) ([47f5a8e](https://github.com/context-dot-dev/context-typescript-sdk/commit/47f5a8e7dda03ff3d4507d3e45030d2e05ec3a69)) + + +### Bug Fixes + +* **api:** document search domain limits and clarify scrape parameter errors ([#1388](https://github.com/context-dot-dev/context-typescript-sdk/issues/1388)) ([d5f9ce1](https://github.com/context-dot-dev/context-typescript-sdk/commit/d5f9ce1b09edf45122372dfcbd1cebaa6108b90e)) +* **scrape:** resolve extracted URLs from source references ([#1333](https://github.com/context-dot-dev/context-typescript-sdk/issues/1333)) ([51b131b](https://github.com/context-dot-dev/context-typescript-sdk/commit/51b131b2c12a8903abeca139a66c070c64040304)) + + +### Documentation + +* **openapi:** complete concise API reference metadata ([#1329](https://github.com/context-dot-dev/context-typescript-sdk/issues/1329)) ([790d1f4](https://github.com/context-dot-dev/context-typescript-sdk/commit/790d1f42e0cd523501a3e7d038be664c64929765)) +* **scrape:** rename endpoint to Scrape Anything ([#1341](https://github.com/context-dot-dev/context-typescript-sdk/issues/1341)) ([84ace2a](https://github.com/context-dot-dev/context-typescript-sdk/commit/84ace2adbccb99145ab5930a3cca20aa6b71eeb7)) + ## [3.2.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.1.0...v3.2.0) (2026-09-27) diff --git a/package.json b/package.json index 500c5e4b..84c532f0 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.2.0", + "version": "3.3.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/resources/web.ts b/src/resources/web.ts index 338a7fc4..37e99d3a 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2338,7 +2338,7 @@ export interface WebScrapeParams { tags?: Array; /** - * Deadline for the whole request. Defaults to 60000 ms with `fail`. Fixed waits + * Deadline for the whole request. Defaults to 90000 ms with `fail`. Fixed waits * must end before it. */ timeoutOpts?: WebScrapeParams.TimeoutOpts; @@ -2752,7 +2752,7 @@ export namespace WebScrapeParams { } /** - * Deadline for the whole request. Defaults to 60000 ms with `fail`. Fixed waits + * Deadline for the whole request. Defaults to 90000 ms with `fail`. Fixed waits * must end before it. */ export interface TimeoutOpts { diff --git a/src/version.ts b/src/version.ts index 9ca3e095..ab2e905d 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.2.0'; // x-release-please-version +export const VERSION = '3.3.0'; // x-release-please-version From 889ef2055c8ba9e7f956990fe5a9237e2993af82 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 29 Sep 2026 21:17:01 +0000 Subject: [PATCH 116/232] feat(scrape): add productParams.dedupeImages, always run product AI fallback (#1423) Stainless-Generated-From: f7706e782cf19a2d3643be4ad44db69c29864b23 --- src/resources/web.ts | 4 ++-- tests/api-resources/web.test.ts | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 37e99d3a..b305e490 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2503,9 +2503,9 @@ export namespace WebScrapeParams { */ export interface ProductParams { /** - * Use an AI model when the page has no structured product data. + * Drop visually duplicate product images, keeping the largest copy. */ - useAIFallback?: boolean; + dedupeImages?: boolean; } /** diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 1a3328eb..9c05bb09 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -173,7 +173,7 @@ describe('resource web', () => { }, }, }, - productParams: { useAIFallback: true }, + productParams: { dedupeImages: true }, screenshotParams: { area: 'viewport', format: 'png' }, sharedParams: { actions: [{ action: 'Click the product details tab', type: 'perform' }], From f7706e782cf19a2d3643be4ad44db69c29864b23 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 29 Sep 2026 21:17:01 +0000 Subject: [PATCH 117/232] seal --- src/resources/web.ts | 4 ++-- tests/api-resources/web.test.ts | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 37e99d3a..b305e490 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2503,9 +2503,9 @@ export namespace WebScrapeParams { */ export interface ProductParams { /** - * Use an AI model when the page has no structured product data. + * Drop visually duplicate product images, keeping the largest copy. */ - useAIFallback?: boolean; + dedupeImages?: boolean; } /** diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 1a3328eb..9c05bb09 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -173,7 +173,7 @@ describe('resource web', () => { }, }, }, - productParams: { useAIFallback: true }, + productParams: { dedupeImages: true }, screenshotParams: { area: 'viewport', format: 'png' }, sharedParams: { actions: [{ action: 'Click the product details tab', type: 'perform' }], From 91e8d5e529c51b2b66554d877f756acf833a6366 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 30 Sep 2026 01:54:38 +0000 Subject: [PATCH 118/232] feat(scrape): accept documents up to 50 MB (#1436) Stainless-Generated-From: f7a025870632ba0fa20d1fc157ad2f3e99203f42 --- src/resources/web.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index b305e490..aac43cca 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1017,7 +1017,7 @@ export namespace WebScrapeResponse { export namespace Bytes { export interface Data { /** - * Body as base64, after HTTP decompression. Up to 20 MiB decoded. + * Body as base64, after HTTP decompression. Up to 50 MiB decoded. */ base64: string; From f7a025870632ba0fa20d1fc157ad2f3e99203f42 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 30 Sep 2026 01:54:38 +0000 Subject: [PATCH 119/232] seal --- src/resources/web.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index b305e490..aac43cca 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1017,7 +1017,7 @@ export namespace WebScrapeResponse { export namespace Bytes { export interface Data { /** - * Body as base64, after HTTP decompression. Up to 20 MiB decoded. + * Body as base64, after HTTP decompression. Up to 50 MiB decoded. */ base64: string; From f9b8c6db3acad05121e5445207b05af08c69dfd7 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 30 Sep 2026 02:04:45 +0000 Subject: [PATCH 120/232] feat(logs): serve request logs at /org/logs (#1442) Stainless-Generated-From: c9a4427370704a652b726e5611d62abdf6dd7bd6 --- api.md | 4 ++-- src/resources/logs.ts | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api.md b/api.md index 43bc7eb2..ed4b2339 100644 --- a/api.md +++ b/api.md @@ -183,8 +183,8 @@ Types: Methods: -- client.logs.retrieve(requestID) -> LogRetrieveResponse -- client.logs.list({ ...params }) -> LogListResponse +- client.logs.retrieve(requestID) -> LogRetrieveResponse +- client.logs.list({ ...params }) -> LogListResponse # Feedback diff --git a/src/resources/logs.ts b/src/resources/logs.ts index 14f71a1c..08c45928 100644 --- a/src/resources/logs.ts +++ b/src/resources/logs.ts @@ -13,7 +13,7 @@ export class Logs extends APIResource { * Retrieve a request’s metadata, retained input, and response. */ retrieve(requestID: string, options?: RequestOptions): APIPromise { - return this._client.get(path`/logs/${requestID}`, options); + return this._client.get(path`/org/logs/${requestID}`, options); } /** @@ -21,7 +21,7 @@ export class Logs extends APIResource { * include batch settlements and monitor runs. */ list(query: LogListParams | null | undefined = {}, options?: RequestOptions): APIPromise { - return this._client.get('/logs', { query, ...options }); + return this._client.get('/org/logs', { query, ...options }); } } From c9a4427370704a652b726e5611d62abdf6dd7bd6 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 30 Sep 2026 02:04:45 +0000 Subject: [PATCH 121/232] seal --- api.md | 4 ++-- src/resources/logs.ts | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api.md b/api.md index 43bc7eb2..ed4b2339 100644 --- a/api.md +++ b/api.md @@ -183,8 +183,8 @@ Types: Methods: -- client.logs.retrieve(requestID) -> LogRetrieveResponse -- client.logs.list({ ...params }) -> LogListResponse +- client.logs.retrieve(requestID) -> LogRetrieveResponse +- client.logs.list({ ...params }) -> LogListResponse # Feedback diff --git a/src/resources/logs.ts b/src/resources/logs.ts index 14f71a1c..08c45928 100644 --- a/src/resources/logs.ts +++ b/src/resources/logs.ts @@ -13,7 +13,7 @@ export class Logs extends APIResource { * Retrieve a request’s metadata, retained input, and response. */ retrieve(requestID: string, options?: RequestOptions): APIPromise { - return this._client.get(path`/logs/${requestID}`, options); + return this._client.get(path`/org/logs/${requestID}`, options); } /** @@ -21,7 +21,7 @@ export class Logs extends APIResource { * include batch settlements and monitor runs. */ list(query: LogListParams | null | undefined = {}, options?: RequestOptions): APIPromise { - return this._client.get('/logs', { query, ...options }); + return this._client.get('/org/logs', { query, ...options }); } } From 7020c30b863e8b5ecdb669a763ecf378172ff674 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 30 Sep 2026 07:50:10 +0000 Subject: [PATCH 122/232] fix(api): derive OpenAPI request docs from runtime Zod schemas (#1421) Stainless-Generated-From: 4deb712a9b2f5dab4d658a7532b53bb2b9521252 --- src/resources/batch.ts | 53 ++- src/resources/brand.ts | 572 +++++++++++++++++++++++++++++- src/resources/parse.ts | 6 +- src/resources/web.ts | 30 +- tests/api-resources/batch.test.ts | 4 +- tests/api-resources/web.test.ts | 8 +- 6 files changed, 608 insertions(+), 65 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index c8ecbb91..ee847ef8 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -1310,9 +1310,10 @@ export interface BatchListParams { status?: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; /** - * Comma-separated list of tags to filter by (matches batches having any of them). + * Tags to filter by (matches batches having any of them). Pass repeated `tags` + * params or one comma-separated list, e.g. `tags=docs,competitor`. */ - tags?: string; + tags?: string | Array; } export interface BatchGetResultsParams { @@ -1664,8 +1665,7 @@ export namespace BatchSubmitParams { maxAgeMs?: number | null; /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ pdf?: Options.Pdf; @@ -1692,13 +1692,12 @@ export namespace BatchSubmitParams { export namespace Options { /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. */ end?: number; @@ -1713,7 +1712,7 @@ export namespace BatchSubmitParams { shouldParse?: boolean; /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * First 1-based PDF page to parse. */ start?: number; } @@ -1994,8 +1993,7 @@ export namespace BatchSubmitParams { maxAgeMs?: number | null; /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ pdf?: Options.Pdf; @@ -2017,13 +2015,12 @@ export namespace BatchSubmitParams { export namespace Options { /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. */ end?: number; @@ -2038,7 +2035,7 @@ export namespace BatchSubmitParams { shouldParse?: boolean; /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * First 1-based PDF page to parse. */ start?: number; } @@ -2418,8 +2415,7 @@ export namespace BatchSubmitParams { maxAgeMs?: number | null; /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ pdf?: Options.Pdf; @@ -2446,13 +2442,12 @@ export namespace BatchSubmitParams { export namespace Options { /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. */ end?: number; @@ -2467,7 +2462,7 @@ export namespace BatchSubmitParams { shouldParse?: boolean; /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * First 1-based PDF page to parse. */ start?: number; } @@ -2815,8 +2810,7 @@ export namespace BatchSubmitParams { maxAgeMs?: number | null; /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ pdf?: Options.Pdf; @@ -2838,13 +2832,12 @@ export namespace BatchSubmitParams { export namespace Options { /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. */ end?: number; @@ -2859,7 +2852,7 @@ export namespace BatchSubmitParams { shouldParse?: boolean; /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * First 1-based PDF page to parse. */ start?: number; } diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 34aba28d..7a104fef 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -1132,10 +1132,249 @@ export declare namespace BrandRetrieveParams { type: 'by_name'; /** - * Optional country code hint (GL parameter) to specify the country when looking up - * by company name. - */ - country_gl?: string; + * Two-letter ISO 3166-1 alpha-2 country code (GL parameter) used to localize + * search. + */ + country_gl?: + | 'af' + | 'al' + | 'dz' + | 'as' + | 'ad' + | 'ao' + | 'ai' + | 'aq' + | 'ag' + | 'ar' + | 'am' + | 'aw' + | 'au' + | 'at' + | 'az' + | 'bs' + | 'bh' + | 'bd' + | 'bb' + | 'by' + | 'be' + | 'bz' + | 'bj' + | 'bm' + | 'bt' + | 'bo' + | 'ba' + | 'bw' + | 'bv' + | 'br' + | 'io' + | 'bn' + | 'bg' + | 'bf' + | 'bi' + | 'kh' + | 'cm' + | 'ca' + | 'cv' + | 'ky' + | 'cf' + | 'td' + | 'cl' + | 'cn' + | 'cx' + | 'cc' + | 'co' + | 'km' + | 'cg' + | 'cd' + | 'ck' + | 'cr' + | 'ci' + | 'hr' + | 'cu' + | 'cy' + | 'cz' + | 'dk' + | 'dj' + | 'dm' + | 'do' + | 'ec' + | 'eg' + | 'sv' + | 'gq' + | 'er' + | 'ee' + | 'et' + | 'fk' + | 'fo' + | 'fj' + | 'fi' + | 'fr' + | 'gf' + | 'pf' + | 'tf' + | 'ga' + | 'gm' + | 'ge' + | 'de' + | 'gh' + | 'gi' + | 'gr' + | 'gl' + | 'gd' + | 'gp' + | 'gu' + | 'gt' + | 'gn' + | 'gw' + | 'gy' + | 'ht' + | 'hm' + | 'va' + | 'hn' + | 'hk' + | 'hu' + | 'is' + | 'in' + | 'id' + | 'ir' + | 'iq' + | 'ie' + | 'il' + | 'it' + | 'jm' + | 'jp' + | 'jo' + | 'kz' + | 'ke' + | 'ki' + | 'kp' + | 'kr' + | 'kw' + | 'kg' + | 'la' + | 'lv' + | 'lb' + | 'ls' + | 'lr' + | 'ly' + | 'li' + | 'lt' + | 'lu' + | 'mo' + | 'mk' + | 'mg' + | 'mw' + | 'my' + | 'mv' + | 'ml' + | 'mt' + | 'mh' + | 'mq' + | 'mr' + | 'mu' + | 'yt' + | 'mx' + | 'fm' + | 'md' + | 'mc' + | 'mn' + | 'ms' + | 'ma' + | 'mz' + | 'mm' + | 'na' + | 'nr' + | 'np' + | 'nl' + | 'an' + | 'nc' + | 'nz' + | 'ni' + | 'ne' + | 'ng' + | 'nu' + | 'nf' + | 'mp' + | 'no' + | 'om' + | 'pk' + | 'pw' + | 'ps' + | 'pa' + | 'pg' + | 'py' + | 'pe' + | 'ph' + | 'pn' + | 'pl' + | 'pt' + | 'pr' + | 'qa' + | 're' + | 'ro' + | 'ru' + | 'rw' + | 'sh' + | 'kn' + | 'lc' + | 'pm' + | 'vc' + | 'ws' + | 'sm' + | 'st' + | 'sa' + | 'sn' + | 'rs' + | 'sc' + | 'sl' + | 'sg' + | 'sk' + | 'si' + | 'sb' + | 'so' + | 'za' + | 'gs' + | 'es' + | 'lk' + | 'sd' + | 'sr' + | 'sj' + | 'sz' + | 'se' + | 'ch' + | 'sy' + | 'tw' + | 'tj' + | 'tz' + | 'th' + | 'tl' + | 'tg' + | 'tk' + | 'to' + | 'tt' + | 'tn' + | 'tr' + | 'tm' + | 'tc' + | 'tv' + | 'ug' + | 'ua' + | 'ae' + | 'gb' + | 'us' + | 'um' + | 'uy' + | 'uz' + | 'vu' + | 've' + | 'vn' + | 'vg' + | 'vi' + | 'wf' + | 'eh' + | 'ye' + | 'zm' + | 'zw'; force_language?: | 'afrikaans' @@ -1631,9 +1870,81 @@ export declare namespace BrandRetrieveParams { tags?: Array; /** - * Optional stock exchange for the ticker. Defaults to NASDAQ if not specified. - */ - ticker_exchange?: string; + * Stock exchange code. + */ + ticker_exchange?: + | 'AMEX' + | 'AMS' + | 'AQS' + | 'ASX' + | 'ATH' + | 'BER' + | 'BME' + | 'BRU' + | 'BSE' + | 'BUD' + | 'BUE' + | 'BVC' + | 'CBOE' + | 'CNQ' + | 'CPH' + | 'DFM' + | 'DOH' + | 'DUB' + | 'DUS' + | 'DXE' + | 'EGX' + | 'FSX' + | 'HAM' + | 'HEL' + | 'HKSE' + | 'HOSE' + | 'ICE' + | 'IOB' + | 'IST' + | 'JKT' + | 'JNB' + | 'JPX' + | 'KLS' + | 'KOE' + | 'KSC' + | 'KUW' + | 'LIS' + | 'LSE' + | 'MCX' + | 'MEX' + | 'MIL' + | 'MUN' + | 'NASDAQ' + | 'NEO' + | 'NSE' + | 'NYSE' + | 'NZE' + | 'OSL' + | 'OTC' + | 'PAR' + | 'PNK' + | 'PRA' + | 'RIS' + | 'SAO' + | 'SAU' + | 'SES' + | 'SET' + | 'SGO' + | 'SHH' + | 'SHZ' + | 'SIX' + | 'STO' + | 'STU' + | 'TAI' + | 'TAL' + | 'TLV' + | 'TSX' + | 'TSXV' + | 'TWO' + | 'VIE' + | 'WSE' + | 'XETRA'; /** * Request deadline and what to return when it passes. @@ -1718,10 +2029,249 @@ export declare namespace BrandRetrieveParams { city?: string; /** - * Optional country code hint (GL parameter) to specify the country when - * identifying a transaction. - */ - country_gl?: string; + * Two-letter ISO 3166-1 alpha-2 country code (GL parameter) used to localize + * search. + */ + country_gl?: + | 'af' + | 'al' + | 'dz' + | 'as' + | 'ad' + | 'ao' + | 'ai' + | 'aq' + | 'ag' + | 'ar' + | 'am' + | 'aw' + | 'au' + | 'at' + | 'az' + | 'bs' + | 'bh' + | 'bd' + | 'bb' + | 'by' + | 'be' + | 'bz' + | 'bj' + | 'bm' + | 'bt' + | 'bo' + | 'ba' + | 'bw' + | 'bv' + | 'br' + | 'io' + | 'bn' + | 'bg' + | 'bf' + | 'bi' + | 'kh' + | 'cm' + | 'ca' + | 'cv' + | 'ky' + | 'cf' + | 'td' + | 'cl' + | 'cn' + | 'cx' + | 'cc' + | 'co' + | 'km' + | 'cg' + | 'cd' + | 'ck' + | 'cr' + | 'ci' + | 'hr' + | 'cu' + | 'cy' + | 'cz' + | 'dk' + | 'dj' + | 'dm' + | 'do' + | 'ec' + | 'eg' + | 'sv' + | 'gq' + | 'er' + | 'ee' + | 'et' + | 'fk' + | 'fo' + | 'fj' + | 'fi' + | 'fr' + | 'gf' + | 'pf' + | 'tf' + | 'ga' + | 'gm' + | 'ge' + | 'de' + | 'gh' + | 'gi' + | 'gr' + | 'gl' + | 'gd' + | 'gp' + | 'gu' + | 'gt' + | 'gn' + | 'gw' + | 'gy' + | 'ht' + | 'hm' + | 'va' + | 'hn' + | 'hk' + | 'hu' + | 'is' + | 'in' + | 'id' + | 'ir' + | 'iq' + | 'ie' + | 'il' + | 'it' + | 'jm' + | 'jp' + | 'jo' + | 'kz' + | 'ke' + | 'ki' + | 'kp' + | 'kr' + | 'kw' + | 'kg' + | 'la' + | 'lv' + | 'lb' + | 'ls' + | 'lr' + | 'ly' + | 'li' + | 'lt' + | 'lu' + | 'mo' + | 'mk' + | 'mg' + | 'mw' + | 'my' + | 'mv' + | 'ml' + | 'mt' + | 'mh' + | 'mq' + | 'mr' + | 'mu' + | 'yt' + | 'mx' + | 'fm' + | 'md' + | 'mc' + | 'mn' + | 'ms' + | 'ma' + | 'mz' + | 'mm' + | 'na' + | 'nr' + | 'np' + | 'nl' + | 'an' + | 'nc' + | 'nz' + | 'ni' + | 'ne' + | 'ng' + | 'nu' + | 'nf' + | 'mp' + | 'no' + | 'om' + | 'pk' + | 'pw' + | 'ps' + | 'pa' + | 'pg' + | 'py' + | 'pe' + | 'ph' + | 'pn' + | 'pl' + | 'pt' + | 'pr' + | 'qa' + | 're' + | 'ro' + | 'ru' + | 'rw' + | 'sh' + | 'kn' + | 'lc' + | 'pm' + | 'vc' + | 'ws' + | 'sm' + | 'st' + | 'sa' + | 'sn' + | 'rs' + | 'sc' + | 'sl' + | 'sg' + | 'sk' + | 'si' + | 'sb' + | 'so' + | 'za' + | 'gs' + | 'es' + | 'lk' + | 'sd' + | 'sr' + | 'sj' + | 'sz' + | 'se' + | 'ch' + | 'sy' + | 'tw' + | 'tj' + | 'tz' + | 'th' + | 'tl' + | 'tg' + | 'tk' + | 'to' + | 'tt' + | 'tn' + | 'tr' + | 'tm' + | 'tc' + | 'tv' + | 'ug' + | 'ua' + | 'ae' + | 'gb' + | 'us' + | 'um' + | 'uy' + | 'uz' + | 'vu' + | 've' + | 'vn' + | 'vg' + | 'vi' + | 'wf' + | 'eh' + | 'ye' + | 'zm' + | 'zw'; force_language?: | 'afrikaans' diff --git a/src/resources/parse.ts b/src/resources/parse.ts index 19dc04e4..0a48c26b 100644 --- a/src/resources/parse.ts +++ b/src/resources/parse.ts @@ -266,13 +266,13 @@ export namespace ParseHandleParams { */ export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. */ end?: number; /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * First 1-based PDF page to parse. */ start?: number; } diff --git a/src/resources/web.ts b/src/resources/web.ts index aac43cca..4ff39cdc 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -3390,7 +3390,7 @@ export interface WebSearchParams { * Passages from each result page that are relevant to the query. Pages are read * with the `markdownOptions` settings. */ - highlightsOptions?: WebSearchParams.HighlightsOptions; + highlightsOptions?: WebSearchParams.HighlightsOptions | null; /** * Allowlist — only return results from these domains. Up to 100 domains. Example: @@ -3401,7 +3401,7 @@ export interface WebSearchParams { /** * Inline Markdown scraping for each result. Set `enabled: true` to activate. */ - markdownOptions?: WebSearchParams.MarkdownOptions; + markdownOptions?: WebSearchParams.MarkdownOptions | null; /** * Number of results to request and return (10–100). Defaults to 10. @@ -3477,10 +3477,10 @@ export namespace WebSearchParams { * only highlights are requested. Explicit values override either default. Maximum: * 365 days. Set to 0 to force a fresh scrape. */ - maxAgeMs?: number; + maxAgeMs?: number | null; /** - * PDF handling. Use start/end to bound text extraction and OCR to a page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ pdf?: MarkdownOptions.Pdf; @@ -3503,12 +3503,12 @@ export namespace WebSearchParams { * Extra wait after page load before rendering, in ms (0–30000). Useful for * JS-heavy pages. */ - waitForMs?: number; + waitForMs?: number | null; } export namespace MarkdownOptions { /** - * PDF handling. Use start/end to bound text extraction and OCR to a page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ export interface Pdf { /** @@ -3523,7 +3523,7 @@ export namespace WebSearchParams { shouldParse?: boolean; /** - * First PDF page to parse (1-based, inclusive). Defaults to page 1. + * First 1-based PDF page to parse. */ start?: number; } @@ -3780,7 +3780,7 @@ export interface WebWebCrawlMdParams { /** * Remove matching elements after inclusions. Exclusions take precedence. */ - excludeSelectors?: Array; + excludeSelectors?: Array | null; /** * When true, follow links on subdomains of the starting URL's domain (e.g. @@ -3808,12 +3808,12 @@ export interface WebWebCrawlMdParams { /** * Keep matching HTML subtrees before converting each page to Markdown. */ - includeSelectors?: Array; + includeSelectors?: Array | null; /** * Maximum cache age in milliseconds. Defaults to 1 day; `0` fetches fresh. */ - maxAgeMs?: number; + maxAgeMs?: number | null; /** * Maximum link depth from the starting URL (0 = only the starting page) @@ -3874,7 +3874,7 @@ export interface WebWebCrawlMdParams { * Browser wait time in milliseconds after initial page load for each crawled page. * Defaults to 3500 (3.5 seconds). Min: 0. Max: 30000 (30 seconds). */ - waitForMs?: number; + waitForMs?: number | null; /** * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless @@ -3889,13 +3889,13 @@ export namespace WebWebCrawlMdParams { */ export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. */ end?: number; /** - * Read scanned PDF pages with OCR; preserve pages that already contain text. + * Read scanned PDF pages with OCR; preserve pages that already have text. */ ocr?: boolean; @@ -3906,7 +3906,7 @@ export namespace WebWebCrawlMdParams { shouldParse?: boolean; /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * First 1-based PDF page to parse. */ start?: number; } diff --git a/tests/api-resources/batch.test.ts b/tests/api-resources/batch.test.ts index 0d04e037..393f6e97 100644 --- a/tests/api-resources/batch.test.ts +++ b/tests/api-resources/batch.test.ts @@ -92,7 +92,7 @@ describe('resource batch', () => { await expect( client.batch.getResults( 'batch_9f2c8a', - { cursor: 'cursor', limit: 1 }, + { cursor: '321669910225:155771193', limit: 1 }, { path: '/_stainless_unknown_path' }, ), ).rejects.toThrow(ContextDev.NotFoundError); @@ -166,7 +166,7 @@ describe('resource batch', () => { url: 'https://example.com', retry: { delays_seconds: [10, 60, 300, 1800, 7200, 21600, 57600] }, }, - webhookUrl: 'webhookUrl', + webhookUrl: 'https://example.com', 'Idempotency-Key': 'Idempotency-Key', }); }); diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 9c05bb09..fe4a29ee 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -260,10 +260,10 @@ describe('resource web', () => { const response = await client.web.search({ query: 'Stripe API authentication', country: 'af', - excludeDomains: ['string'], + excludeDomains: ['xxx'], freshness: 'last_24_hours', highlightsOptions: { enabled: true, maxCharacters: 100 }, - includeDomains: ['string'], + includeDomains: ['xxx'], markdownOptions: { enabled: true, includeFrames: true, @@ -305,12 +305,12 @@ describe('resource web', () => { const response = await client.web.webCrawlMd({ url: 'https://example.com', country: 'de', - excludeSelectors: ['string'], + excludeSelectors: ['x'], followSubdomains: true, includeFrames: true, includeImages: true, includeLinks: true, - includeSelectors: ['string'], + includeSelectors: ['x'], maxAgeMs: 0, maxDepth: 0, maxPages: 10, From 4deb712a9b2f5dab4d658a7532b53bb2b9521252 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 30 Sep 2026 07:50:10 +0000 Subject: [PATCH 123/232] seal --- src/resources/batch.ts | 53 ++- src/resources/brand.ts | 572 +++++++++++++++++++++++++++++- src/resources/parse.ts | 6 +- src/resources/web.ts | 30 +- tests/api-resources/batch.test.ts | 4 +- tests/api-resources/web.test.ts | 8 +- 6 files changed, 608 insertions(+), 65 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index c8ecbb91..ee847ef8 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -1310,9 +1310,10 @@ export interface BatchListParams { status?: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; /** - * Comma-separated list of tags to filter by (matches batches having any of them). + * Tags to filter by (matches batches having any of them). Pass repeated `tags` + * params or one comma-separated list, e.g. `tags=docs,competitor`. */ - tags?: string; + tags?: string | Array; } export interface BatchGetResultsParams { @@ -1664,8 +1665,7 @@ export namespace BatchSubmitParams { maxAgeMs?: number | null; /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ pdf?: Options.Pdf; @@ -1692,13 +1692,12 @@ export namespace BatchSubmitParams { export namespace Options { /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. */ end?: number; @@ -1713,7 +1712,7 @@ export namespace BatchSubmitParams { shouldParse?: boolean; /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * First 1-based PDF page to parse. */ start?: number; } @@ -1994,8 +1993,7 @@ export namespace BatchSubmitParams { maxAgeMs?: number | null; /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ pdf?: Options.Pdf; @@ -2017,13 +2015,12 @@ export namespace BatchSubmitParams { export namespace Options { /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. */ end?: number; @@ -2038,7 +2035,7 @@ export namespace BatchSubmitParams { shouldParse?: boolean; /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * First 1-based PDF page to parse. */ start?: number; } @@ -2418,8 +2415,7 @@ export namespace BatchSubmitParams { maxAgeMs?: number | null; /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ pdf?: Options.Pdf; @@ -2446,13 +2442,12 @@ export namespace BatchSubmitParams { export namespace Options { /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. */ end?: number; @@ -2467,7 +2462,7 @@ export namespace BatchSubmitParams { shouldParse?: boolean; /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * First 1-based PDF page to parse. */ start?: number; } @@ -2815,8 +2810,7 @@ export namespace BatchSubmitParams { maxAgeMs?: number | null; /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ pdf?: Options.Pdf; @@ -2838,13 +2832,12 @@ export namespace BatchSubmitParams { export namespace Options { /** - * PDF parsing controls. Use start/end to limit text extraction and embedded-image - * detection/OCR to an inclusive 1-based page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. */ end?: number; @@ -2859,7 +2852,7 @@ export namespace BatchSubmitParams { shouldParse?: boolean; /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * First 1-based PDF page to parse. */ start?: number; } diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 34aba28d..7a104fef 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -1132,10 +1132,249 @@ export declare namespace BrandRetrieveParams { type: 'by_name'; /** - * Optional country code hint (GL parameter) to specify the country when looking up - * by company name. - */ - country_gl?: string; + * Two-letter ISO 3166-1 alpha-2 country code (GL parameter) used to localize + * search. + */ + country_gl?: + | 'af' + | 'al' + | 'dz' + | 'as' + | 'ad' + | 'ao' + | 'ai' + | 'aq' + | 'ag' + | 'ar' + | 'am' + | 'aw' + | 'au' + | 'at' + | 'az' + | 'bs' + | 'bh' + | 'bd' + | 'bb' + | 'by' + | 'be' + | 'bz' + | 'bj' + | 'bm' + | 'bt' + | 'bo' + | 'ba' + | 'bw' + | 'bv' + | 'br' + | 'io' + | 'bn' + | 'bg' + | 'bf' + | 'bi' + | 'kh' + | 'cm' + | 'ca' + | 'cv' + | 'ky' + | 'cf' + | 'td' + | 'cl' + | 'cn' + | 'cx' + | 'cc' + | 'co' + | 'km' + | 'cg' + | 'cd' + | 'ck' + | 'cr' + | 'ci' + | 'hr' + | 'cu' + | 'cy' + | 'cz' + | 'dk' + | 'dj' + | 'dm' + | 'do' + | 'ec' + | 'eg' + | 'sv' + | 'gq' + | 'er' + | 'ee' + | 'et' + | 'fk' + | 'fo' + | 'fj' + | 'fi' + | 'fr' + | 'gf' + | 'pf' + | 'tf' + | 'ga' + | 'gm' + | 'ge' + | 'de' + | 'gh' + | 'gi' + | 'gr' + | 'gl' + | 'gd' + | 'gp' + | 'gu' + | 'gt' + | 'gn' + | 'gw' + | 'gy' + | 'ht' + | 'hm' + | 'va' + | 'hn' + | 'hk' + | 'hu' + | 'is' + | 'in' + | 'id' + | 'ir' + | 'iq' + | 'ie' + | 'il' + | 'it' + | 'jm' + | 'jp' + | 'jo' + | 'kz' + | 'ke' + | 'ki' + | 'kp' + | 'kr' + | 'kw' + | 'kg' + | 'la' + | 'lv' + | 'lb' + | 'ls' + | 'lr' + | 'ly' + | 'li' + | 'lt' + | 'lu' + | 'mo' + | 'mk' + | 'mg' + | 'mw' + | 'my' + | 'mv' + | 'ml' + | 'mt' + | 'mh' + | 'mq' + | 'mr' + | 'mu' + | 'yt' + | 'mx' + | 'fm' + | 'md' + | 'mc' + | 'mn' + | 'ms' + | 'ma' + | 'mz' + | 'mm' + | 'na' + | 'nr' + | 'np' + | 'nl' + | 'an' + | 'nc' + | 'nz' + | 'ni' + | 'ne' + | 'ng' + | 'nu' + | 'nf' + | 'mp' + | 'no' + | 'om' + | 'pk' + | 'pw' + | 'ps' + | 'pa' + | 'pg' + | 'py' + | 'pe' + | 'ph' + | 'pn' + | 'pl' + | 'pt' + | 'pr' + | 'qa' + | 're' + | 'ro' + | 'ru' + | 'rw' + | 'sh' + | 'kn' + | 'lc' + | 'pm' + | 'vc' + | 'ws' + | 'sm' + | 'st' + | 'sa' + | 'sn' + | 'rs' + | 'sc' + | 'sl' + | 'sg' + | 'sk' + | 'si' + | 'sb' + | 'so' + | 'za' + | 'gs' + | 'es' + | 'lk' + | 'sd' + | 'sr' + | 'sj' + | 'sz' + | 'se' + | 'ch' + | 'sy' + | 'tw' + | 'tj' + | 'tz' + | 'th' + | 'tl' + | 'tg' + | 'tk' + | 'to' + | 'tt' + | 'tn' + | 'tr' + | 'tm' + | 'tc' + | 'tv' + | 'ug' + | 'ua' + | 'ae' + | 'gb' + | 'us' + | 'um' + | 'uy' + | 'uz' + | 'vu' + | 've' + | 'vn' + | 'vg' + | 'vi' + | 'wf' + | 'eh' + | 'ye' + | 'zm' + | 'zw'; force_language?: | 'afrikaans' @@ -1631,9 +1870,81 @@ export declare namespace BrandRetrieveParams { tags?: Array; /** - * Optional stock exchange for the ticker. Defaults to NASDAQ if not specified. - */ - ticker_exchange?: string; + * Stock exchange code. + */ + ticker_exchange?: + | 'AMEX' + | 'AMS' + | 'AQS' + | 'ASX' + | 'ATH' + | 'BER' + | 'BME' + | 'BRU' + | 'BSE' + | 'BUD' + | 'BUE' + | 'BVC' + | 'CBOE' + | 'CNQ' + | 'CPH' + | 'DFM' + | 'DOH' + | 'DUB' + | 'DUS' + | 'DXE' + | 'EGX' + | 'FSX' + | 'HAM' + | 'HEL' + | 'HKSE' + | 'HOSE' + | 'ICE' + | 'IOB' + | 'IST' + | 'JKT' + | 'JNB' + | 'JPX' + | 'KLS' + | 'KOE' + | 'KSC' + | 'KUW' + | 'LIS' + | 'LSE' + | 'MCX' + | 'MEX' + | 'MIL' + | 'MUN' + | 'NASDAQ' + | 'NEO' + | 'NSE' + | 'NYSE' + | 'NZE' + | 'OSL' + | 'OTC' + | 'PAR' + | 'PNK' + | 'PRA' + | 'RIS' + | 'SAO' + | 'SAU' + | 'SES' + | 'SET' + | 'SGO' + | 'SHH' + | 'SHZ' + | 'SIX' + | 'STO' + | 'STU' + | 'TAI' + | 'TAL' + | 'TLV' + | 'TSX' + | 'TSXV' + | 'TWO' + | 'VIE' + | 'WSE' + | 'XETRA'; /** * Request deadline and what to return when it passes. @@ -1718,10 +2029,249 @@ export declare namespace BrandRetrieveParams { city?: string; /** - * Optional country code hint (GL parameter) to specify the country when - * identifying a transaction. - */ - country_gl?: string; + * Two-letter ISO 3166-1 alpha-2 country code (GL parameter) used to localize + * search. + */ + country_gl?: + | 'af' + | 'al' + | 'dz' + | 'as' + | 'ad' + | 'ao' + | 'ai' + | 'aq' + | 'ag' + | 'ar' + | 'am' + | 'aw' + | 'au' + | 'at' + | 'az' + | 'bs' + | 'bh' + | 'bd' + | 'bb' + | 'by' + | 'be' + | 'bz' + | 'bj' + | 'bm' + | 'bt' + | 'bo' + | 'ba' + | 'bw' + | 'bv' + | 'br' + | 'io' + | 'bn' + | 'bg' + | 'bf' + | 'bi' + | 'kh' + | 'cm' + | 'ca' + | 'cv' + | 'ky' + | 'cf' + | 'td' + | 'cl' + | 'cn' + | 'cx' + | 'cc' + | 'co' + | 'km' + | 'cg' + | 'cd' + | 'ck' + | 'cr' + | 'ci' + | 'hr' + | 'cu' + | 'cy' + | 'cz' + | 'dk' + | 'dj' + | 'dm' + | 'do' + | 'ec' + | 'eg' + | 'sv' + | 'gq' + | 'er' + | 'ee' + | 'et' + | 'fk' + | 'fo' + | 'fj' + | 'fi' + | 'fr' + | 'gf' + | 'pf' + | 'tf' + | 'ga' + | 'gm' + | 'ge' + | 'de' + | 'gh' + | 'gi' + | 'gr' + | 'gl' + | 'gd' + | 'gp' + | 'gu' + | 'gt' + | 'gn' + | 'gw' + | 'gy' + | 'ht' + | 'hm' + | 'va' + | 'hn' + | 'hk' + | 'hu' + | 'is' + | 'in' + | 'id' + | 'ir' + | 'iq' + | 'ie' + | 'il' + | 'it' + | 'jm' + | 'jp' + | 'jo' + | 'kz' + | 'ke' + | 'ki' + | 'kp' + | 'kr' + | 'kw' + | 'kg' + | 'la' + | 'lv' + | 'lb' + | 'ls' + | 'lr' + | 'ly' + | 'li' + | 'lt' + | 'lu' + | 'mo' + | 'mk' + | 'mg' + | 'mw' + | 'my' + | 'mv' + | 'ml' + | 'mt' + | 'mh' + | 'mq' + | 'mr' + | 'mu' + | 'yt' + | 'mx' + | 'fm' + | 'md' + | 'mc' + | 'mn' + | 'ms' + | 'ma' + | 'mz' + | 'mm' + | 'na' + | 'nr' + | 'np' + | 'nl' + | 'an' + | 'nc' + | 'nz' + | 'ni' + | 'ne' + | 'ng' + | 'nu' + | 'nf' + | 'mp' + | 'no' + | 'om' + | 'pk' + | 'pw' + | 'ps' + | 'pa' + | 'pg' + | 'py' + | 'pe' + | 'ph' + | 'pn' + | 'pl' + | 'pt' + | 'pr' + | 'qa' + | 're' + | 'ro' + | 'ru' + | 'rw' + | 'sh' + | 'kn' + | 'lc' + | 'pm' + | 'vc' + | 'ws' + | 'sm' + | 'st' + | 'sa' + | 'sn' + | 'rs' + | 'sc' + | 'sl' + | 'sg' + | 'sk' + | 'si' + | 'sb' + | 'so' + | 'za' + | 'gs' + | 'es' + | 'lk' + | 'sd' + | 'sr' + | 'sj' + | 'sz' + | 'se' + | 'ch' + | 'sy' + | 'tw' + | 'tj' + | 'tz' + | 'th' + | 'tl' + | 'tg' + | 'tk' + | 'to' + | 'tt' + | 'tn' + | 'tr' + | 'tm' + | 'tc' + | 'tv' + | 'ug' + | 'ua' + | 'ae' + | 'gb' + | 'us' + | 'um' + | 'uy' + | 'uz' + | 'vu' + | 've' + | 'vn' + | 'vg' + | 'vi' + | 'wf' + | 'eh' + | 'ye' + | 'zm' + | 'zw'; force_language?: | 'afrikaans' diff --git a/src/resources/parse.ts b/src/resources/parse.ts index 19dc04e4..0a48c26b 100644 --- a/src/resources/parse.ts +++ b/src/resources/parse.ts @@ -266,13 +266,13 @@ export namespace ParseHandleParams { */ export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. */ end?: number; /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * First 1-based PDF page to parse. */ start?: number; } diff --git a/src/resources/web.ts b/src/resources/web.ts index aac43cca..4ff39cdc 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -3390,7 +3390,7 @@ export interface WebSearchParams { * Passages from each result page that are relevant to the query. Pages are read * with the `markdownOptions` settings. */ - highlightsOptions?: WebSearchParams.HighlightsOptions; + highlightsOptions?: WebSearchParams.HighlightsOptions | null; /** * Allowlist — only return results from these domains. Up to 100 domains. Example: @@ -3401,7 +3401,7 @@ export interface WebSearchParams { /** * Inline Markdown scraping for each result. Set `enabled: true` to activate. */ - markdownOptions?: WebSearchParams.MarkdownOptions; + markdownOptions?: WebSearchParams.MarkdownOptions | null; /** * Number of results to request and return (10–100). Defaults to 10. @@ -3477,10 +3477,10 @@ export namespace WebSearchParams { * only highlights are requested. Explicit values override either default. Maximum: * 365 days. Set to 0 to force a fresh scrape. */ - maxAgeMs?: number; + maxAgeMs?: number | null; /** - * PDF handling. Use start/end to bound text extraction and OCR to a page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ pdf?: MarkdownOptions.Pdf; @@ -3503,12 +3503,12 @@ export namespace WebSearchParams { * Extra wait after page load before rendering, in ms (0–30000). Useful for * JS-heavy pages. */ - waitForMs?: number; + waitForMs?: number | null; } export namespace MarkdownOptions { /** - * PDF handling. Use start/end to bound text extraction and OCR to a page range. + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. */ export interface Pdf { /** @@ -3523,7 +3523,7 @@ export namespace WebSearchParams { shouldParse?: boolean; /** - * First PDF page to parse (1-based, inclusive). Defaults to page 1. + * First 1-based PDF page to parse. */ start?: number; } @@ -3780,7 +3780,7 @@ export interface WebWebCrawlMdParams { /** * Remove matching elements after inclusions. Exclusions take precedence. */ - excludeSelectors?: Array; + excludeSelectors?: Array | null; /** * When true, follow links on subdomains of the starting URL's domain (e.g. @@ -3808,12 +3808,12 @@ export interface WebWebCrawlMdParams { /** * Keep matching HTML subtrees before converting each page to Markdown. */ - includeSelectors?: Array; + includeSelectors?: Array | null; /** * Maximum cache age in milliseconds. Defaults to 1 day; `0` fetches fresh. */ - maxAgeMs?: number; + maxAgeMs?: number | null; /** * Maximum link depth from the starting URL (0 = only the starting page) @@ -3874,7 +3874,7 @@ export interface WebWebCrawlMdParams { * Browser wait time in milliseconds after initial page load for each crawled page. * Defaults to 3500 (3.5 seconds). Min: 0. Max: 30000 (30 seconds). */ - waitForMs?: number; + waitForMs?: number | null; /** * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless @@ -3889,13 +3889,13 @@ export namespace WebWebCrawlMdParams { */ export interface Pdf { /** - * Last 1-based PDF page to parse. When omitted, parsing ends at the last page. - * Must be greater than or equal to start when both are provided. + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. */ end?: number; /** - * Read scanned PDF pages with OCR; preserve pages that already contain text. + * Read scanned PDF pages with OCR; preserve pages that already have text. */ ocr?: boolean; @@ -3906,7 +3906,7 @@ export namespace WebWebCrawlMdParams { shouldParse?: boolean; /** - * First 1-based PDF page to parse. When omitted, parsing starts at the first page. + * First 1-based PDF page to parse. */ start?: number; } diff --git a/tests/api-resources/batch.test.ts b/tests/api-resources/batch.test.ts index 0d04e037..393f6e97 100644 --- a/tests/api-resources/batch.test.ts +++ b/tests/api-resources/batch.test.ts @@ -92,7 +92,7 @@ describe('resource batch', () => { await expect( client.batch.getResults( 'batch_9f2c8a', - { cursor: 'cursor', limit: 1 }, + { cursor: '321669910225:155771193', limit: 1 }, { path: '/_stainless_unknown_path' }, ), ).rejects.toThrow(ContextDev.NotFoundError); @@ -166,7 +166,7 @@ describe('resource batch', () => { url: 'https://example.com', retry: { delays_seconds: [10, 60, 300, 1800, 7200, 21600, 57600] }, }, - webhookUrl: 'webhookUrl', + webhookUrl: 'https://example.com', 'Idempotency-Key': 'Idempotency-Key', }); }); diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 9c05bb09..fe4a29ee 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -260,10 +260,10 @@ describe('resource web', () => { const response = await client.web.search({ query: 'Stripe API authentication', country: 'af', - excludeDomains: ['string'], + excludeDomains: ['xxx'], freshness: 'last_24_hours', highlightsOptions: { enabled: true, maxCharacters: 100 }, - includeDomains: ['string'], + includeDomains: ['xxx'], markdownOptions: { enabled: true, includeFrames: true, @@ -305,12 +305,12 @@ describe('resource web', () => { const response = await client.web.webCrawlMd({ url: 'https://example.com', country: 'de', - excludeSelectors: ['string'], + excludeSelectors: ['x'], followSubdomains: true, includeFrames: true, includeImages: true, includeLinks: true, - includeSelectors: ['string'], + includeSelectors: ['x'], maxAgeMs: 0, maxDepth: 0, maxPages: 10, From 7cf578b382bd19d536cc7e63281a07d22ef01363 Mon Sep 17 00:00:00 2001 From: contextualbeer Date: Wed, 30 Sep 2026 09:51:44 +0200 Subject: [PATCH 124/232] release: 3.4.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 15 +++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 18 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 6110c0f0..9dc6cef9 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.3.0" + ".": "3.4.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index edcd7321..530311f0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,20 @@ # Changelog +## [3.4.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.3.0...v3.4.0) (2026-09-30) + + +### Features + +* **logs:** serve request logs at /org/logs ([#1442](https://github.com/context-dot-dev/context-typescript-sdk/issues/1442)) ([f9b8c6d](https://github.com/context-dot-dev/context-typescript-sdk/commit/f9b8c6db3acad05121e5445207b05af08c69dfd7)) +* **scrape:** accept documents up to 50 MB ([#1436](https://github.com/context-dot-dev/context-typescript-sdk/issues/1436)) ([91e8d5e](https://github.com/context-dot-dev/context-typescript-sdk/commit/91e8d5e529c51b2b66554d877f756acf833a6366)) +* **scrape:** add productParams.dedupeImages, always run product AI fallback ([#1423](https://github.com/context-dot-dev/context-typescript-sdk/issues/1423)) ([889ef20](https://github.com/context-dot-dev/context-typescript-sdk/commit/889ef2055c8ba9e7f956990fe5a9237e2993af82)) +* **scrape:** default POST /web/scrape deadline to 90s ([#1428](https://github.com/context-dot-dev/context-typescript-sdk/issues/1428)) ([bc3912b](https://github.com/context-dot-dev/context-typescript-sdk/commit/bc3912b90e614a3889f8cd0449d6501bbed5c28e)) + + +### Bug Fixes + +* **api:** derive OpenAPI request docs from runtime Zod schemas ([#1421](https://github.com/context-dot-dev/context-typescript-sdk/issues/1421)) ([7020c30](https://github.com/context-dot-dev/context-typescript-sdk/commit/7020c30b863e8b5ecdb669a763ecf378172ff674)) + ## [3.3.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.2.0...v3.3.0) (2026-09-29) diff --git a/package.json b/package.json index 84c532f0..066a8abe 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.3.0", + "version": "3.4.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index ab2e905d..d8607e36 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.3.0'; // x-release-please-version +export const VERSION = '3.4.0'; // x-release-please-version From 59da2fe6fad88ce1588c46b7bcc5b4ad884048b1 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 1 Oct 2026 00:53:09 +0000 Subject: [PATCH 125/232] seal --- .release-please-manifest.json | 2 +- CHANGELOG.md | 15 +++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 18 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 6110c0f0..9dc6cef9 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.3.0" + ".": "3.4.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index edcd7321..530311f0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,20 @@ # Changelog +## [3.4.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.3.0...v3.4.0) (2026-09-30) + + +### Features + +* **logs:** serve request logs at /org/logs ([#1442](https://github.com/context-dot-dev/context-typescript-sdk/issues/1442)) ([f9b8c6d](https://github.com/context-dot-dev/context-typescript-sdk/commit/f9b8c6db3acad05121e5445207b05af08c69dfd7)) +* **scrape:** accept documents up to 50 MB ([#1436](https://github.com/context-dot-dev/context-typescript-sdk/issues/1436)) ([91e8d5e](https://github.com/context-dot-dev/context-typescript-sdk/commit/91e8d5e529c51b2b66554d877f756acf833a6366)) +* **scrape:** add productParams.dedupeImages, always run product AI fallback ([#1423](https://github.com/context-dot-dev/context-typescript-sdk/issues/1423)) ([889ef20](https://github.com/context-dot-dev/context-typescript-sdk/commit/889ef2055c8ba9e7f956990fe5a9237e2993af82)) +* **scrape:** default POST /web/scrape deadline to 90s ([#1428](https://github.com/context-dot-dev/context-typescript-sdk/issues/1428)) ([bc3912b](https://github.com/context-dot-dev/context-typescript-sdk/commit/bc3912b90e614a3889f8cd0449d6501bbed5c28e)) + + +### Bug Fixes + +* **api:** derive OpenAPI request docs from runtime Zod schemas ([#1421](https://github.com/context-dot-dev/context-typescript-sdk/issues/1421)) ([7020c30](https://github.com/context-dot-dev/context-typescript-sdk/commit/7020c30b863e8b5ecdb669a763ecf378172ff674)) + ## [3.3.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.2.0...v3.3.0) (2026-09-29) diff --git a/package.json b/package.json index 84c532f0..066a8abe 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.3.0", + "version": "3.4.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index ab2e905d..d8607e36 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.3.0'; // x-release-please-version +export const VERSION = '3.4.0'; // x-release-please-version From 30858ea0211aafda74de151286b9f7f5eccd51d7 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 4 Oct 2026 20:15:48 +0000 Subject: [PATCH 126/232] seal --- src/resources/web.ts | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 4ff39cdc..c98f72d0 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1732,7 +1732,14 @@ export namespace WebSearchResponse { /** * Per-result highlights outcome. Inspect this before reading `highlights`. */ - code: 'SUCCESS' | 'NOT_REQUESTED' | 'TIMEOUT' | 'CONTENT_TOO_LARGE' | 'WEBSITE_ACCESS_ERROR' | 'ERROR'; + code: + | 'SUCCESS' + | 'NOT_REQUESTED' + | 'TIMEOUT' + | 'CONTENT_TOO_LARGE' + | 'WEBSITE_ACCESS_ERROR' + | 'WEBSITE_BLOCKED' + | 'ERROR'; /** * Passages relevant to the query, in page order. Null unless @@ -1748,7 +1755,14 @@ export namespace WebSearchResponse { /** * Per-result scrape outcome. Inspect this before reading `markdown`. */ - code: 'SUCCESS' | 'NOT_REQUESTED' | 'TIMEOUT' | 'CONTENT_TOO_LARGE' | 'WEBSITE_ACCESS_ERROR' | 'ERROR'; + code: + | 'SUCCESS' + | 'NOT_REQUESTED' + | 'TIMEOUT' + | 'CONTENT_TOO_LARGE' + | 'WEBSITE_ACCESS_ERROR' + | 'WEBSITE_BLOCKED' + | 'ERROR'; /** * GFM Markdown of the page. Null unless markdownOptions.enabled is true and From 429afc288ed925f75a5b18a9204a47df0c65f869 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 4 Oct 2026 20:15:48 +0000 Subject: [PATCH 127/232] fix(search): shorter default page-read budget and blocked-page codes for search results (#1573) Stainless-Generated-From: 30858ea0211aafda74de151286b9f7f5eccd51d7 --- src/resources/web.ts | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 4ff39cdc..c98f72d0 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1732,7 +1732,14 @@ export namespace WebSearchResponse { /** * Per-result highlights outcome. Inspect this before reading `highlights`. */ - code: 'SUCCESS' | 'NOT_REQUESTED' | 'TIMEOUT' | 'CONTENT_TOO_LARGE' | 'WEBSITE_ACCESS_ERROR' | 'ERROR'; + code: + | 'SUCCESS' + | 'NOT_REQUESTED' + | 'TIMEOUT' + | 'CONTENT_TOO_LARGE' + | 'WEBSITE_ACCESS_ERROR' + | 'WEBSITE_BLOCKED' + | 'ERROR'; /** * Passages relevant to the query, in page order. Null unless @@ -1748,7 +1755,14 @@ export namespace WebSearchResponse { /** * Per-result scrape outcome. Inspect this before reading `markdown`. */ - code: 'SUCCESS' | 'NOT_REQUESTED' | 'TIMEOUT' | 'CONTENT_TOO_LARGE' | 'WEBSITE_ACCESS_ERROR' | 'ERROR'; + code: + | 'SUCCESS' + | 'NOT_REQUESTED' + | 'TIMEOUT' + | 'CONTENT_TOO_LARGE' + | 'WEBSITE_ACCESS_ERROR' + | 'WEBSITE_BLOCKED' + | 'ERROR'; /** * GFM Markdown of the page. Null unless markdownOptions.enabled is true and From db8d540a33eb56431c0ef43794ee724f112b0fa5 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 4 Oct 2026 20:26:46 +0000 Subject: [PATCH 128/232] seal --- src/resources/web.ts | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/resources/web.ts b/src/resources/web.ts index c98f72d0..bbf3f02a 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1166,6 +1166,12 @@ export namespace WebScrapeResponse { */ error_code?: string; + /** + * True when the page was too long to read in full, so values found only in the + * unread parts may be missing. + */ + isTruncated?: true; + /** * Explanation of the failure and possible next steps. */ From 8891890369c39d18404d2859a6c181ed14d185bb Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 4 Oct 2026 20:26:46 +0000 Subject: [PATCH 129/232] fix(scrape): keep the relevant sections of long pages for JSON extraction (#1582) Stainless-Generated-From: db8d540a33eb56431c0ef43794ee724f112b0fa5 --- src/resources/web.ts | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/resources/web.ts b/src/resources/web.ts index c98f72d0..bbf3f02a 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1166,6 +1166,12 @@ export namespace WebScrapeResponse { */ error_code?: string; + /** + * True when the page was too long to read in full, so values found only in the + * unread parts may be missing. + */ + isTruncated?: true; + /** * Explanation of the failure and possible next steps. */ From db180560d6610776b0d5596dfb062511714cebd5 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 4 Oct 2026 20:37:52 +0000 Subject: [PATCH 130/232] seal --- src/resources/web.ts | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index bbf3f02a..9bc1c3ee 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -144,9 +144,8 @@ export interface WebAnswersResponse { json_content: { [key: string]: unknown }; /** - * Public evidence URLs from searches, pages, or company/profile records, in - * first-seen order. A listed URL may identify a record without its page being - * read. + * URLs of the pages and company/profile records read for the answer, followed by + * URLs cited in json_content. */ sources: Array; From da733eed4a52641246d71a24308c8b72094e9a4c Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 4 Oct 2026 20:37:53 +0000 Subject: [PATCH 131/232] fix(answers): keep page links for the agent and only cite URLs it actually saw (#1571) Stainless-Generated-From: db180560d6610776b0d5596dfb062511714cebd5 --- src/resources/web.ts | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index bbf3f02a..9bc1c3ee 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -144,9 +144,8 @@ export interface WebAnswersResponse { json_content: { [key: string]: unknown }; /** - * Public evidence URLs from searches, pages, or company/profile records, in - * first-seen order. A listed URL may identify a record without its page being - * read. + * URLs of the pages and company/profile records read for the answer, followed by + * URLs cited in json_content. */ sources: Array; From be1c4382cead87e10b0316f559865b8d8592af7d Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 5 Oct 2026 15:48:37 +0000 Subject: [PATCH 132/232] seal --- src/resources/web.ts | 5 +++++ tests/api-resources/web.test.ts | 1 + 2 files changed, 6 insertions(+) diff --git a/src/resources/web.ts b/src/resources/web.ts index 9bc1c3ee..55816804 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -3394,6 +3394,11 @@ export interface WebSearchParams { | 'zm' | 'zw'; + /** + * Maximum length of each result's `description`, in characters. + */ + descriptionMaxCharacters?: number | null; + /** * Blocklist — drop results from these domains. Up to 100 domains. Example: * ["pinterest.com", "reddit.com"]. diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index fe4a29ee..2e7bf681 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -260,6 +260,7 @@ describe('resource web', () => { const response = await client.web.search({ query: 'Stripe API authentication', country: 'af', + descriptionMaxCharacters: 0, excludeDomains: ['xxx'], freshness: 'last_24_hours', highlightsOptions: { enabled: true, maxCharacters: 100 }, From 435424d48a7bb8900febd3146e25a2bd453d2272 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 5 Oct 2026 15:48:38 +0000 Subject: [PATCH 133/232] feat(search): /web/search - for news results extend description with matching passages from article. Stainless-Generated-From: be1c4382cead87e10b0316f559865b8d8592af7d --- src/resources/web.ts | 5 +++++ tests/api-resources/web.test.ts | 1 + 2 files changed, 6 insertions(+) diff --git a/src/resources/web.ts b/src/resources/web.ts index 9bc1c3ee..55816804 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -3394,6 +3394,11 @@ export interface WebSearchParams { | 'zm' | 'zw'; + /** + * Maximum length of each result's `description`, in characters. + */ + descriptionMaxCharacters?: number | null; + /** * Blocklist — drop results from these domains. Up to 100 domains. Example: * ["pinterest.com", "reddit.com"]. diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index fe4a29ee..2e7bf681 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -260,6 +260,7 @@ describe('resource web', () => { const response = await client.web.search({ query: 'Stripe API authentication', country: 'af', + descriptionMaxCharacters: 0, excludeDomains: ['xxx'], freshness: 'last_24_hours', highlightsOptions: { enabled: true, maxCharacters: 100 }, From e903cb1bb2b42df37645be34888422a4ca099217 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 5 Oct 2026 19:07:49 +0000 Subject: [PATCH 134/232] seal --- src/resources/news.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/resources/news.ts b/src/resources/news.ts index c857c1bc..c13c271d 100644 --- a/src/resources/news.ts +++ b/src/resources/news.ts @@ -434,6 +434,7 @@ export namespace NewsSearchParams { | 'mx' | 'ng' | 'nl' + | 'pk' | 'qa' | 'sa' | 'se' From e3ff1272921ff10db0326beae6c2f94582efc04c Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 5 Oct 2026 19:07:50 +0000 Subject: [PATCH 135/232] feat(news): add Google News sitemap feeds for 52 sites from the NEEDLE 4-star gaps (#1612) Stainless-Generated-From: e903cb1bb2b42df37645be34888422a4ca099217 --- src/resources/news.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/resources/news.ts b/src/resources/news.ts index c857c1bc..c13c271d 100644 --- a/src/resources/news.ts +++ b/src/resources/news.ts @@ -434,6 +434,7 @@ export namespace NewsSearchParams { | 'mx' | 'ng' | 'nl' + | 'pk' | 'qa' | 'sa' | 'se' From 39fc762e0effa24906a76643429273e975eff203 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 7 Oct 2026 04:35:05 +0000 Subject: [PATCH 136/232] feat(batches): keep batch result files for 180 days (#1638) Stainless-Generated-From: 103334272938293e8eb5c8f5d53ae48aadc4553a --- src/resources/batch.ts | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index ee847ef8..38607642 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -13,7 +13,7 @@ import { path } from '../internal/utils/path'; */ export class Batch extends APIResource { /** - * Get batch progress and result download links. Result files are deleted 7 days + * Get batch progress and result download links. Result files are deleted 180 days * after the batch finishes. * * @example @@ -67,8 +67,8 @@ export class Batch extends APIResource { } /** - * Page through a finished batch’s results as JSON. Results remain available for 7 - * days. + * Page through a finished batch’s results as JSON. Results remain available for + * 180 days. * * @example * ```ts @@ -309,7 +309,7 @@ export interface BatchRetrieveResponse { request_id: string; /** - * Result download links; null until the batch finishes. Files are deleted 7 days + * Result download links; null until the batch finishes. Files are deleted 180 days * after the batch finishes. */ results: BatchRetrieveResponse.Results | null; @@ -397,7 +397,7 @@ export namespace BatchRetrieveResponse { } /** - * Result download links; null until the batch finishes. Files are deleted 7 days + * Result download links; null until the batch finishes. Files are deleted 180 days * after the batch finishes. */ export interface Results { @@ -546,7 +546,7 @@ export namespace BatchListResponse { progress: Data.Progress; /** - * Result download links; null until the batch finishes. Files are deleted 7 days + * Result download links; null until the batch finishes. Files are deleted 180 days * after the batch finishes. */ results: Data.Results | null; @@ -612,7 +612,7 @@ export namespace BatchListResponse { } /** - * Result download links; null until the batch finishes. Files are deleted 7 days + * Result download links; null until the batch finishes. Files are deleted 180 days * after the batch finishes. */ export interface Results { From 103334272938293e8eb5c8f5d53ae48aadc4553a Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 7 Oct 2026 04:35:05 +0000 Subject: [PATCH 137/232] seal --- src/resources/batch.ts | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index ee847ef8..38607642 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -13,7 +13,7 @@ import { path } from '../internal/utils/path'; */ export class Batch extends APIResource { /** - * Get batch progress and result download links. Result files are deleted 7 days + * Get batch progress and result download links. Result files are deleted 180 days * after the batch finishes. * * @example @@ -67,8 +67,8 @@ export class Batch extends APIResource { } /** - * Page through a finished batch’s results as JSON. Results remain available for 7 - * days. + * Page through a finished batch’s results as JSON. Results remain available for + * 180 days. * * @example * ```ts @@ -309,7 +309,7 @@ export interface BatchRetrieveResponse { request_id: string; /** - * Result download links; null until the batch finishes. Files are deleted 7 days + * Result download links; null until the batch finishes. Files are deleted 180 days * after the batch finishes. */ results: BatchRetrieveResponse.Results | null; @@ -397,7 +397,7 @@ export namespace BatchRetrieveResponse { } /** - * Result download links; null until the batch finishes. Files are deleted 7 days + * Result download links; null until the batch finishes. Files are deleted 180 days * after the batch finishes. */ export interface Results { @@ -546,7 +546,7 @@ export namespace BatchListResponse { progress: Data.Progress; /** - * Result download links; null until the batch finishes. Files are deleted 7 days + * Result download links; null until the batch finishes. Files are deleted 180 days * after the batch finishes. */ results: Data.Results | null; @@ -612,7 +612,7 @@ export namespace BatchListResponse { } /** - * Result download links; null until the batch finishes. Files are deleted 7 days + * Result download links; null until the batch finishes. Files are deleted 180 days * after the batch finishes. */ export interface Results { From 03a0cf788a72fca424ed59dddcee52bbb638680e Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Wed, 7 Oct 2026 06:37:13 +0200 Subject: [PATCH 138/232] release: 3.5.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 16 ++++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 19 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 9dc6cef9..3cf104e9 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.4.0" + ".": "3.5.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 530311f0..829a2cf9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,21 @@ # Changelog +## [3.5.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.4.0...v3.5.0) (2026-10-07) + + +### Features + +* **batches:** keep batch result files for 180 days ([#1638](https://github.com/context-dot-dev/context-typescript-sdk/issues/1638)) ([39fc762](https://github.com/context-dot-dev/context-typescript-sdk/commit/39fc762e0effa24906a76643429273e975eff203)) +* **news:** add Google News sitemap feeds for 52 sites from the NEEDLE 4-star gaps ([#1612](https://github.com/context-dot-dev/context-typescript-sdk/issues/1612)) ([e3ff127](https://github.com/context-dot-dev/context-typescript-sdk/commit/e3ff1272921ff10db0326beae6c2f94582efc04c)) +* **search:** /web/search - for news results extend description with matching passages from article. ([435424d](https://github.com/context-dot-dev/context-typescript-sdk/commit/435424d48a7bb8900febd3146e25a2bd453d2272)) + + +### Bug Fixes + +* **answers:** keep page links for the agent and only cite URLs it actually saw ([#1571](https://github.com/context-dot-dev/context-typescript-sdk/issues/1571)) ([da733ee](https://github.com/context-dot-dev/context-typescript-sdk/commit/da733eed4a52641246d71a24308c8b72094e9a4c)) +* **scrape:** keep the relevant sections of long pages for JSON extraction ([#1582](https://github.com/context-dot-dev/context-typescript-sdk/issues/1582)) ([8891890](https://github.com/context-dot-dev/context-typescript-sdk/commit/8891890369c39d18404d2859a6c181ed14d185bb)) +* **search:** shorter default page-read budget and blocked-page codes for search results ([#1573](https://github.com/context-dot-dev/context-typescript-sdk/issues/1573)) ([429afc2](https://github.com/context-dot-dev/context-typescript-sdk/commit/429afc288ed925f75a5b18a9204a47df0c65f869)) + ## [3.4.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.3.0...v3.4.0) (2026-09-30) diff --git a/package.json b/package.json index 066a8abe..1a6397a9 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.4.0", + "version": "3.5.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index d8607e36..ce3f15b1 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.4.0'; // x-release-please-version +export const VERSION = '3.5.0'; // x-release-please-version From ea754f3369c731dd8ba95d89ba065efa798dc27e Mon Sep 17 00:00:00 2001 From: Yahia Bakour Date: Thu, 8 Oct 2026 12:48:11 -0400 Subject: [PATCH 139/232] docs: lead README with Context.dev capabilities --- README.md | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 08d23b4e..e279aa13 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![NPM version]()](https://npmjs.org/package/context.dev) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/context.dev) -This library provides convenient access to the Context Dev REST API from server-side TypeScript or JavaScript. +Context.dev is a web scraping API for AI agents and LLMs. This SDK turns any URL into clean, LLM-ready markdown, crawls whole sites, searches the web, takes screenshots and extracts structured JSON against a schema you define, all with one API key. Proxies, JavaScript rendering and anti-bot handling run on Context.dev's side, so there is no headless browser to host. The REST API documentation can be found on [docs.context.dev](https://docs.context.dev/). The full API of this library can be found in [api.md](api.md). @@ -31,6 +31,47 @@ const brand = await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_doma console.log(brand.request_id); ``` +### Extract structured JSON + +`jsonParams.schema` accepts JSON Schema; install Zod 4 (`npm install zod@^4`) to build a schema with Zod and convert it with `z.toJSONSchema`. + +```ts +import ContextDev from 'context.dev'; +import { z } from 'zod'; + +const client = new ContextDev(); +const pageSchema = z.object({ + title: z.string().nullable(), + description: z.string().nullable(), +}); + +const page = await client.web.scrape({ + url: 'https://example.com', + formats: { json: true }, + jsonParams: { schema: z.toJSONSchema(pageSchema) }, +}); + +console.log(page.json.data); +``` + +## What you can do + +| Task | Method | +| --- | --- | +| Scrape a URL to markdown, HTML, JSON or a screenshot | `client.web.scrape` | +| Crawl a site and get every page as markdown | `client.web.webCrawlMd` | +| Map every URL on a domain | `client.web.mapUrls` | +| Search the web | `client.web.search` | +| Take a screenshot of a page | `client.web.screenshot` | +| Parse PDFs and documents | `client.parse.handle` | +| Run thousands of URLs as a batch | `client.batch.submit` | +| Watch a page for changes | `client.monitors.create` | +| Look up a company's logo, colors and brand data | `client.brand.retrieve` | + +## Use it from an AI agent + +Context.dev also ships as a plugin for [Claude](https://github.com/context-dot-dev/claude-plugin), [Cursor](https://github.com/context-dot-dev/cursor-plugin) and [Gemini CLI](https://github.com/context-dot-dev/gemini-cli-context), and as tools for [LangChain](https://github.com/context-dot-dev/langchain-context) and [Haystack](https://github.com/context-dot-dev/context-haystack). + ### Request & Response types This library includes TypeScript definitions for all request params and response fields. You may import and use them like so: From dadbc3a86d3e4edbafb725a2b56191c23871d096 Mon Sep 17 00:00:00 2001 From: Yahia Bakour Date: Thu, 8 Oct 2026 12:48:33 -0400 Subject: [PATCH 140/232] docs: format capability table --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index e279aa13..bdb26377 100644 --- a/README.md +++ b/README.md @@ -56,17 +56,17 @@ console.log(page.json.data); ## What you can do -| Task | Method | -| --- | --- | -| Scrape a URL to markdown, HTML, JSON or a screenshot | `client.web.scrape` | -| Crawl a site and get every page as markdown | `client.web.webCrawlMd` | -| Map every URL on a domain | `client.web.mapUrls` | -| Search the web | `client.web.search` | -| Take a screenshot of a page | `client.web.screenshot` | -| Parse PDFs and documents | `client.parse.handle` | -| Run thousands of URLs as a batch | `client.batch.submit` | -| Watch a page for changes | `client.monitors.create` | -| Look up a company's logo, colors and brand data | `client.brand.retrieve` | +| Task | Method | +| ---------------------------------------------------- | ------------------------ | +| Scrape a URL to markdown, HTML, JSON or a screenshot | `client.web.scrape` | +| Crawl a site and get every page as markdown | `client.web.webCrawlMd` | +| Map every URL on a domain | `client.web.mapUrls` | +| Search the web | `client.web.search` | +| Take a screenshot of a page | `client.web.screenshot` | +| Parse PDFs and documents | `client.parse.handle` | +| Run thousands of URLs as a batch | `client.batch.submit` | +| Watch a page for changes | `client.monitors.create` | +| Look up a company's logo, colors and brand data | `client.brand.retrieve` | ## Use it from an AI agent From 2628c22cdc48e011546ba0e0ef45d2e3f7fe8b53 Mon Sep 17 00:00:00 2001 From: Yahia Bakour Date: Thu, 8 Oct 2026 12:51:09 -0400 Subject: [PATCH 141/232] docs: remove Stainless README attribution --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index bdb26377..3ada9d90 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,6 @@ Context.dev is a web scraping API for AI agents and LLMs. This SDK turns any URL The REST API documentation can be found on [docs.context.dev](https://docs.context.dev/). The full API of this library can be found in [api.md](api.md). -It is generated with [Stainless](https://www.stainless.com/). - ## Installation ```sh From ec358c9b4a59664a5901d113e3c56eefdea86d4c Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 8 Oct 2026 16:55:21 +0000 Subject: [PATCH 142/232] Build SDK Stainless-Generated-From: 0dbef8ca08f28ec57e0e0b4ebebee37bd9cd78a3 --- README.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 08d23b4e..d69cd405 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Context Dev TypeScript API Library +# Context.dev TypeScript SDK API Library [![NPM version]()](https://npmjs.org/package/context.dev) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/context.dev) @@ -26,9 +26,12 @@ const client = new ContextDev({ apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted }); -const brand = await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }); +const page = await client.web.scrape({ + formats: { markdown: true }, + url: 'https://example.com', +}); -console.log(brand.request_id); +console.log(page.request_id); ``` ### Request & Response types @@ -229,7 +232,7 @@ parameter. This library doesn't validate at runtime that the request matches the send will be sent as-is. ```ts -client.brand.retrieve({ +client.web.scrape({ // ... // @ts-expect-error baz is not yet public baz: 'undocumented option', From e9b2400177404d9ff436ab86c75135d29c046568 Mon Sep 17 00:00:00 2001 From: Yahia Bakour Date: Thu, 8 Oct 2026 13:03:44 -0400 Subject: [PATCH 143/232] docs: demonstrate scraping formats throughout README --- README.md | 102 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 72 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 3ada9d90..399620e7 100644 --- a/README.md +++ b/README.md @@ -14,19 +14,25 @@ npm install context.dev ## Usage +Set `CONTEXT_DEV_API_KEY` to your API key; the client reads it automatically. + +### Scrape markdown and HTML + The full API of this library can be found in [api.md](api.md). -```js +```ts import ContextDev from 'context.dev'; -const client = new ContextDev({ - apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted -}); +const client = new ContextDev(); -const brand = await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }); +const page = await client.web.scrape({ + url: 'https://example.com', + formats: { markdown: true, html: true }, +}); -console.log(brand.request_id); +console.log(page.markdown.data); +console.log(page.html.data); ``` ### Extract structured JSON @@ -52,19 +58,54 @@ const page = await client.web.scrape({ console.log(page.json.data); ``` +### Extract relevant highlights + +Return the passages that answer a question about the page. + +```ts +import ContextDev from 'context.dev'; + +const client = new ContextDev(); + +const page = await client.web.scrape({ + url: 'https://example.com', + formats: { highlights: true }, + highlightsParams: { query: 'What is this domain used for?' }, +}); + +console.log(page.highlights.data); +``` + +### Take a screenshot + +The screenshot is returned as a base64 image data URL. + +```ts +import ContextDev from 'context.dev'; + +const client = new ContextDev(); + +const page = await client.web.scrape({ + url: 'https://example.com', + formats: { screenshot: true }, +}); + +console.log(page.screenshot.data); +``` + ## What you can do -| Task | Method | -| ---------------------------------------------------- | ------------------------ | -| Scrape a URL to markdown, HTML, JSON or a screenshot | `client.web.scrape` | -| Crawl a site and get every page as markdown | `client.web.webCrawlMd` | -| Map every URL on a domain | `client.web.mapUrls` | -| Search the web | `client.web.search` | -| Take a screenshot of a page | `client.web.screenshot` | -| Parse PDFs and documents | `client.parse.handle` | -| Run thousands of URLs as a batch | `client.batch.submit` | -| Watch a page for changes | `client.monitors.create` | -| Look up a company's logo, colors and brand data | `client.brand.retrieve` | +| Task | Method | +| ---------------------------------------------------------------- | ------------------------ | +| Scrape a URL to markdown, HTML, JSON, highlights or a screenshot | `client.web.scrape` | +| Crawl a site and get every page as markdown | `client.web.webCrawlMd` | +| Map every URL on a domain | `client.web.mapUrls` | +| Search the web | `client.web.search` | +| Take a screenshot of a page | `client.web.screenshot` | +| Parse PDFs and documents | `client.parse.handle` | +| Run thousands of URLs as a batch | `client.batch.submit` | +| Watch a page for changes | `client.monitors.create` | +| Look up a company's logo, colors and brand data | `client.brand.retrieve` | ## Use it from an AI agent @@ -82,8 +123,8 @@ const client = new ContextDev({ apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted }); -const params: ContextDev.BrandRetrieveParams = { domain: 'REPLACE_ME', type: 'by_domain' }; -const brand: ContextDev.BrandRetrieveResponse = await client.brand.retrieve(params); +const params: ContextDev.WebScrapeParams = { url: 'https://example.com', formats: { markdown: true } }; +const page: ContextDev.WebScrapeResponse = await client.web.scrape(params); ``` Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors. @@ -96,8 +137,8 @@ a subclass of `APIError` will be thrown: ```ts -const brand = await client.brand - .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }) +const page = await client.web + .scrape({ url: 'https://example.com', formats: { markdown: true } }) .catch(async (err) => { if (err instanceof ContextDev.APIError) { console.log(err.status); // 400 @@ -138,7 +179,7 @@ const client = new ContextDev({ }); // Or, configure per-request: -await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }, { +await client.web.scrape({ url: 'https://example.com', formats: { markdown: true } }, { maxRetries: 5, }); ``` @@ -155,7 +196,7 @@ const client = new ContextDev({ }); // Override per-request: -await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }, { +await client.web.scrape({ url: 'https://example.com', formats: { markdown: true } }, { timeout: 5 * 1000, }); ``` @@ -178,17 +219,17 @@ Unlike `.asResponse()` this method consumes the body, returning once it is parse ```ts const client = new ContextDev(); -const response = await client.brand - .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }) +const response = await client.web + .scrape({ url: 'https://example.com', formats: { markdown: true } }) .asResponse(); console.log(response.headers.get('X-My-Header')); console.log(response.statusText); // access the underlying Response object -const { data: brand, response: raw } = await client.brand - .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }) +const { data: page, response: raw } = await client.web + .scrape({ url: 'https://example.com', formats: { markdown: true } }) .withResponse(); console.log(raw.headers.get('X-My-Header')); -console.log(brand.request_id); +console.log(page.markdown.data); ``` ### Logging @@ -268,8 +309,9 @@ parameter. This library doesn't validate at runtime that the request matches the send will be sent as-is. ```ts -client.brand.retrieve({ - // ... +client.web.scrape({ + url: 'https://example.com', + formats: { markdown: true }, // @ts-expect-error baz is not yet public baz: 'undocumented option', }); From fe57440954ee5c5b98279d437d38dbac295f5af3 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 8 Oct 2026 17:13:36 +0000 Subject: [PATCH 144/232] Build SDK Stainless-Generated-From: 240ef531e2bb4ead2c6c92f0dfd13f1b86e5e4ea --- README.md | 42 ++++++++++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index d69cd405..a26beef8 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ const client = new ContextDev({ }); const page = await client.web.scrape({ - formats: { markdown: true }, + formats: { markdown: true, html: true }, url: 'https://example.com', }); @@ -46,8 +46,11 @@ const client = new ContextDev({ apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted }); -const params: ContextDev.BrandRetrieveParams = { domain: 'REPLACE_ME', type: 'by_domain' }; -const brand: ContextDev.BrandRetrieveResponse = await client.brand.retrieve(params); +const params: ContextDev.WebScrapeParams = { + formats: { markdown: true }, + url: 'https://example.com', +}; +const page: ContextDev.WebScrapeResponse = await client.web.scrape(params); ``` Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors. @@ -60,8 +63,11 @@ a subclass of `APIError` will be thrown: ```ts -const brand = await client.brand - .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }) +const page = await client.web + .scrape({ + formats: { markdown: true }, + url: 'https://example.com', + }) .catch(async (err) => { if (err instanceof ContextDev.APIError) { console.log(err.status); // 400 @@ -102,7 +108,10 @@ const client = new ContextDev({ }); // Or, configure per-request: -await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }, { +await client.web.scrape({ + formats: { markdown: true }, + url: 'https://example.com', +}, { maxRetries: 5, }); ``` @@ -119,7 +128,10 @@ const client = new ContextDev({ }); // Override per-request: -await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }, { +await client.web.scrape({ + formats: { markdown: true }, + url: 'https://example.com', +}, { timeout: 5 * 1000, }); ``` @@ -142,17 +154,23 @@ Unlike `.asResponse()` this method consumes the body, returning once it is parse ```ts const client = new ContextDev(); -const response = await client.brand - .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }) +const response = await client.web + .scrape({ + formats: { markdown: true }, + url: 'https://example.com', + }) .asResponse(); console.log(response.headers.get('X-My-Header')); console.log(response.statusText); // access the underlying Response object -const { data: brand, response: raw } = await client.brand - .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }) +const { data: page, response: raw } = await client.web + .scrape({ + formats: { markdown: true }, + url: 'https://example.com', + }) .withResponse(); console.log(raw.headers.get('X-My-Header')); -console.log(brand.request_id); +console.log(page.request_id); ``` ### Logging From 2d04e167318461e05894f0404a5dfc6f3a24a4b4 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 8 Oct 2026 18:23:29 +0000 Subject: [PATCH 145/232] Build SDK Stainless-Generated-From: 25b31e74f32afedcea0162c98c077bf2b21ae330 --- README.md | 128 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 94 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index a26beef8..16f1e614 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,10 @@ [![NPM version]()](https://npmjs.org/package/context.dev) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/context.dev) -This library provides convenient access to the Context Dev REST API from server-side TypeScript or JavaScript. +Context.dev is a web scraping API for AI agents and LLMs. This SDK turns any URL into clean, LLM-ready markdown, crawls whole sites, searches the web, takes screenshots and extracts structured JSON against a schema you define, all with one API key. Proxies, JavaScript rendering and anti-bot handling run on Context.dev's side, so there is no headless browser to host. The REST API documentation can be found on [docs.context.dev](https://docs.context.dev/). The full API of this library can be found in [api.md](api.md). -It is generated with [Stainless](https://www.stainless.com/). - ## Installation ```sh @@ -16,24 +14,103 @@ npm install context.dev ## Usage +Set `CONTEXT_DEV_API_KEY` to your API key; the client reads it automatically. + +### Scrape markdown and HTML + The full API of this library can be found in [api.md](api.md). -```js +```ts import ContextDev from 'context.dev'; -const client = new ContextDev({ - apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted -}); +const client = new ContextDev(); const page = await client.web.scrape({ + url: 'https://example.com', formats: { markdown: true, html: true }, +}); + +console.log(page.markdown.data); +console.log(page.html.data); +``` + +### Extract structured JSON + +`jsonParams.schema` accepts JSON Schema; install Zod 4 (`npm install zod@^4`) to build a schema with Zod and convert it with `z.toJSONSchema`. + +```ts +import ContextDev from 'context.dev'; +import { z } from 'zod'; + +const client = new ContextDev(); +const pageSchema = z.object({ + title: z.string().nullable(), + description: z.string().nullable(), +}); + +const page = await client.web.scrape({ url: 'https://example.com', + formats: { json: true }, + jsonParams: { schema: z.toJSONSchema(pageSchema) }, }); -console.log(page.request_id); +console.log(page.json.data); ``` +### Extract relevant highlights + +Return the passages that answer a question about the page. + +```ts +import ContextDev from 'context.dev'; + +const client = new ContextDev(); + +const page = await client.web.scrape({ + url: 'https://example.com', + formats: { highlights: true }, + highlightsParams: { query: 'What is this domain used for?' }, +}); + +console.log(page.highlights.data); +``` + +### Take a screenshot + +The screenshot is returned as a base64 image data URL. + +```ts +import ContextDev from 'context.dev'; + +const client = new ContextDev(); + +const page = await client.web.scrape({ + url: 'https://example.com', + formats: { screenshot: true }, +}); + +console.log(page.screenshot.data); +``` + +## What you can do + +| Task | Method | +| ---------------------------------------------------------------- | ------------------------ | +| Scrape a URL to markdown, HTML, JSON, highlights or a screenshot | `client.web.scrape` | +| Crawl a site and get every page as markdown | `client.web.webCrawlMd` | +| Map every URL on a domain | `client.web.mapUrls` | +| Search the web | `client.web.search` | +| Take a screenshot of a page | `client.web.screenshot` | +| Parse PDFs and documents | `client.parse.handle` | +| Run thousands of URLs as a batch | `client.batch.submit` | +| Watch a page for changes | `client.monitors.create` | +| Look up a company's logo, colors and brand data | `client.brand.retrieve` | + +## Use it from an AI agent + +Context.dev also ships as a plugin for [Claude](https://github.com/context-dot-dev/claude-plugin), [Cursor](https://github.com/context-dot-dev/cursor-plugin) and [Gemini CLI](https://github.com/context-dot-dev/gemini-cli-context), and as tools for [LangChain](https://github.com/context-dot-dev/langchain-context) and [Haystack](https://github.com/context-dot-dev/context-haystack). + ### Request & Response types This library includes TypeScript definitions for all request params and response fields. You may import and use them like so: @@ -46,10 +123,7 @@ const client = new ContextDev({ apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted }); -const params: ContextDev.WebScrapeParams = { - formats: { markdown: true }, - url: 'https://example.com', -}; +const params: ContextDev.WebScrapeParams = { url: 'https://example.com', formats: { markdown: true } }; const page: ContextDev.WebScrapeResponse = await client.web.scrape(params); ``` @@ -64,10 +138,7 @@ a subclass of `APIError` will be thrown: ```ts const page = await client.web - .scrape({ - formats: { markdown: true }, - url: 'https://example.com', - }) + .scrape({ url: 'https://example.com', formats: { markdown: true } }) .catch(async (err) => { if (err instanceof ContextDev.APIError) { console.log(err.status); // 400 @@ -108,10 +179,7 @@ const client = new ContextDev({ }); // Or, configure per-request: -await client.web.scrape({ - formats: { markdown: true }, - url: 'https://example.com', -}, { +await client.web.scrape({ url: 'https://example.com', formats: { markdown: true } }, { maxRetries: 5, }); ``` @@ -128,10 +196,7 @@ const client = new ContextDev({ }); // Override per-request: -await client.web.scrape({ - formats: { markdown: true }, - url: 'https://example.com', -}, { +await client.web.scrape({ url: 'https://example.com', formats: { markdown: true } }, { timeout: 5 * 1000, }); ``` @@ -155,22 +220,16 @@ Unlike `.asResponse()` this method consumes the body, returning once it is parse const client = new ContextDev(); const response = await client.web - .scrape({ - formats: { markdown: true }, - url: 'https://example.com', - }) + .scrape({ url: 'https://example.com', formats: { markdown: true } }) .asResponse(); console.log(response.headers.get('X-My-Header')); console.log(response.statusText); // access the underlying Response object const { data: page, response: raw } = await client.web - .scrape({ - formats: { markdown: true }, - url: 'https://example.com', - }) + .scrape({ url: 'https://example.com', formats: { markdown: true } }) .withResponse(); console.log(raw.headers.get('X-My-Header')); -console.log(page.request_id); +console.log(page.markdown.data); ``` ### Logging @@ -251,7 +310,8 @@ send will be sent as-is. ```ts client.web.scrape({ - // ... + url: 'https://example.com', + formats: { markdown: true }, // @ts-expect-error baz is not yet public baz: 'undocumented option', }); From 756cb4f728b3c8fb1d93468445624fe2b1e1c782 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 8 Oct 2026 18:26:45 +0000 Subject: [PATCH 146/232] seal --- .release-please-manifest.json | 2 +- CHANGELOG.md | 16 ++++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 19 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 9dc6cef9..3cf104e9 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.4.0" + ".": "3.5.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 530311f0..829a2cf9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,21 @@ # Changelog +## [3.5.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.4.0...v3.5.0) (2026-10-07) + + +### Features + +* **batches:** keep batch result files for 180 days ([#1638](https://github.com/context-dot-dev/context-typescript-sdk/issues/1638)) ([39fc762](https://github.com/context-dot-dev/context-typescript-sdk/commit/39fc762e0effa24906a76643429273e975eff203)) +* **news:** add Google News sitemap feeds for 52 sites from the NEEDLE 4-star gaps ([#1612](https://github.com/context-dot-dev/context-typescript-sdk/issues/1612)) ([e3ff127](https://github.com/context-dot-dev/context-typescript-sdk/commit/e3ff1272921ff10db0326beae6c2f94582efc04c)) +* **search:** /web/search - for news results extend description with matching passages from article. ([435424d](https://github.com/context-dot-dev/context-typescript-sdk/commit/435424d48a7bb8900febd3146e25a2bd453d2272)) + + +### Bug Fixes + +* **answers:** keep page links for the agent and only cite URLs it actually saw ([#1571](https://github.com/context-dot-dev/context-typescript-sdk/issues/1571)) ([da733ee](https://github.com/context-dot-dev/context-typescript-sdk/commit/da733eed4a52641246d71a24308c8b72094e9a4c)) +* **scrape:** keep the relevant sections of long pages for JSON extraction ([#1582](https://github.com/context-dot-dev/context-typescript-sdk/issues/1582)) ([8891890](https://github.com/context-dot-dev/context-typescript-sdk/commit/8891890369c39d18404d2859a6c181ed14d185bb)) +* **search:** shorter default page-read budget and blocked-page codes for search results ([#1573](https://github.com/context-dot-dev/context-typescript-sdk/issues/1573)) ([429afc2](https://github.com/context-dot-dev/context-typescript-sdk/commit/429afc288ed925f75a5b18a9204a47df0c65f869)) + ## [3.4.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.3.0...v3.4.0) (2026-09-30) diff --git a/package.json b/package.json index 066a8abe..1a6397a9 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.4.0", + "version": "3.5.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index d8607e36..ce3f15b1 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.4.0'; // x-release-please-version +export const VERSION = '3.5.0'; // x-release-please-version From 169b8b785578f0f73e920b9e989df9bacc69f111 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 8 Oct 2026 18:37:38 +0000 Subject: [PATCH 147/232] Generate SDK --- README.md | 51 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 36 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 08d23b4e..a26beef8 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Context Dev TypeScript API Library +# Context.dev TypeScript SDK API Library [![NPM version]()](https://npmjs.org/package/context.dev) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/context.dev) @@ -26,9 +26,12 @@ const client = new ContextDev({ apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted }); -const brand = await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }); +const page = await client.web.scrape({ + formats: { markdown: true, html: true }, + url: 'https://example.com', +}); -console.log(brand.request_id); +console.log(page.request_id); ``` ### Request & Response types @@ -43,8 +46,11 @@ const client = new ContextDev({ apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted }); -const params: ContextDev.BrandRetrieveParams = { domain: 'REPLACE_ME', type: 'by_domain' }; -const brand: ContextDev.BrandRetrieveResponse = await client.brand.retrieve(params); +const params: ContextDev.WebScrapeParams = { + formats: { markdown: true }, + url: 'https://example.com', +}; +const page: ContextDev.WebScrapeResponse = await client.web.scrape(params); ``` Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors. @@ -57,8 +63,11 @@ a subclass of `APIError` will be thrown: ```ts -const brand = await client.brand - .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }) +const page = await client.web + .scrape({ + formats: { markdown: true }, + url: 'https://example.com', + }) .catch(async (err) => { if (err instanceof ContextDev.APIError) { console.log(err.status); // 400 @@ -99,7 +108,10 @@ const client = new ContextDev({ }); // Or, configure per-request: -await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }, { +await client.web.scrape({ + formats: { markdown: true }, + url: 'https://example.com', +}, { maxRetries: 5, }); ``` @@ -116,7 +128,10 @@ const client = new ContextDev({ }); // Override per-request: -await client.brand.retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }, { +await client.web.scrape({ + formats: { markdown: true }, + url: 'https://example.com', +}, { timeout: 5 * 1000, }); ``` @@ -139,17 +154,23 @@ Unlike `.asResponse()` this method consumes the body, returning once it is parse ```ts const client = new ContextDev(); -const response = await client.brand - .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }) +const response = await client.web + .scrape({ + formats: { markdown: true }, + url: 'https://example.com', + }) .asResponse(); console.log(response.headers.get('X-My-Header')); console.log(response.statusText); // access the underlying Response object -const { data: brand, response: raw } = await client.brand - .retrieve({ domain: 'REPLACE_ME', type: 'by_domain' }) +const { data: page, response: raw } = await client.web + .scrape({ + formats: { markdown: true }, + url: 'https://example.com', + }) .withResponse(); console.log(raw.headers.get('X-My-Header')); -console.log(brand.request_id); +console.log(page.request_id); ``` ### Logging @@ -229,7 +250,7 @@ parameter. This library doesn't validate at runtime that the request matches the send will be sent as-is. ```ts -client.brand.retrieve({ +client.web.scrape({ // ... // @ts-expect-error baz is not yet public baz: 'undocumented option', From 7969bc95e11a7e77645b7ad3af097c406f9a7e12 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 9 Oct 2026 22:05:22 +0000 Subject: [PATCH 148/232] feat(web-search): charge markdown per delivered page (#1729) Stainless-Generated-From: be82b9e68994bfb073702597f4bb04256b02f170 --- src/resources/web.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 55816804..f775d2e3 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -3476,7 +3476,7 @@ export namespace WebSearchParams { */ export interface MarkdownOptions { /** - * Scrape each result to Markdown. Adds 1 credit per 10 results. + * Scrape each result to Markdown. Adds 1 credit per result with Markdown. */ enabled?: boolean; From af15286afa9d946c6e27fc9075f685bfc57d70c2 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 14 Oct 2026 06:31:13 +0000 Subject: [PATCH 149/232] feat(scrape): add login profiles for authenticated scraping (#1617) Stainless-Generated-From: 83b55a59af3ff2862bb5580e389604a3e8dc522d --- src/resources/web.ts | 54 +++++++++++++++++++++++++++++++++ tests/api-resources/web.test.ts | 1 + 2 files changed, 55 insertions(+) diff --git a/src/resources/web.ts b/src/resources/web.ts index f775d2e3..79aa6061 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -960,6 +960,12 @@ export interface WebScrapeResponse { */ product: WebScrapeResponse.Product; + /** + * Authenticated browser profile used for this scrape, or null when no profile was + * requested. New and existing profile requests both return the profile ID. + */ + profile: WebScrapeResponse.Profile | null; + /** * Unique ID of this request, also in `X-Request-Id`. Include it when contacting * support. @@ -1514,6 +1520,18 @@ export namespace WebScrapeResponse { } } + /** + * Authenticated browser profile used for this scrape, or null when no profile was + * requested. New and existing profile requests both return the profile ID. + */ + export interface Profile { + /** + * Save this ID after creating a profile, then reuse it as + * sharedParams.profile.profileId with type "existing". + */ + id: string; + } + /** * Screenshot as a base64 image data URL. */ @@ -2633,6 +2651,13 @@ export namespace WebScrapeParams { */ parsers?: SharedParams.Parsers; + /** + * Create or reuse an authenticated browser profile. Requires a paid plan and an + * HTTPS target. Profiles persist session state, bypass shared caches, and cannot + * be combined with ZDR, custom headers, or raw bytes. + */ + profile?: SharedParams.Existing | SharedParams.New; + /** * Wait for CSS animations to finish before capture. Defaults to `true` when * `screenshot` is requested. @@ -2753,6 +2778,35 @@ export namespace WebScrapeParams { } } + export interface Existing { + /** + * The ID returned in profile.id by an earlier scrape. + */ + profileId: string; + + /** + * Reuse a saved browser profile. + */ + type: 'existing'; + } + + export interface New { + /** + * Username or email for the target website. + */ + identifier: string; + + /** + * Password used to sign in. It is never stored in the profile. + */ + password: string; + + /** + * Sign in and create a browser profile. + */ + type: 'new'; + } + /** * Browser size in pixels. Omit for 1920 × 1080. When provided, missing dimensions * default to 1440 × 900. diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 2e7bf681..683490de 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -192,6 +192,7 @@ describe('resource web', () => { startPage: 1, }, }, + profile: { profileId: 'prof_210b9798eb53baa4e69d31c1071cf03d', type: 'existing' }, settleAnimations: true, theme: 'light', viewport: { height: 240, width: 240 }, From f591111493f9434d35df95249466aaf6bf8f001b Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 14 Oct 2026 07:03:31 +0000 Subject: [PATCH 150/232] feat(scrape): add prebuilt Google Maps parsing (#1824) Stainless-Generated-From: 5c5ca80e5cfac319dbd985f92393d8b61f29a811 --- src/resources/web.ts | 50 ++++++++++++++++++++++++--------- tests/api-resources/web.test.ts | 1 + 2 files changed, 38 insertions(+), 13 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 79aa6061..1c4e64d1 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -950,8 +950,9 @@ export interface WebScrapeResponse { metadata: WebScrapeResponse.Metadata; /** - * Fields from `parseParams.rules`, after content filters. Unmatched fields are - * `null` (`[]` for lists). + * Custom rules return fields after content filters; unmatched fields are null ([] + * for lists). The google-maps parser returns business records in data.results and + * reads Maps data directly, independently of DOM filters and other outputs. */ parsed: WebScrapeResponse.Parsed; @@ -1339,8 +1340,9 @@ export namespace WebScrapeResponse { } /** - * Fields from `parseParams.rules`, after content filters. Unmatched fields are - * `null` (`[]` for lists). + * Custom rules return fields after content filters; unmatched fields are null ([] + * for lists). The google-maps parser returns business records in data.results and + * reads Maps data directly, independently of DOM filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1352,6 +1354,12 @@ export namespace WebScrapeResponse { */ success: boolean | null; + /** + * The selected prebuilt parser name, or custom when type is omitted, custom rules + * are used, or parsing is not requested. + */ + type: 'custom' | 'google-maps'; + /** * Why the output failed. Present only when `success` is `false`. */ @@ -2352,7 +2360,7 @@ export interface WebScrapeParams { /** * Requires `formats.parse: true`; required when it is set. */ - parseParams?: WebScrapeParams.ParseParams; + parseParams?: WebScrapeParams.CustomParser | WebScrapeParams.PrebuiltParser; /** * Product options. Requires formats.product: true. @@ -2422,7 +2430,7 @@ export namespace WebScrapeParams { markdown?: boolean; /** - * Fields extracted with `parseParams.rules`, returned as `parsed`. + * Fields extracted with custom rules or a prebuilt parser, returned as `parsed`. */ parse?: boolean; @@ -2504,18 +2512,20 @@ export namespace WebScrapeParams { inlineImages?: 'placeholder' | 'preserve'; } - /** - * Requires `formats.parse: true`; required when it is set. - */ - export interface ParseParams { + export interface CustomParser { /** * Field names mapped to CSS selectors (`h1`, `a@href`) or rule objects. Max 100 * fields, 5 levels. */ - rules: { [key: string]: string | ParseParams.UnionMember1 }; + rules: { [key: string]: string | CustomParser.UnionMember1 }; + + /** + * Extract fields using custom CSS rules. This is the default when type is omitted. + */ + type?: 'custom'; } - export namespace ParseParams { + export namespace CustomParser { export interface UnionMember1 { /** * CSS selector to match within the current page or parent rule. @@ -2535,6 +2545,20 @@ export namespace WebScrapeParams { } } + export interface PrebuiltParser { + /** + * Parse Google Maps business data into data.results. Accepts Maps place, search, + * and internal data URLs. Uses a US exit and English labels regardless of hl or + * Accept-Language, and reads Maps data independently of DOM filters. + */ + parser: 'google-maps'; + + /** + * Use a prebuilt parser instead of custom rules. + */ + type: 'prebuilt'; + } + /** * Product options. Requires formats.product: true. */ @@ -2654,7 +2678,7 @@ export namespace WebScrapeParams { /** * Create or reuse an authenticated browser profile. Requires a paid plan and an * HTTPS target. Profiles persist session state, bypass shared caches, and cannot - * be combined with ZDR, custom headers, or raw bytes. + * be combined with ZDR, custom headers, raw bytes, or prebuilt parsers. */ profile?: SharedParams.Existing | SharedParams.New; diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 683490de..899c1b15 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -172,6 +172,7 @@ describe('resource web', () => { type: 'list', }, }, + type: 'custom', }, productParams: { dedupeImages: true }, screenshotParams: { area: 'viewport', format: 'png' }, From a164793925ce33e276548bdd98f565fe443830a3 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Wed, 14 Oct 2026 09:05:10 +0200 Subject: [PATCH 151/232] release: 3.6.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 18 ++++++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 21 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 3cf104e9..dc703804 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.5.0" + ".": "3.6.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 829a2cf9..0733bb3c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,23 @@ # Changelog +## [3.6.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.5.0...v3.6.0) (2026-10-14) + + +### Features + +* **scrape:** add login profiles for authenticated scraping ([#1617](https://github.com/context-dot-dev/context-typescript-sdk/issues/1617)) ([af15286](https://github.com/context-dot-dev/context-typescript-sdk/commit/af15286afa9d946c6e27fc9075f685bfc57d70c2)) +* **scrape:** add prebuilt Google Maps parsing ([#1824](https://github.com/context-dot-dev/context-typescript-sdk/issues/1824)) ([f591111](https://github.com/context-dot-dev/context-typescript-sdk/commit/f591111493f9434d35df95249466aaf6bf8f001b)) +* **web-search:** charge markdown per delivered page ([#1729](https://github.com/context-dot-dev/context-typescript-sdk/issues/1729)) ([7969bc9](https://github.com/context-dot-dev/context-typescript-sdk/commit/7969bc95e11a7e77645b7ad3af097c406f9a7e12)) + + +### Documentation + +* demonstrate scraping formats throughout README ([e9b2400](https://github.com/context-dot-dev/context-typescript-sdk/commit/e9b2400177404d9ff436ab86c75135d29c046568)) +* format capability table ([dadbc3a](https://github.com/context-dot-dev/context-typescript-sdk/commit/dadbc3a86d3e4edbafb725a2b56191c23871d096)) +* lead README with Context.dev capabilities ([ea754f3](https://github.com/context-dot-dev/context-typescript-sdk/commit/ea754f3369c731dd8ba95d89ba065efa798dc27e)) +* reconcile custom scraping README with generated examples ([085efb2](https://github.com/context-dot-dev/context-typescript-sdk/commit/085efb2b0b7501f2cf3cc176e4de2e621a46474b)) +* remove Stainless README attribution ([2628c22](https://github.com/context-dot-dev/context-typescript-sdk/commit/2628c22cdc48e011546ba0e0ef45d2e3f7fe8b53)) + ## [3.5.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.4.0...v3.5.0) (2026-10-07) diff --git a/package.json b/package.json index 1a6397a9..392bed8a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.5.0", + "version": "3.6.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index ce3f15b1..73e38377 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.5.0'; // x-release-please-version +export const VERSION = '3.6.0'; // x-release-please-version From 06afee30979ed4ce08b6e2eb9062a06d916296c9 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 14 Oct 2026 20:09:45 +0000 Subject: [PATCH 152/232] feat(search): allow requesting a single result (#1880) Stainless-Generated-From: 3c8b0f0170903469ce6ea534cc3ae74685ae0f55 --- src/resources/web.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 1c4e64d1..894ec378 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -3506,7 +3506,7 @@ export interface WebSearchParams { markdownOptions?: WebSearchParams.MarkdownOptions | null; /** - * Number of results to request and return (10–100). Defaults to 10. + * Number of results to request and return (1–100). Defaults to 10. */ numResults?: number; From 9ea0075732b70dcc403ae6479cd453835471d369 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 14 Oct 2026 21:29:40 +0000 Subject: [PATCH 153/232] feat(scrape): add Google Play app and reviews prebuilt parsers (#1857) feat(scrape): add App Store app and reviews prebuilt parsers (#1859) feat(scrape): add emails prebuilt parser (#1862) feat(scrape): add phone-numbers prebuilt parser (#1863) feat(scrape): add links prebuilt parser (#1865) Stainless-Generated-From: d0a6c06d8214520954549f79b27a52384c8f1d90 --- src/resources/web.ts | 64 +++++++++++++++++++++++++++++++++++++------- 1 file changed, 54 insertions(+), 10 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index 894ec378..d9fc7a82 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -951,8 +951,12 @@ export interface WebScrapeResponse { /** * Custom rules return fields after content filters; unmatched fields are null ([] - * for lists). The google-maps parser returns business records in data.results and - * reads Maps data directly, independently of DOM filters and other outputs. + * for lists). The google-maps parser returns business records in data.results, and + * the google-play parser returns one app record as data, google-play-reviews + * returns data.reviews, app-store and app-store-reviews do the same for the App + * Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, + * and data.links from the rendered page; the store and Maps parsers read their + * data directly, independently of DOM filters and other outputs. */ parsed: WebScrapeResponse.Parsed; @@ -1341,8 +1345,12 @@ export namespace WebScrapeResponse { /** * Custom rules return fields after content filters; unmatched fields are null ([] - * for lists). The google-maps parser returns business records in data.results and - * reads Maps data directly, independently of DOM filters and other outputs. + * for lists). The google-maps parser returns business records in data.results, and + * the google-play parser returns one app record as data, google-play-reviews + * returns data.reviews, app-store and app-store-reviews do the same for the App + * Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, + * and data.links from the rendered page; the store and Maps parsers read their + * data directly, independently of DOM filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1358,7 +1366,16 @@ export namespace WebScrapeResponse { * The selected prebuilt parser name, or custom when type is omitted, custom rules * are used, or parsing is not requested. */ - type: 'custom' | 'google-maps'; + type: + | 'custom' + | 'google-maps' + | 'google-play' + | 'google-play-reviews' + | 'app-store' + | 'app-store-reviews' + | 'emails' + | 'phone-numbers' + | 'links'; /** * Why the output failed. Present only when `success` is `false`. @@ -2547,11 +2564,38 @@ export namespace WebScrapeParams { export interface PrebuiltParser { /** - * Parse Google Maps business data into data.results. Accepts Maps place, search, - * and internal data URLs. Uses a US exit and English labels regardless of hl or - * Accept-Language, and reads Maps data independently of DOM filters. - */ - parser: 'google-maps'; + * google-maps parses Google Maps business data into data.results. Accepts Maps + * place, search, and internal data URLs. Uses a US exit and English labels + * regardless of hl or Accept-Language. google-play parses a Play Store app into + * data: details, developer contact, ratings, price, permissions, and data safety. + * google-play-reviews returns the 200 newest reviews of the app, with developer + * replies, in data.reviews. Both Play parsers accept app details URLs + * (play.google.com/store/apps/details?id=…); hl and gl set the language and + * storefront, defaulting to en and us. app-store parses an App Store app into + * data: details, developer, ratings, price, version, and screenshots. + * app-store-reviews returns up to the 500 newest reviews in data.reviews. Both App + * Store parsers accept app URLs (apps.apple.com/us/app/…/id…); the country in the + * path sets the storefront, defaulting to us. emails accepts any page and returns + * its email addresses as data.emails ([{ email }]), read from mailto links, + * Cloudflare-protected addresses, and visible text. phone-numbers accepts any page + * and returns its valid phone numbers in E.164 as data.phone_numbers ([{ phone + * }]), read from tel links and visible text; numbers without a country code are + * read for the country of the site TLD, defaulting to US. links accepts any page + * and returns its unique http(s) links as data.links ([{ url, text }]), with + * absolute URLs; text falls back to aria-label or image alt and is null when a + * link has none. The emails parser reads the rendered page and respects content + * filters; the other prebuilt parsers read their data independently of DOM + * filters. + */ + parser: + | 'google-maps' + | 'google-play' + | 'google-play-reviews' + | 'app-store' + | 'app-store-reviews' + | 'emails' + | 'phone-numbers' + | 'links'; /** * Use a prebuilt parser instead of custom rules. From 9cc6cfceebd5ec12c4ee6dccceb2628a8574625a Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 16 Oct 2026 04:24:30 +0000 Subject: [PATCH 154/232] feat(scrape): list browser profiles and label them with descriptions (#1914) feat(search): order company search results by headcount, traffic, funding or founding year (#1916) Stainless-Generated-From: 32e530836b8e0fc840803eddc9ebef1a7bff5a16 --- .stats.yml | 2 +- api.md | 12 +++ src/client.ts | 5 + src/resources/browser.ts | 3 + src/resources/browser/browser.ts | 19 ++++ src/resources/browser/index.ts | 4 + src/resources/browser/profiles.ts | 99 ++++++++++++++++++++ src/resources/index.ts | 1 + src/resources/web.ts | 5 + tests/api-resources/browser/profiles.test.ts | 33 +++++++ 10 files changed, 182 insertions(+), 1 deletion(-) create mode 100644 src/resources/browser.ts create mode 100644 src/resources/browser/browser.ts create mode 100644 src/resources/browser/index.ts create mode 100644 src/resources/browser/profiles.ts create mode 100644 tests/api-resources/browser/profiles.test.ts diff --git a/.stats.yml b/.stats.yml index de0574c0..c7c071bd 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 44 +configured_endpoints: 45 diff --git a/api.md b/api.md index ed4b2339..a00558e2 100644 --- a/api.md +++ b/api.md @@ -186,6 +186,18 @@ Methods: - client.logs.retrieve(requestID) -> LogRetrieveResponse - client.logs.list({ ...params }) -> LogListResponse +# Browser + +## Profiles + +Types: + +- ProfileListResponse + +Methods: + +- client.browser.profiles.list({ ...params }) -> ProfileListResponse + # Feedback Types: diff --git a/src/client.ts b/src/client.ts index f8ca469f..05af2c84 100644 --- a/src/client.ts +++ b/src/client.ts @@ -100,6 +100,7 @@ import { WebWebCrawlMdParams, WebWebCrawlMdResponse, } from './resources/web'; +import { Browser } from './resources/browser/browser'; import { RetryConfig, Webhooks } from './resources/webhooks/webhooks'; import { type Fetch } from './internal/builtin-types'; import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers'; @@ -841,6 +842,7 @@ export class ContextDev { * Read your organization's API request logs. */ logs: API.Logs = new API.Logs(this); + browser: API.Browser = new API.Browser(this); /** * Report API issues and documentation mismatches. */ @@ -858,6 +860,7 @@ ContextDev.Webhooks = Webhooks; ContextDev.People = People; ContextDev.News = News; ContextDev.Logs = Logs; +ContextDev.Browser = Browser; ContextDev.Feedback = Feedback; export declare namespace ContextDev { @@ -978,6 +981,8 @@ export declare namespace ContextDev { type LogListParams as LogListParams, }; + export { Browser as Browser }; + export { Feedback as Feedback, type FeedbackSubmitResponse as FeedbackSubmitResponse, diff --git a/src/resources/browser.ts b/src/resources/browser.ts new file mode 100644 index 00000000..53b35d9f --- /dev/null +++ b/src/resources/browser.ts @@ -0,0 +1,3 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export * from './browser/index'; diff --git a/src/resources/browser/browser.ts b/src/resources/browser/browser.ts new file mode 100644 index 00000000..94b7c271 --- /dev/null +++ b/src/resources/browser/browser.ts @@ -0,0 +1,19 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../../core/resource'; +import * as ProfilesAPI from './profiles'; +import { ProfileListParams, ProfileListResponse, Profiles } from './profiles'; + +export class Browser extends APIResource { + profiles: ProfilesAPI.Profiles = new ProfilesAPI.Profiles(this._client); +} + +Browser.Profiles = Profiles; + +export declare namespace Browser { + export { + Profiles as Profiles, + type ProfileListResponse as ProfileListResponse, + type ProfileListParams as ProfileListParams, + }; +} diff --git a/src/resources/browser/index.ts b/src/resources/browser/index.ts new file mode 100644 index 00000000..1e5b73fb --- /dev/null +++ b/src/resources/browser/index.ts @@ -0,0 +1,4 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export { Browser } from './browser'; +export { Profiles, type ProfileListResponse, type ProfileListParams } from './profiles'; diff --git a/src/resources/browser/profiles.ts b/src/resources/browser/profiles.ts new file mode 100644 index 00000000..8d449034 --- /dev/null +++ b/src/resources/browser/profiles.ts @@ -0,0 +1,99 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../../core/resource'; +import { APIPromise } from '../../core/api-promise'; +import { RequestOptions } from '../../internal/request-options'; + +/** + * See the authenticated browser profiles your organization created. + */ +export class Profiles extends APIResource { + /** + * List the browser profiles your organization created with `/web/scrape`, newest + * first. + */ + list( + query: ProfileListParams | null | undefined = {}, + options?: RequestOptions, + ): APIPromise { + return this._client.get('/org/browser/profiles', { query, ...options }); + } +} + +export interface ProfileListResponse { + /** + * Browser profiles, newest first. + */ + data: Array; + + /** + * Whether a next page exists. + */ + has_more: boolean; + + /** + * Pass as `cursor` to fetch the next page. + */ + next_cursor: string | null; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: ProfileListResponse.KeyMetadata; +} + +export namespace ProfileListResponse { + export interface Data { + /** + * Profile ID to pass as `sharedParams.profile.profileId` on `/web/scrape`. + */ + id: string; + + /** + * When the profile was created. + */ + created_at: string; + + /** + * The description supplied when the profile was created, or null. + */ + description: string | null; + } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + +export interface ProfileListParams { + /** + * The `next_cursor` from the previous page. + */ + cursor?: string; + + /** + * Number of profiles per page. + */ + limit?: number; +} + +export declare namespace Profiles { + export { type ProfileListResponse as ProfileListResponse, type ProfileListParams as ProfileListParams }; +} diff --git a/src/resources/index.ts b/src/resources/index.ts index 1e1402fc..8b696005 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -23,6 +23,7 @@ export { type BrandRetrieveParams, type BrandSearchParams, } from './brand'; +export { Browser } from './browser/browser'; export { Feedback, type FeedbackSubmitResponse, type FeedbackSubmitParams } from './feedback'; export { Industry, diff --git a/src/resources/web.ts b/src/resources/web.ts index d9fc7a82..cbdb20ea 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2873,6 +2873,11 @@ export namespace WebScrapeParams { * Sign in and create a browser profile. */ type: 'new'; + + /** + * Optional label shown when listing profiles with `GET /org/browser/profiles`. + */ + description?: string; } /** diff --git a/tests/api-resources/browser/profiles.test.ts b/tests/api-resources/browser/profiles.test.ts new file mode 100644 index 00000000..e34e2591 --- /dev/null +++ b/tests/api-resources/browser/profiles.test.ts @@ -0,0 +1,33 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import ContextDev from 'context.dev'; + +const client = new ContextDev({ + apiKey: 'My API Key', + baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', +}); + +describe('resource profiles', () => { + // Mock server tests are disabled + test.skip('list', async () => { + const responsePromise = client.browser.profiles.list(); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('list: request options and params are passed correctly', async () => { + // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error + await expect( + client.browser.profiles.list( + { cursor: 'prof_210b9798eb53baa4e69d31c1071cf03d', limit: 1 }, + { path: '/_stainless_unknown_path' }, + ), + ).rejects.toThrow(ContextDev.NotFoundError); + }); +}); From c447e68b5d39b322d2c159a46938cce67e4c8a16 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 16 Oct 2026 05:07:29 +0000 Subject: [PATCH 155/232] feat(batch): support Scrape Anything batches up to 100k URLs (#1883) Stainless-Generated-From: 4b4aa0e153cde0662b797572d02af5e7a167a089 --- src/resources/batch.ts | 4352 +++++++++++++++++++---------- tests/api-resources/batch.test.ts | 80 +- 2 files changed, 2864 insertions(+), 1568 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 38607642..ec385dd6 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -67,8 +67,9 @@ export class Batch extends APIResource { } /** - * Page through a finished batch’s results as JSON. Results remain available for - * 180 days. + * Page through a finished batch’s results as JSON. Each record contains result + * with the same outputs and per-format errors as POST /web/scrape. Results remain + * available for 180 days. * * @example * ```ts @@ -86,8 +87,10 @@ export class Batch extends APIResource { } /** - * Scrape up to 25,000 URLs, or crawl a site, asynchronously. 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. Poll + * the batch ID or receive a webhook when it finishes. * * @example * ```ts @@ -95,7 +98,6 @@ export class Batch extends APIResource { * input: { * mode: 'scrape', * data: { - * format: 'markdown', * urls: [ * { * url: 'https://example.com/products/anvil', @@ -107,7 +109,8 @@ export class Batch extends APIResource { * itemId: 'sku-2', * }, * ], - * options: { useMainContentOnly: true }, + * formats: { markdown: true, html: true }, + * sharedParams: { mainContentOnly: true }, * }, * }, * }); @@ -271,10 +274,9 @@ export interface BatchRetrieveResponse { failure: Failure | null; /** - * What each page is returned as. Matches `input.data.format` on the submit - * request. + * Outputs requested for each page. Matches input.data.formats on submission. */ - format: 'markdown' | 'html'; + formats: BatchRetrieveResponse.Formats; /** * What the submission accepted. @@ -363,6 +365,56 @@ export namespace BatchRetrieveResponse { reserved: number; } + /** + * Outputs requested for each page. Matches input.data.formats on submission. + */ + export interface Formats { + /** + * The original HTTP response body. + */ + bytes?: boolean; + + /** + * Markdown excerpts relevant to `highlightsParams.query`. + */ + highlights?: boolean; + + /** + * Rendered HTML. + */ + html?: boolean; + + /** + * Images found on the page. + */ + images?: boolean; + + /** + * An object matching `jsonParams.schema`, extracted from the page. + */ + json?: boolean; + + /** + * Page content as Markdown. + */ + markdown?: boolean; + + /** + * Fields extracted with custom rules or a prebuilt parser, returned as `parsed`. + */ + parse?: boolean; + + /** + * Product details such as name, price, and availability. + */ + product?: boolean; + + /** + * A screenshot of the page. + */ + screenshot?: boolean; + } + export interface InvalidURL { /** * Why it was rejected. @@ -519,10 +571,9 @@ export namespace BatchListResponse { failure: BatchAPI.Failure | null; /** - * What each page is returned as. Matches `input.data.format` on the submit - * request. + * Outputs requested for each page. Matches input.data.formats on submission. */ - format: 'markdown' | 'html'; + formats: Data.Formats; /** * What the submission accepted. @@ -590,6 +641,56 @@ export namespace BatchListResponse { reserved: number; } + /** + * Outputs requested for each page. Matches input.data.formats on submission. + */ + export interface Formats { + /** + * The original HTTP response body. + */ + bytes?: boolean; + + /** + * Markdown excerpts relevant to `highlightsParams.query`. + */ + highlights?: boolean; + + /** + * Rendered HTML. + */ + html?: boolean; + + /** + * Images found on the page. + */ + images?: boolean; + + /** + * An object matching `jsonParams.schema`, extracted from the page. + */ + json?: boolean; + + /** + * Page content as Markdown. + */ + markdown?: boolean; + + /** + * Fields extracted with custom rules or a prebuilt parser, returned as `parsed`. + */ + parse?: boolean; + + /** + * Product details such as name, price, and availability. + */ + product?: boolean; + + /** + * A screenshot of the page. + */ + screenshot?: boolean; + } + /** * Pages attempted so far. Use `status` to check completion. */ @@ -737,9 +838,9 @@ export interface BatchCancelResponse { credits: BatchCancelResponse.Credits; /** - * What each page is returned as. + * Outputs requested for each page. Matches input.data.formats on submission. */ - format: 'markdown' | 'html'; + formats: BatchCancelResponse.Formats; /** * What the submission accepted. @@ -800,6 +901,56 @@ export namespace BatchCancelResponse { reserved: number; } + /** + * Outputs requested for each page. Matches input.data.formats on submission. + */ + export interface Formats { + /** + * The original HTTP response body. + */ + bytes?: boolean; + + /** + * Markdown excerpts relevant to `highlightsParams.query`. + */ + highlights?: boolean; + + /** + * Rendered HTML. + */ + html?: boolean; + + /** + * Images found on the page. + */ + images?: boolean; + + /** + * An object matching `jsonParams.schema`, extracted from the page. + */ + json?: boolean; + + /** + * Page content as Markdown. + */ + markdown?: boolean; + + /** + * Fields extracted with custom rules or a prebuilt parser, returned as `parsed`. + */ + parse?: boolean; + + /** + * Product details such as name, price, and availability. + */ + product?: boolean; + + /** + * A screenshot of the page. + */ + screenshot?: boolean; + } + /** * How far the batch got before cancellation. */ @@ -881,32 +1032,22 @@ export interface BatchGetResultsResponse { export namespace BatchGetResultsResponse { /** - * A page the batch fetched successfully. + * At least one requested output succeeded. Check result.isPartial and each output + * success for incomplete results. */ export interface Ok { /** - * Whether this response came from cache. - */ - cache_metadata: Ok.CacheMetadata; - - /** - * URL the content was read from, after redirects. - */ - final_url: string; - - /** - * HTTP status of the final response, when known. + * Credits charged for this page, including OCR. Cached outputs use the same + * pricing as POST /web/scrape. */ - http_status: number | null; + credits_used: number; /** - * Metadata extracted from the scraped page HTML. + * The same response as POST /web/scrape, including per-format success, failure, + * and partial results. */ - metadata: Ok.Metadata; + result: Ok.Result; - /** - * The page was scraped. - */ status: 'ok'; /** @@ -914,1172 +1055,2515 @@ export namespace BatchGetResultsResponse { */ url: string; - /** - * Page HTML. Present on html batches, and on markdown batches submitted with - * `options.includeHTML`. - */ - html?: string; - /** * Your `itemId` from submission. */ itemId?: string; - /** - * Page content as Markdown. Present on markdown batches. - */ - markdown?: string; - /** * Caller-supplied metadata echoed from submission. */ meta?: { [key: string]: unknown }; /** - * Number of PDF pages recovered by OCR. Omitted when OCR did not run. + * PDF pages recovered by OCR. Omitted when OCR did not run. */ ocr_pages?: number; } export namespace Ok { /** - * Whether this response came from cache. + * The same response as POST /web/scrape, including per-format success, failure, + * and partial results. */ - export interface CacheMetadata { + export interface Result { /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. + * The original HTTP response body, unchanged by waits, actions, and filters. */ - age_ms: number; + bytes: Result.Bytes; /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. + * Whether this response came from cache. */ - status: 'hit' | 'miss' | 'zdr'; - } + cache_metadata: Result.CacheMetadata; - /** - * Metadata extracted from the scraped page HTML. - */ - export interface Metadata { /** - * Final URL scraped after redirects or scraper fallback, when known. Falls back to - * sourceUrl when unavailable. + * Relevant Markdown excerpts in page order. `[Heading]` adds context; `…` marks + * omitted text. */ - finalUrl: string; + highlights: Result.Highlights; /** - * Original URL requested by the caller. + * Rendered HTML after content filters. */ - sourceUrl: string; + html: Result.HTML; /** - * Additional non-social meta tags not promoted to top-level metadata fields. + * Images after content filters. `[]` when none are found. */ - additionalMeta?: { [key: string]: string | Array }; + images: Result.Images; /** - * Resolved alternate links from link rel=alternate tags. + * Object matching `jsonParams.schema`. */ - alternates?: Array; + json: Result.Json; /** - * Author metadata, when present. + * Markdown after content filters. */ - author?: string; + markdown: Result.Markdown; /** - * Resolved canonical URL, when present. + * Page metadata. Fields are omitted when not found. */ - canonicalUrl?: string; + metadata: Result.Metadata; /** - * Best description extracted from standard, Open Graph, or Twitter metadata. + * Custom rules return fields after content filters; unmatched fields are null ([] + * for lists). The google-maps parser returns business records in data.results, and + * the google-play parser returns one app record as data, google-play-reviews + * returns data.reviews, app-store and app-store-reviews do the same for the App + * Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, + * and data.links from the rendered page; the store and Maps parsers read their + * data directly, independently of DOM filters and other outputs. */ - description?: string; + parsed: Result.Parsed; /** - * Resolved favicon URL, when present. + * Product details found on the page. */ - favicon?: string; + product: Result.Product; /** - * Page headings (h1–h6) in document order, extracted from the unfiltered document. - * Capped at the first 500 headings. Omitted when the page has none. + * Authenticated browser profile used for this scrape, or null when no profile was + * requested. New and existing profile requests both return the profile ID. */ - headings?: Array; + profile: Result.Profile | null; /** - * Primary resolved preview image from Open Graph, Twitter, or image metadata. + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. */ - image?: string; + request_id: string; /** - * JSON-LD structured data blocks parsed from the page. + * Screenshot as a base64 image data URL. */ - jsonLd?: Array<{ [key: string]: unknown }>; + screenshot: Result.Screenshot; /** - * Keywords extracted from the page's keywords meta tag. + * Final URL after redirects and browser actions. */ - keywords?: Array; + url: string; /** - * Language extracted from html lang or language meta tags. + * True when at least one requested output succeeds but the response has failed or + * incomplete outputs. Absent when all requested outputs fail. */ - language?: string; + isPartial?: true; /** - * Modified timestamp/date from page metadata, when present. + * Credits this request used and your remaining balance. */ - modifiedTime?: string; + key_metadata?: Result.KeyMetadata; + } + export namespace Result { /** - * Open Graph metadata with the og: prefix removed and keys camel-cased. + * The original HTTP response body, unchanged by waits, actions, and filters. */ - openGraph?: { [key: string]: string | Array }; + export interface Bytes { + data: Bytes.Data | null; - /** - * Published timestamp/date from page metadata, when present. - */ - publishedTime?: string; + requested: boolean; - /** - * Robots meta directive, when present. - */ - robots?: string; + /** + * `true` if returned, `false` if it failed, `null` if not requested. + */ + success: boolean | null; - /** - * Site or application name from page metadata. - */ - siteName?: string; + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; + } + + export namespace Bytes { + export interface Data { + /** + * Body as base64, after HTTP decompression. Up to 50 MiB decoded. + */ + base64: string; + + contentType: string; + } + } /** - * Best title extracted from the page. + * Whether this response came from cache. */ - title?: string; + export interface CacheMetadata { + /** + * Age of the cached data in milliseconds. Zero for miss and zdr responses. + */ + age_ms: number; + + /** + * Whether the response was served from cache, required fresh work, or honored + * zero-data-retention cache bypass. + */ + status: 'hit' | 'miss' | 'zdr'; + } /** - * Twitter card metadata with the twitter: prefix removed and keys camel-cased. + * Relevant Markdown excerpts in page order. `[Heading]` adds context; `…` marks + * omitted text. */ - twitter?: { [key: string]: string | Array }; - } + export interface Highlights { + data: Array | null; + + requested: boolean; - export namespace Metadata { - export interface Alternate { /** - * Resolved alternate URL. + * `true` if returned, `false` if it failed, `null` if not requested. */ - href: string; + success: boolean | null; /** - * Language or locale for the alternate URL, when present. + * Why the output failed. Present only when `success` is `false`. */ - hreflang?: string; + error_code?: string; /** - * Alternate resource title, when present. + * Explanation of the failure and possible next steps. */ - title?: string; + message?: string; + } + + /** + * Rendered HTML after content filters. + */ + export interface HTML { + data: string | null; + + requested: boolean; /** - * Alternate resource MIME type, when present. + * `true` if returned, `false` if it failed, `null` if not requested. */ - type?: string; - } + success: boolean | null; - export interface Heading { /** - * Heading level, 1–6 (from h1–h6). + * Why the output failed. Present only when `success` is `false`. */ - level: number; + error_code?: string; /** - * Heading text with whitespace collapsed, truncated to 1000 characters. + * Explanation of the failure and possible next steps. */ - text: string; + message?: string; } - } - } - /** - * A page the batch could not fetch. - */ - export interface Error { - /** - * Why the page failed. - */ - error_code: string; + /** + * Images after content filters. `[]` when none are found. + */ + export interface Images { + data: Array | null; - /** - * Human-readable failure detail. - */ - message: string; + requested: boolean; - /** - * The page could not be scraped. - */ - status: 'error'; + /** + * `true` if returned, `false` if it failed, `null` if not requested. + */ + success: boolean | null; - /** - * URL as submitted, or as discovered by the crawl. - */ - url: string; + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; - /** - * Your `itemId` from submission. - */ - itemId?: string; + /** + * Explanation of the failure and possible next steps. + */ + message?: string; + } - /** - * Caller-supplied metadata echoed from submission. - */ - meta?: { [key: string]: unknown }; - } + export namespace Images { + export interface Data { + /** + * Alt text, if present. + */ + alt: string | null; - /** - * Credits this request used and your remaining balance. - */ - export interface KeyMetadata { - /** - * Credits charged for this request. - */ - credits_consumed: number; + /** + * Image URL, or a data URI for inline images. + */ + url: string; + + classification?: + | 'photography' + | 'illustration' + | 'logo' + | 'wordmark' + | 'icon' + | 'pattern' + | 'graphic' + | 'other'; - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} + /** + * Hosted image URL, valid for 24 hours after capture. Requires `file` enrichment + * and ZDR disabled. + */ + fileUrl?: string; -export interface BatchSubmitResponse { - /** - * Batch ID. Poll GET /batch/{batch_id} with it. - */ - id: string; + height?: number; - /** - * Whether this response came from cache. - */ - cache_metadata: BatchSubmitResponse.CacheMetadata; + width?: number; + } + } - /** - * Crawl settings as submitted. - */ - crawl: CrawlControls | null; + /** + * Object matching `jsonParams.schema`. + */ + export interface Json { + data: { [key: string]: unknown } | null; - /** - * When the batch was created. - */ - created_at: string; + requested: boolean; - /** - * What accepting this batch cost. - */ - credits: BatchSubmitResponse.Credits; + /** + * `true` if returned, `false` if it failed, `null` if not requested. + */ + success: boolean | null; - /** - * What each page will be returned as. - */ - format: 'markdown' | 'html'; + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; - /** - * What the submission accepted. - */ - input: Intake; + /** + * True when the page was too long to read in full, so values found only in the + * unread parts may be missing. + */ + isTruncated?: true; - /** - * Rejected URLs (first 100). - */ - invalid_urls: Array; + /** + * Explanation of the failure and possible next steps. + */ + message?: string; + } - /** - * How pages will be selected. - */ - mode: 'scrape' | 'crawl'; + /** + * Markdown after content filters. + */ + export interface Markdown { + data: string | null; - /** - * Unique ID of this request, also in `X-Request-Id`. Include it when contacting - * support. - */ - request_id: string; + requested: boolean; - /** - * Always `queued`. An accepted batch has not started yet. - */ - status: 'queued'; + /** + * `true` if returned, `false` if it failed, `null` if not requested. + */ + success: boolean | null; - /** - * Tags stored on the batch. - */ - tags: Array; + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; - /** - * API key usage for this request. - */ - key_metadata?: BatchSubmitResponse.KeyMetadata; + /** + * Explanation of the failure and possible next steps. + */ + message?: string; + } - /** - * Secret for verifying `X-Context-Signature`. Only submit returns it, so store it. - */ - webhook_secret?: string; -} + /** + * Page metadata. Fields are omitted when not found. + */ + export interface Metadata { + /** + * Additional non-social meta tags not promoted to top-level metadata fields. + */ + additionalMeta?: { [key: string]: string | Array }; -export namespace BatchSubmitResponse { - /** - * Whether this response came from cache. - */ - export interface CacheMetadata { - /** - * Age of the cached data in milliseconds. Zero for miss and zdr responses. - */ - age_ms: number; + /** + * Resolved alternate links from link rel=alternate tags. + */ + alternates?: Array; - /** - * Whether the response was served from cache, required fresh work, or honored - * zero-data-retention cache bypass. - */ - status: 'hit' | 'miss' | 'zdr'; - } + /** + * Author metadata, when present. + */ + author?: string; - /** - * What accepting this batch cost. - */ - export interface Credits { - /** - * Credits held at submission. - */ - reserved: number; - } + /** + * Resolved canonical URL, when present. + */ + canonicalUrl?: string; - export interface InvalidURL { - /** - * Why it was rejected. - */ - reason: string; + /** + * Best description extracted from standard, Open Graph, or Twitter metadata. + */ + description?: string; - /** - * Rejected URL. - */ - url: string; - } + /** + * Resolved favicon URL, when present. + */ + favicon?: string; - /** - * API key usage for this request. - */ - export interface KeyMetadata { - /** - * Credits charged for this request. - */ - credits_consumed: number; + /** + * Up to 500 h1–h6 headings in document order, before content filtering. + */ + headings?: Array; - /** - * Credits remaining for your organization. - */ - credits_remaining: number; - } -} + /** + * Primary resolved preview image from Open Graph, Twitter, or image metadata. + */ + image?: string; -export interface BatchListParams { - /** - * Cursor from the previous page. - */ - cursor?: string; + /** + * JSON-LD structured data blocks parsed from the page. + */ + jsonLd?: Array<{ [key: string]: unknown }>; - /** - * Batches per page. Defaults to 25. - */ - limit?: number; + /** + * Keywords extracted from the page's keywords meta tag. + */ + keywords?: Array; - /** - * Free-text search term, matched against the batch id, crawl source (start URL or - * sitemap domain), and tags. - */ - q?: string; + /** + * Language extracted from html lang or language meta tags. + */ + language?: string; - /** - * `prefix` for as-you-type prefix matching (default), `exact` for full-token - * matching. - */ - search_type?: 'exact' | 'prefix'; + /** + * Modified timestamp/date from page metadata, when present. + */ + modifiedTime?: string; - /** - * Filter by status. - */ - status?: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; + /** + * Open Graph metadata with the og: prefix removed and keys camel-cased. + */ + openGraph?: { [key: string]: string | Array }; - /** - * Tags to filter by (matches batches having any of them). Pass repeated `tags` - * params or one comma-separated list, e.g. `tags=docs,competitor`. - */ - tags?: string | Array; -} + /** + * Published timestamp/date from page metadata, when present. + */ + publishedTime?: string; -export interface BatchGetResultsParams { - /** - * next_cursor from the previous page. - */ - cursor?: string; + /** + * Robots meta directive, when present. + */ + robots?: string; - /** - * Records per page. Defaults to 25. A page can close early so its payload stays - * under ~8 MB; rely on next_cursor rather than counting records. - */ - limit?: number; -} + /** + * Site or application name from page metadata. + */ + siteName?: string; -export interface BatchSubmitParams { - /** - * Body param: Choose a URL list or a site crawl. - */ - input: BatchSubmitParams.Scrape | BatchSubmitParams.Crawl; + /** + * Best title extracted from the page. + */ + title?: string; - /** - * Body param: Tags stored on the batch. Filter the batch list by them later. - */ - tags?: Array; + /** + * Twitter card metadata with the twitter: prefix removed and keys camel-cased. + */ + twitter?: { [key: string]: string | Array }; + } - /** - * Body param: Where to send the batch's final-status event. Omit `retry` for one - * attempt; `{}` uses the default retry schedule. - */ - webhook?: BatchSubmitParams.Webhook; + export namespace Metadata { + export interface Alternate { + /** + * Resolved alternate URL. + */ + href: string; - /** - * Body param: Legacy URL notified when the batch finishes. Preserves one - * best-effort attempt. Cannot be combined with webhook. - */ - webhookUrl?: string; + /** + * Language or locale for the alternate URL, when present. + */ + hreflang?: string; - /** - * Header param: Unique key per submission. Retrying with the same key and body - * returns the original batch; a different body returns `409`. - */ - 'Idempotency-Key'?: string; -} + /** + * Alternate resource title, when present. + */ + title?: string; -export namespace BatchSubmitParams { - /** - * Scrape a list of up to 25,000 URLs. - */ - export interface Scrape { - /** - * Pages to scrape and their output format. - */ - data: Scrape.Markdown | Scrape.HTML; + /** + * Alternate resource MIME type, when present. + */ + type?: string; + } - /** - * Scrape the pages in `data.urls`. - */ - mode: 'scrape'; - } + export interface Heading { + /** + * Heading level, 1–6 (from h1–h6). + */ + level: number; - export namespace Scrape { - /** - * Scrape the listed pages as Markdown. - */ - export interface Markdown { - /** - * Return page content as Markdown. - */ - format: 'markdown'; + /** + * Heading text with whitespace collapsed, truncated to 1000 characters. + */ + text: string; + } + } /** - * Pages to scrape. Maximum 25000. + * Custom rules return fields after content filters; unmatched fields are null ([] + * for lists). The google-maps parser returns business records in data.results, and + * the google-play parser returns one app record as data, google-play-reviews + * returns data.reviews, app-store and app-store-reviews do the same for the App + * Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, + * and data.links from the rendered page; the store and Maps parsers read their + * data directly, independently of DOM filters and other outputs. */ - urls: Array; + export interface Parsed { + data: { [key: string]: unknown } | null; - /** - * Options for Markdown output. - */ - options?: Markdown.Options; - } + requested: boolean; - export namespace Markdown { - /** - * A page to scrape, with optional data for matching results. - */ - export interface URL { /** - * Page URL to scrape. + * `true` if returned, `false` if it failed, `null` if not requested. */ - url: string; + success: boolean | null; /** - * Your ID for this page, returned with its result. The same URL can use different - * IDs. + * The selected prebuilt parser name, or custom when type is omitted, custom rules + * are used, or parsing is not requested. */ - itemId?: string; + type: + | 'custom' + | 'google-maps' + | 'google-play' + | 'google-play-reviews' + | 'app-store' + | 'app-store-reviews' + | 'emails' + | 'phone-numbers' + | 'links'; /** - * Custom JSON returned unchanged with this page result. + * Why the output failed. Present only when `success` is `false`. */ - meta?: { [key: string]: unknown }; + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; } /** - * Options for Markdown output. - */ - export interface Options { - /** - * Fetch from this country (ISO 3166-1 alpha-2). - */ - country?: - | 'ad' - | 'ae' - | 'af' - | 'ag' - | 'ai' - | 'al' - | 'am' - | 'ao' - | 'ar' - | 'at' - | 'au' - | 'aw' - | 'az' - | 'ba' - | 'bb' - | 'bd' - | 'be' - | 'bf' - | 'bg' - | 'bh' - | 'bi' - | 'bj' - | 'bm' - | 'bn' - | 'bo' - | 'bq' - | 'br' - | 'bs' - | 'bw' - | 'by' - | 'bz' - | 'ca' - | 'cd' - | 'cf' - | 'cg' - | 'ch' - | 'ci' - | 'cl' - | 'cm' - | 'cn' - | 'co' - | 'cr' - | 'cv' - | 'cw' - | 'cy' - | 'cz' - | 'de' - | 'dj' - | 'dk' - | 'dm' - | 'do' - | 'dz' - | 'ec' - | 'ee' - | 'eg' - | 'es' - | 'et' - | 'fi' - | 'fj' - | 'fr' - | 'ga' - | 'gb' - | 'gd' - | 'ge' - | 'gf' - | 'gg' - | 'gh' - | 'gm' - | 'gn' - | 'gp' - | 'gq' - | 'gr' - | 'gt' - | 'gu' - | 'gw' - | 'gy' - | 'hk' - | 'hn' - | 'hr' - | 'ht' - | 'hu' - | 'id' - | 'ie' - | 'il' - | 'im' - | 'in' - | 'iq' - | 'ir' - | 'is' - | 'it' - | 'je' - | 'jm' - | 'jo' - | 'jp' - | 'ke' - | 'kg' - | 'kh' - | 'kn' - | 'kr' - | 'kw' - | 'ky' - | 'kz' - | 'la' - | 'lb' - | 'lc' - | 'lk' - | 'lr' - | 'ls' - | 'lt' - | 'lu' - | 'lv' - | 'ly' - | 'ma' - | 'mc' - | 'md' - | 'me' - | 'mf' - | 'mg' - | 'mk' - | 'ml' - | 'mm' - | 'mn' - | 'mo' - | 'mq' - | 'mr' - | 'mt' - | 'mu' - | 'mv' - | 'mw' - | 'mx' - | 'my' - | 'mz' - | 'na' - | 'nc' - | 'ne' - | 'ng' - | 'ni' - | 'nl' - | 'no' - | 'np' - | 'nz' - | 'om' - | 'pa' - | 'pe' - | 'pf' - | 'pg' - | 'ph' - | 'pk' - | 'pl' - | 'pr' - | 'ps' - | 'pt' - | 'py' - | 'qa' - | 're' - | 'ro' - | 'rs' - | 'ru' - | 'rw' - | 'sa' - | 'sc' - | 'sd' - | 'se' - | 'sg' - | 'si' - | 'sk' - | 'sl' - | 'sm' - | 'sn' - | 'so' - | 'sr' - | 'ss' - | 'st' - | 'sv' - | 'sx' - | 'sy' - | 'sz' - | 'tc' - | 'td' - | 'tg' - | 'th' - | 'tj' - | 'tl' - | 'tm' - | 'tn' - | 'tr' - | 'tt' - | 'tw' - | 'tz' - | 'ua' - | 'ug' - | 'us' - | 'uy' - | 'uz' - | 'vc' - | 've' - | 'vg' - | 'vi' - | 'vn' - | 'ye' - | 'yt' - | 'za' - | 'zm' - | 'zw'; - - /** - * Remove elements matching these CSS selectors. Applied after `includeSelectors`, - * so an element matching both is removed. - */ - excludeSelectors?: Array | null; - - /** - * Also return each page's HTML in `html`. - */ - includeHTML?: boolean; - - /** - * Include image references in the Markdown. - */ - includeImages?: boolean; + * Product details found on the page. + */ + export interface Product { + data: Product.Data | null; - /** - * Include links in the Markdown. - */ - includeLinks?: boolean; + requested: boolean; /** - * Keep only elements matching these CSS selectors. Filtered pages ignore - * `maxAgeMs`. + * `true` if returned, `false` if it failed, `null` if not requested. */ - includeSelectors?: Array | null; + success: boolean | null; /** - * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 - * year (31536000000 ms). `0` fetches fresh. + * Why the output failed. Present only when `success` is `false`. */ - maxAgeMs?: number | null; + error_code?: string; /** - * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. + * Explanation of the failure and possible next steps. */ - pdf?: Options.Pdf; + message?: string; + } + + export namespace Product { + export interface Data { + /** + * Whether the page is a product detail page. + */ + isProductPage: boolean; + + /** + * The extracted product, or null when the page is not a product detail page. + */ + product: Data.Product | null; + } + + export namespace Data { + /** + * The extracted product, or null when the page is not a product detail page. + */ + export interface Product { + /** + * Stock or ordering availability. + */ + availability: + | 'in_stock' + | 'out_of_stock' + | 'limited_availability' + | 'preorder' + | 'backorder' + | 'made_to_order' + | 'discontinued' + | null; + + /** + * Brand or vendor. + */ + brand: string | null; + + /** + * Product category. + */ + category: string | null; + + /** + * ISO 4217 currency code. + */ + currency: string | null; + + /** + * Product description. + */ + description: string | null; + + /** + * Product dimensions as shown on the page. + */ + dimensions: Array; + + /** + * Key features and specifications. + */ + features: Array; + + /** + * Product image URLs, main image first. + */ + images: Array; + + /** + * Main product image URL. + */ + imageUrl: string | null; + + /** + * Product name. + */ + name: string; + + /** + * Current price. + */ + price: number | null; + + /** + * List price before any discount. + */ + regularPrice: number | null; + + /** + * Product identifier such as a SKU or model number. + */ + sku: string | null; + + /** + * Product tags. + */ + tags: Array; + + /** + * Intended audience. + */ + targetAudience: Array; + + /** + * Product variations, such as different colors or sizes, with their attributes and + * images. Empty if none are found. May not include every variation offered by the + * store. + */ + variants: Array; + } + + export namespace Product { + export interface Variant { + /** + * Explicit variant attributes such as color, size, material, pattern and + * properties declared by page. + */ + attributes: { [key: string]: string }; + + /** + * Original source image URLs explicitly attached to this variant. + */ + images: Array; + + sku: string | null; + + /** + * Variant or offer URL when provided by the source. May be shared by variants. + */ + url: string | null; + } + } + } + } + /** + * Authenticated browser profile used for this scrape, or null when no profile was + * requested. New and existing profile requests both return the profile ID. + */ + export interface Profile { /** - * Wait for CSS animations to finish before extracting, on browser-rendered pages. + * Save this ID after creating a profile, then reuse it as + * sharedParams.profile.profileId with type "existing". */ - settleAnimations?: boolean; + id: string; + } + + /** + * Screenshot as a base64 image data URL. + */ + export interface Screenshot { + data: string | null; + + requested: boolean; /** - * Shorten inline base64 image data. + * `true` if returned, `false` if it failed, `null` if not requested. */ - shortenBase64Images?: boolean; + success: boolean | null; /** - * Return the main content without navigation or footers. + * Why the output failed. Present only when `success` is `false`. */ - useMainContentOnly?: boolean; + error_code?: string; /** - * How long to wait after initial page load, in milliseconds. `0` waits 500 ms. + * Explanation of the failure and possible next steps. */ - waitForMs?: number; + message?: string; } - export namespace Options { - /** - * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } + } + } + + /** + * A page the batch could not fetch. + */ + export interface Error { + /** + * Why the page failed. + */ + error_code: string; + + /** + * Human-readable failure detail. + */ + message: string; + + /** + * The page could not be scraped. + */ + status: 'error'; + + /** + * URL as submitted, or as discovered by the crawl. + */ + url: string; + + /** + * Credits charged for this page, including OCR. Cached outputs use the same + * pricing as POST /web/scrape. + */ + credits_used?: number; + + /** + * Your `itemId` from submission. + */ + itemId?: string; + + /** + * Caller-supplied metadata echoed from submission. + */ + meta?: { [key: string]: unknown }; + + /** + * PDF pages recovered by OCR. Omitted when OCR did not run. + */ + ocr_pages?: number; + + /** + * Per-format failures when scraping returned a structured response. Omitted for + * errors that prevent scraping. + */ + result?: Error.Result; + } + + export namespace Error { + /** + * Per-format failures when scraping returned a structured response. Omitted for + * errors that prevent scraping. + */ + export interface Result { + /** + * The original HTTP response body, unchanged by waits, actions, and filters. + */ + bytes: Result.Bytes; + + /** + * Whether this response came from cache. + */ + cache_metadata: Result.CacheMetadata; + + /** + * Relevant Markdown excerpts in page order. `[Heading]` adds context; `…` marks + * omitted text. + */ + highlights: Result.Highlights; + + /** + * Rendered HTML after content filters. + */ + html: Result.HTML; + + /** + * Images after content filters. `[]` when none are found. + */ + images: Result.Images; + + /** + * Object matching `jsonParams.schema`. + */ + json: Result.Json; + + /** + * Markdown after content filters. + */ + markdown: Result.Markdown; + + /** + * Page metadata. Fields are omitted when not found. + */ + metadata: Result.Metadata; + + /** + * Custom rules return fields after content filters; unmatched fields are null ([] + * for lists). The google-maps parser returns business records in data.results, and + * the google-play parser returns one app record as data, google-play-reviews + * returns data.reviews, app-store and app-store-reviews do the same for the App + * Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, + * and data.links from the rendered page; the store and Maps parsers read their + * data directly, independently of DOM filters and other outputs. + */ + parsed: Result.Parsed; + + /** + * Product details found on the page. + */ + product: Result.Product; + + /** + * Authenticated browser profile used for this scrape, or null when no profile was + * requested. New and existing profile requests both return the profile ID. + */ + profile: Result.Profile | null; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Screenshot as a base64 image data URL. + */ + screenshot: Result.Screenshot; + + /** + * Final URL after redirects and browser actions. + */ + url: string; + + /** + * True when at least one requested output succeeds but the response has failed or + * incomplete outputs. Absent when all requested outputs fail. + */ + isPartial?: true; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: Result.KeyMetadata; + } + + export namespace Result { + /** + * The original HTTP response body, unchanged by waits, actions, and filters. + */ + export interface Bytes { + data: Bytes.Data | null; + + requested: boolean; + + /** + * `true` if returned, `false` if it failed, `null` if not requested. + */ + success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; + } + + export namespace Bytes { + export interface Data { + /** + * Body as base64, after HTTP decompression. Up to 50 MiB decoded. + */ + base64: string; + + contentType: string; + } + } + + /** + * Whether this response came from cache. + */ + export interface CacheMetadata { + /** + * Age of the cached data in milliseconds. Zero for miss and zdr responses. + */ + age_ms: number; + + /** + * Whether the response was served from cache, required fresh work, or honored + * zero-data-retention cache bypass. + */ + status: 'hit' | 'miss' | 'zdr'; + } + + /** + * Relevant Markdown excerpts in page order. `[Heading]` adds context; `…` marks + * omitted text. + */ + export interface Highlights { + data: Array | null; + + requested: boolean; + + /** + * `true` if returned, `false` if it failed, `null` if not requested. + */ + success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; + } + + /** + * Rendered HTML after content filters. + */ + export interface HTML { + data: string | null; + + requested: boolean; + + /** + * `true` if returned, `false` if it failed, `null` if not requested. + */ + success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; + } + + /** + * Images after content filters. `[]` when none are found. + */ + export interface Images { + data: Array | null; + + requested: boolean; + + /** + * `true` if returned, `false` if it failed, `null` if not requested. + */ + success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; + } + + export namespace Images { + export interface Data { + /** + * Alt text, if present. + */ + alt: string | null; + + /** + * Image URL, or a data URI for inline images. + */ + url: string; + + classification?: + | 'photography' + | 'illustration' + | 'logo' + | 'wordmark' + | 'icon' + | 'pattern' + | 'graphic' + | 'other'; + + /** + * Hosted image URL, valid for 24 hours after capture. Requires `file` enrichment + * and ZDR disabled. + */ + fileUrl?: string; + + height?: number; + + width?: number; + } + } + + /** + * Object matching `jsonParams.schema`. + */ + export interface Json { + data: { [key: string]: unknown } | null; + + requested: boolean; + + /** + * `true` if returned, `false` if it failed, `null` if not requested. + */ + success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * True when the page was too long to read in full, so values found only in the + * unread parts may be missing. + */ + isTruncated?: true; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; + } + + /** + * Markdown after content filters. + */ + export interface Markdown { + data: string | null; + + requested: boolean; + + /** + * `true` if returned, `false` if it failed, `null` if not requested. + */ + success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; + } + + /** + * Page metadata. Fields are omitted when not found. + */ + export interface Metadata { + /** + * Additional non-social meta tags not promoted to top-level metadata fields. + */ + additionalMeta?: { [key: string]: string | Array }; + + /** + * Resolved alternate links from link rel=alternate tags. + */ + alternates?: Array; + + /** + * Author metadata, when present. + */ + author?: string; + + /** + * Resolved canonical URL, when present. + */ + canonicalUrl?: string; + + /** + * Best description extracted from standard, Open Graph, or Twitter metadata. + */ + description?: string; + + /** + * Resolved favicon URL, when present. + */ + favicon?: string; + + /** + * Up to 500 h1–h6 headings in document order, before content filtering. + */ + headings?: Array; + + /** + * Primary resolved preview image from Open Graph, Twitter, or image metadata. + */ + image?: string; + + /** + * JSON-LD structured data blocks parsed from the page. + */ + jsonLd?: Array<{ [key: string]: unknown }>; + + /** + * Keywords extracted from the page's keywords meta tag. + */ + keywords?: Array; + + /** + * Language extracted from html lang or language meta tags. + */ + language?: string; + + /** + * Modified timestamp/date from page metadata, when present. + */ + modifiedTime?: string; + + /** + * Open Graph metadata with the og: prefix removed and keys camel-cased. + */ + openGraph?: { [key: string]: string | Array }; + + /** + * Published timestamp/date from page metadata, when present. + */ + publishedTime?: string; + + /** + * Robots meta directive, when present. + */ + robots?: string; + + /** + * Site or application name from page metadata. + */ + siteName?: string; + + /** + * Best title extracted from the page. + */ + title?: string; + + /** + * Twitter card metadata with the twitter: prefix removed and keys camel-cased. + */ + twitter?: { [key: string]: string | Array }; + } + + export namespace Metadata { + export interface Alternate { + /** + * Resolved alternate URL. + */ + href: string; + + /** + * Language or locale for the alternate URL, when present. + */ + hreflang?: string; + + /** + * Alternate resource title, when present. + */ + title?: string; + + /** + * Alternate resource MIME type, when present. + */ + type?: string; + } + + export interface Heading { + /** + * Heading level, 1–6 (from h1–h6). + */ + level: number; + + /** + * Heading text with whitespace collapsed, truncated to 1000 characters. + */ + text: string; + } + } + + /** + * Custom rules return fields after content filters; unmatched fields are null ([] + * for lists). The google-maps parser returns business records in data.results, and + * the google-play parser returns one app record as data, google-play-reviews + * returns data.reviews, app-store and app-store-reviews do the same for the App + * Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, + * and data.links from the rendered page; the store and Maps parsers read their + * data directly, independently of DOM filters and other outputs. + */ + export interface Parsed { + data: { [key: string]: unknown } | null; + + requested: boolean; + + /** + * `true` if returned, `false` if it failed, `null` if not requested. + */ + success: boolean | null; + + /** + * The selected prebuilt parser name, or custom when type is omitted, custom rules + * are used, or parsing is not requested. + */ + type: + | 'custom' + | 'google-maps' + | 'google-play' + | 'google-play-reviews' + | 'app-store' + | 'app-store-reviews' + | 'emails' + | 'phone-numbers' + | 'links'; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; + } + + /** + * Product details found on the page. + */ + export interface Product { + data: Product.Data | null; + + requested: boolean; + + /** + * `true` if returned, `false` if it failed, `null` if not requested. + */ + success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; + } + + export namespace Product { + export interface Data { + /** + * Whether the page is a product detail page. + */ + isProductPage: boolean; + + /** + * The extracted product, or null when the page is not a product detail page. + */ + product: Data.Product | null; + } + + export namespace Data { + /** + * The extracted product, or null when the page is not a product detail page. + */ + export interface Product { + /** + * Stock or ordering availability. + */ + availability: + | 'in_stock' + | 'out_of_stock' + | 'limited_availability' + | 'preorder' + | 'backorder' + | 'made_to_order' + | 'discontinued' + | null; + + /** + * Brand or vendor. + */ + brand: string | null; + + /** + * Product category. + */ + category: string | null; + + /** + * ISO 4217 currency code. + */ + currency: string | null; + + /** + * Product description. + */ + description: string | null; + + /** + * Product dimensions as shown on the page. + */ + dimensions: Array; + + /** + * Key features and specifications. + */ + features: Array; + + /** + * Product image URLs, main image first. + */ + images: Array; + + /** + * Main product image URL. + */ + imageUrl: string | null; + + /** + * Product name. + */ + name: string; + + /** + * Current price. + */ + price: number | null; + + /** + * List price before any discount. + */ + regularPrice: number | null; + + /** + * Product identifier such as a SKU or model number. + */ + sku: string | null; + + /** + * Product tags. + */ + tags: Array; + + /** + * Intended audience. + */ + targetAudience: Array; + + /** + * Product variations, such as different colors or sizes, with their attributes and + * images. Empty if none are found. May not include every variation offered by the + * store. + */ + variants: Array; + } + + export namespace Product { + export interface Variant { + /** + * Explicit variant attributes such as color, size, material, pattern and + * properties declared by page. + */ + attributes: { [key: string]: string }; + + /** + * Original source image URLs explicitly attached to this variant. + */ + images: Array; + + sku: string | null; + + /** + * Variant or offer URL when provided by the source. May be shared by variants. + */ + url: string | null; + } + } + } + } + + /** + * Authenticated browser profile used for this scrape, or null when no profile was + * requested. New and existing profile requests both return the profile ID. + */ + export interface Profile { + /** + * Save this ID after creating a profile, then reuse it as + * sharedParams.profile.profileId with type "existing". + */ + id: string; + } + + /** + * Screenshot as a base64 image data URL. + */ + export interface Screenshot { + data: string | null; + + requested: boolean; + + /** + * `true` if returned, `false` if it failed, `null` if not requested. + */ + success: boolean | null; + + /** + * Why the output failed. Present only when `success` is `false`. + */ + error_code?: string; + + /** + * Explanation of the failure and possible next steps. + */ + message?: string; + } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } + } + } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + +export interface BatchSubmitResponse { + /** + * Batch ID. Poll GET /batch/{batch_id} with it. + */ + id: string; + + /** + * Whether this response came from cache. + */ + cache_metadata: BatchSubmitResponse.CacheMetadata; + + /** + * Crawl settings as submitted. + */ + crawl: CrawlControls | null; + + /** + * When the batch was created. + */ + created_at: string; + + /** + * What accepting this batch cost. + */ + credits: BatchSubmitResponse.Credits; + + /** + * Outputs requested for each page. Matches input.data.formats on submission. + */ + formats: BatchSubmitResponse.Formats; + + /** + * What the submission accepted. + */ + input: Intake; + + /** + * Rejected URLs (first 100). + */ + invalid_urls: Array; + + /** + * How pages will be selected. + */ + mode: 'scrape' | 'crawl'; + + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Always `queued`. An accepted batch has not started yet. + */ + status: 'queued'; + + /** + * Tags stored on the batch. + */ + tags: Array; + + /** + * API key usage for this request. + */ + key_metadata?: BatchSubmitResponse.KeyMetadata; + + /** + * Secret for verifying `X-Context-Signature`. Only submit returns it, so store it. + */ + webhook_secret?: string; +} + +export namespace BatchSubmitResponse { + /** + * Whether this response came from cache. + */ + export interface CacheMetadata { + /** + * Age of the cached data in milliseconds. Zero for miss and zdr responses. + */ + age_ms: number; + + /** + * Whether the response was served from cache, required fresh work, or honored + * zero-data-retention cache bypass. + */ + status: 'hit' | 'miss' | 'zdr'; + } + + /** + * What accepting this batch cost. + */ + export interface Credits { + /** + * Credits held at submission. + */ + reserved: number; + } + + /** + * Outputs requested for each page. Matches input.data.formats on submission. + */ + export interface Formats { + /** + * The original HTTP response body. + */ + bytes?: boolean; + + /** + * Markdown excerpts relevant to `highlightsParams.query`. + */ + highlights?: boolean; + + /** + * Rendered HTML. + */ + html?: boolean; + + /** + * Images found on the page. + */ + images?: boolean; + + /** + * An object matching `jsonParams.schema`, extracted from the page. + */ + json?: boolean; + + /** + * Page content as Markdown. + */ + markdown?: boolean; + + /** + * Fields extracted with custom rules or a prebuilt parser, returned as `parsed`. + */ + parse?: boolean; + + /** + * Product details such as name, price, and availability. + */ + product?: boolean; + + /** + * A screenshot of the page. + */ + screenshot?: boolean; + } + + export interface InvalidURL { + /** + * Why it was rejected. + */ + reason: string; + + /** + * Rejected URL. + */ + url: string; + } + + /** + * API key usage for this request. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + +export interface BatchListParams { + /** + * Cursor from the previous page. + */ + cursor?: string; + + /** + * Batches per page. Defaults to 25. + */ + limit?: number; + + /** + * Free-text search term, matched against the batch id, crawl source (start URL or + * sitemap domain), and tags. + */ + q?: string; + + /** + * `prefix` for as-you-type prefix matching (default), `exact` for full-token + * matching. + */ + search_type?: 'exact' | 'prefix'; + + /** + * Include batches submitted with Scrape Anything formats. Defaults to false. + */ + shouldIncludeUnified?: boolean; + + /** + * Filter by status. + */ + status?: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; + + /** + * Tags to filter by (matches batches having any of them). Pass repeated `tags` + * params or one comma-separated list, e.g. `tags=docs,competitor`. + */ + tags?: string | Array; +} + +export interface BatchGetResultsParams { + /** + * next_cursor from the previous page. + */ + cursor?: string; + + /** + * Records per page. Defaults to 25. A page can close early so its payload stays + * under ~8 MB; rely on next_cursor rather than counting records. + */ + limit?: number; +} + +export interface BatchSubmitParams { + /** + * Body param: Choose a URL list or a site crawl. + */ + input: BatchSubmitParams.Scrape | BatchSubmitParams.Crawl; + + /** + * Body param: Tags stored on the batch. Filter the batch list by them later. + */ + tags?: Array; + + /** + * Body param: Where to send the batch's final-status event. Omit `retry` for one + * attempt; `{}` uses the default retry schedule. + */ + webhook?: BatchSubmitParams.Webhook; + + /** + * Body param: Legacy URL notified when the batch finishes. Preserves one + * best-effort attempt. Cannot be combined with webhook. + */ + webhookUrl?: string; + + /** + * Header param: Unique key per submission. Retrying with the same key and body + * returns the original batch; a different body returns `409`. + */ + 'Idempotency-Key'?: string; +} + +export namespace BatchSubmitParams { + /** + * Scrape a list of up to 100,000 URLs. + */ + export interface Scrape { + /** + * Use the same formats and parameters as POST /web/scrape, replacing url with + * urls. Options apply to every page. + */ + data: Scrape.Data; + + /** + * Scrape the pages in `data.urls`. + */ + mode: 'scrape'; + } + + export namespace Scrape { + /** + * Use the same formats and parameters as POST /web/scrape, replacing url with + * urls. Options apply to every page. + */ + export interface Data { + /** + * Outputs to return. Set at least one to `true`. + */ + formats: Data.Formats; + + /** + * Pages to scrape. Maximum 100000. + */ + urls: Array; + + /** + * Requires `formats.highlights: true`; required when it is set. + */ + highlightsParams?: Data.HighlightsParams; + + /** + * Image options. Requires formats.images: true. + */ + imageParams?: Data.ImageParams; + + /** + * Requires `formats.json: true`; required when it is set. + */ + jsonParams?: Data.JsonParams; + + /** + * Markdown options. Requires `formats.markdown`. + */ + markdownParams?: Data.MarkdownParams; + + /** + * Maximum age of a cached output, in milliseconds. `0` fetches fresh. Defaults to + * 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). + */ + maxAgeMs?: number; + + /** + * Requires `formats.parse: true`; required when it is set. + */ + parseParams?: Data.CustomParser | Data.PrebuiltParser; + + /** + * Product options. Requires formats.product: true. + */ + productParams?: Data.ProductParams; + + /** + * Screenshot options. Requires formats.screenshot: true. + */ + screenshotParams?: Data.ScreenshotParams; + + /** + * Browser and content settings shared by all outputs. + */ + sharedParams?: Data.SharedParams; + + /** + * Labels for tracking request usage. Not retained when zdr is enabled. + */ + tags?: Array; + + /** + * Deadline for each page, using the same behavior and defaults as POST + * /web/scrape. + */ + timeoutOpts?: Data.TimeoutOpts; + + /** + * Batches persist their results. Only disabled is supported; enabled returns + * ZDR_NOT_SUPPORTED. + */ + zdr?: 'disabled'; + } + + export namespace Data { + /** + * Outputs to return. Set at least one to `true`. + */ + export interface Formats { + /** + * The original HTTP response body. + */ + bytes?: boolean; + + /** + * Markdown excerpts relevant to `highlightsParams.query`. + */ + highlights?: boolean; + + /** + * Rendered HTML. + */ + html?: boolean; + + /** + * Images found on the page. + */ + images?: boolean; + + /** + * An object matching `jsonParams.schema`, extracted from the page. + */ + json?: boolean; + + /** + * Page content as Markdown. + */ + markdown?: boolean; + + /** + * Fields extracted with custom rules or a prebuilt parser, returned as `parsed`. + */ + parse?: boolean; + + /** + * Product details such as name, price, and availability. + */ + product?: boolean; + + /** + * A screenshot of the page. + */ + screenshot?: boolean; + } + + /** + * A page to scrape, with optional data for matching results. + */ + export interface URL { + /** + * Page URL to scrape. + */ + url: string; + + /** + * Your ID for this page, returned with its result. The same URL can use different + * IDs. + */ + itemId?: string; + + /** + * Custom JSON returned unchanged with this page result. + */ + meta?: { [key: string]: unknown }; + } + + /** + * Requires `formats.highlights: true`; required when it is set. + */ + export interface HighlightsParams { + /** + * The question or topic to find passages for. + */ + query: string; + + /** + * Maximum combined length of returned passages. + */ + maxCharacters?: number; + } + + /** + * Image options. Requires formats.images: true. + */ + export interface ImageParams { + /** + * Set `visual` to drop visual duplicates, keeping the largest copy. + */ + dedupe?: 'none' | 'visual'; + + /** + * Extra data per image: `dimensions`, `classification`, or a hosted `file` URL. + */ + enrich?: Array<'dimensions' | 'classification' | 'file'>; + } + + /** + * Requires `formats.json: true`; required when it is set. + */ + export interface JsonParams { + /** + * JSON Schema (not an example object) for a top-level object, up to 50 KB. Use + * optional or nullable fields for missing facts. + */ + schema: { [key: string]: unknown }; + + /** + * Extra guidance, such as which facts to prefer or how to read a field. + */ + instructions?: string; + } + + /** + * Markdown options. Requires `formats.markdown`. + */ + export interface MarkdownParams { + /** + * Include images in the Markdown using image syntax with URLs and alt text. + */ + includeImages?: boolean; + + /** + * Keep link URLs in the Markdown. Set false to return link text without URLs. + */ + includeLinks?: boolean; + + /** + * How base64 images appear: `placeholder` (default) or `preserve`. Requires + * `includeImages`. + */ + inlineImages?: 'placeholder' | 'preserve'; + } + + export interface CustomParser { + /** + * Field names mapped to CSS selectors (`h1`, `a@href`) or rule objects. Max 100 + * fields, 5 levels. + */ + rules: { [key: string]: string | CustomParser.UnionMember1 }; + + /** + * Extract fields using custom CSS rules. This is the default when type is omitted. + */ + type?: 'custom'; + } + + export namespace CustomParser { + export interface UnionMember1 { + /** + * CSS selector to match within the current page or parent rule. + */ + selector: string; + + /** + * Return text, HTML, an attribute such as `@href`, or nested field rules. Defaults + * to text. + */ + output?: 'text' | 'html' | string | unknown; + + /** + * Return the first match with `item` or all matches with `list`. + */ + type?: 'item' | 'list'; + } + } + + export interface PrebuiltParser { + /** + * google-maps parses Google Maps business data into data.results. Accepts Maps + * place, search, and internal data URLs. Uses a US exit and English labels + * regardless of hl or Accept-Language. google-play parses a Play Store app into + * data: details, developer contact, ratings, price, permissions, and data safety. + * google-play-reviews returns the 200 newest reviews of the app, with developer + * replies, in data.reviews. Both Play parsers accept app details URLs + * (play.google.com/store/apps/details?id=…); hl and gl set the language and + * storefront, defaulting to en and us. app-store parses an App Store app into + * data: details, developer, ratings, price, version, and screenshots. + * app-store-reviews returns up to the 500 newest reviews in data.reviews. Both App + * Store parsers accept app URLs (apps.apple.com/us/app/…/id…); the country in the + * path sets the storefront, defaulting to us. emails accepts any page and returns + * its email addresses as data.emails ([{ email }]), read from mailto links, + * Cloudflare-protected addresses, and visible text. phone-numbers accepts any page + * and returns its valid phone numbers in E.164 as data.phone_numbers ([{ phone + * }]), read from tel links and visible text; numbers without a country code are + * read for the country of the site TLD, defaulting to US. links accepts any page + * and returns its unique http(s) links as data.links ([{ url, text }]), with + * absolute URLs; text falls back to aria-label or image alt and is null when a + * link has none. The emails parser reads the rendered page and respects content + * filters; the other prebuilt parsers read their data independently of DOM + * filters. + */ + parser: + | 'google-maps' + | 'google-play' + | 'google-play-reviews' + | 'app-store' + | 'app-store-reviews' + | 'emails' + | 'phone-numbers' + | 'links'; + + /** + * Use a prebuilt parser instead of custom rules. + */ + type: 'prebuilt'; + } + + /** + * Product options. Requires formats.product: true. + */ + export interface ProductParams { + /** + * Drop visually duplicate product images, keeping the largest copy. + */ + dedupeImages?: boolean; + } + + /** + * Screenshot options. Requires formats.screenshot: true. + */ + export interface ScreenshotParams { + /** + * What to capture: `viewport`, `fullPage`, one element, or a rectangle. Max 40 + * megapixels. + */ + area?: 'viewport' | 'fullPage' | ScreenshotParams.Element | ScreenshotParams.Rectangle; + + /** + * Image format for the screenshot. + */ + format?: 'png' | 'jpeg' | 'webp'; + } + + export namespace ScreenshotParams { + export interface Element { + /** + * CSS selector matching exactly one visible element. + */ + selector: string; + } + + /** + * Pixels from the document origin. + */ + export interface Rectangle { + /** + * Height of the capture in pixels. + */ + height: number; + + /** + * Width of the capture in pixels. + */ + width: number; + + /** + * Left edge of the capture, in pixels from the document origin. + */ + x: number; + + /** + * Top edge of the capture, in pixels from the document origin. + */ + y: number; + } + } + + /** + * Browser and content settings shared by all outputs. + */ + export interface SharedParams { + /** + * Browser steps run in order before capture. Requires a paid plan. Skips the + * cache. + */ + actions?: Array< + SharedParams.Perform | SharedParams.Scroll | SharedParams.Wait | SharedParams.WaitFor + >; + + /** + * Proxy country as a two-letter code, such as `US`. Case-insensitive. + */ + country?: string; + + /** + * Accept cookie banners before actions and capture. + */ + dismissCookies?: boolean; + + /** + * Close other popups before actions and capture. + */ + dismissPopups?: boolean; + + /** + * Remove elements matching these CSS selectors. Overrides `includeSelectors`. + */ + excludeSelectors?: Array; + + /** + * HTTP headers to send to the target site. Requests with headers skip the cache. + */ + headers?: { [key: string]: string }; + + /** + * Include iframe content in HTML and text outputs. Screenshots always show visible + * frames. + */ + includeFrames?: boolean; + + /** + * Keep only elements matching these CSS selectors. + */ + includeSelectors?: Array; + + /** + * Keep only the main content. Doesn't affect `screenshot`, `bytes`, or `product`. + */ + mainContentOnly?: boolean; + + /** + * Document parsing options. + */ + parsers?: SharedParams.Parsers; + + /** + * Create or reuse an authenticated browser profile. Requires a paid plan and an + * HTTPS target. Profiles persist session state, bypass shared caches, and cannot + * be combined with ZDR, custom headers, raw bytes, or prebuilt parsers. + */ + profile?: SharedParams.Existing | SharedParams.New; + + /** + * Wait for CSS animations to finish before capture. Defaults to `true` when + * `screenshot` is requested. + */ + settleAnimations?: boolean; + + /** + * Emulate a light or dark color scheme. + */ + theme?: 'light' | 'dark'; + + /** + * Browser size in pixels. Omit for 1920 × 1080. When provided, missing dimensions + * default to 1440 × 900. + */ + viewport?: SharedParams.Viewport; + + /** + * Milliseconds, or a CSS selector to wait for, after actions. Defaults to 500 + * (2000 with frames or XML). + */ + waitFor?: number | string; + } + + export namespace SharedParams { + export interface Perform { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + type: 'perform'; + } + + export interface Scroll { + /** + * Use `scroll` to move through the page or a container. + */ + type: 'scroll'; + + /** + * Distance per scroll: pixels, one `viewport`, or `max` to reach the end. + */ + amount?: number | 'viewport' | 'max'; + + /** + * Direction to scroll. + */ + direction?: 'down' | 'up' | 'left' | 'right'; + + /** + * Maximum number of scroll steps for this action. + */ + maxScrolls?: number; + + /** + * Scroll this container. Omit to scroll the page. + */ + selector?: string; + } + + export interface Wait { + /** + * Time to pause in milliseconds before the next action. + */ + milliseconds: number; + + /** + * Use `wait` to pause for a fixed duration. + */ + type: 'wait'; + } + + export interface WaitFor { + /** + * CSS selector to wait for before continuing. + */ + selector: string; + + /** + * Use `waitFor` to wait for a matching element. + */ + type: 'waitFor'; + } + + /** + * Document parsing options. + */ + export interface Parsers { + /** + * PDF page range and OCR. + */ + pdf?: Parsers.Pdf; + } + + export namespace Parsers { + /** + * PDF page range and OCR. + */ + export interface Pdf { + /** + * Last page to parse. Must be at least `startPage`. + */ + endPage?: number; + + /** + * Set `auto` to read scanned pages with OCR. + */ + ocr?: 'off' | 'auto'; + + /** + * First page to parse, starting at 1. + */ + startPage?: number; + } + } + + export interface Existing { + /** + * The ID returned in profile.id by an earlier scrape. + */ + profileId: string; + + /** + * Reuse a saved browser profile. + */ + type: 'existing'; + } + + export interface New { + /** + * Username or email for the target website. + */ + identifier: string; + + /** + * Password used to sign in. It is never stored in the profile. + */ + password: string; + + /** + * Sign in and create a browser profile. + */ + type: 'new'; + + /** + * Optional label shown when listing profiles with `GET /org/browser/profiles`. + */ + description?: string; + } + + /** + * Browser size in pixels. Omit for 1920 × 1080. When provided, missing dimensions + * default to 1440 × 900. */ - export interface Pdf { + export interface Viewport { /** - * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must - * be >= start. + * Browser viewport height in pixels. */ - end?: number; + height?: number; /** - * Read scanned PDF pages with OCR; preserve pages that already have text. + * Browser viewport width in pixels. */ - ocr?: boolean; + width?: number; + } + } + + /** + * Deadline for each page, using the same behavior and defaults as POST + * /web/scrape. + */ + export interface TimeoutOpts { + /** + * Deadline in milliseconds. + */ + milliseconds: number; + + /** + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. "return-partial" requires at least 5000 ms. + */ + behavior?: 'fail' | 'return-partial'; + } + } + } + + /** + * Crawl pages starting from a URL or from a domain's sitemap. + */ + export interface Crawl { + /** + * Use the same formats and parameters as POST /web/scrape, replacing url with + * source. Options apply to every page. + */ + data: Crawl.Data; + + /** + * Discover and scrape pages from `data.source`. + */ + mode: 'crawl'; + } + + export namespace Crawl { + /** + * Use the same formats and parameters as POST /web/scrape, replacing url with + * source. Options apply to every page. + */ + export interface Data { + /** + * Outputs to return. Set at least one to `true`. + */ + formats: Data.Formats; + + /** + * How to find pages to crawl. + */ + source: Data.StartURL | Data.Sitemap; + + /** + * Requires `formats.highlights: true`; required when it is set. + */ + highlightsParams?: Data.HighlightsParams; + + /** + * Image options. Requires formats.images: true. + */ + imageParams?: Data.ImageParams; + + /** + * Requires `formats.json: true`; required when it is set. + */ + jsonParams?: Data.JsonParams; + + /** + * Markdown options. Requires `formats.markdown`. + */ + markdownParams?: Data.MarkdownParams; + + /** + * Maximum age of a cached output, in milliseconds. `0` fetches fresh. Defaults to + * 3 days (259200000 ms). Maximum: 1 year (31536000000 ms). + */ + maxAgeMs?: number; + + /** + * Requires `formats.parse: true`; required when it is set. + */ + parseParams?: Data.CustomParser | Data.PrebuiltParser; + + /** + * Product options. Requires formats.product: true. + */ + productParams?: Data.ProductParams; - /** - * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. - */ - shouldParse?: boolean; + /** + * Screenshot options. Requires formats.screenshot: true. + */ + screenshotParams?: Data.ScreenshotParams; - /** - * First 1-based PDF page to parse. - */ - start?: number; - } - } - } + /** + * Browser and content settings shared by all outputs. + */ + sharedParams?: Data.SharedParams; - /** - * Scrape the listed pages as HTML. - */ - export interface HTML { /** - * Return page content as HTML. + * Labels for tracking request usage. Not retained when zdr is enabled. */ - format: 'html'; + tags?: Array; /** - * Pages to scrape. Maximum 25000. + * Deadline for each page, using the same behavior and defaults as POST + * /web/scrape. */ - urls: Array; + timeoutOpts?: Data.TimeoutOpts; /** - * Options for HTML output. + * Batches persist their results. Only disabled is supported; enabled returns + * ZDR_NOT_SUPPORTED. */ - options?: HTML.Options; + zdr?: 'disabled'; } - export namespace HTML { + export namespace Data { /** - * A page to scrape, with optional data for matching results. + * Outputs to return. Set at least one to `true`. */ - export interface URL { + export interface Formats { /** - * Page URL to scrape. + * The original HTTP response body. */ - url: string; + bytes?: boolean; /** - * Your ID for this page, returned with its result. The same URL can use different - * IDs. + * Markdown excerpts relevant to `highlightsParams.query`. */ - itemId?: string; + highlights?: boolean; /** - * Custom JSON returned unchanged with this page result. + * Rendered HTML. */ - meta?: { [key: string]: unknown }; - } + html?: boolean; - /** - * Options for HTML output. - */ - export interface Options { - /** - * Fetch from this country (ISO 3166-1 alpha-2). - */ - country?: - | 'ad' - | 'ae' - | 'af' - | 'ag' - | 'ai' - | 'al' - | 'am' - | 'ao' - | 'ar' - | 'at' - | 'au' - | 'aw' - | 'az' - | 'ba' - | 'bb' - | 'bd' - | 'be' - | 'bf' - | 'bg' - | 'bh' - | 'bi' - | 'bj' - | 'bm' - | 'bn' - | 'bo' - | 'bq' - | 'br' - | 'bs' - | 'bw' - | 'by' - | 'bz' - | 'ca' - | 'cd' - | 'cf' - | 'cg' - | 'ch' - | 'ci' - | 'cl' - | 'cm' - | 'cn' - | 'co' - | 'cr' - | 'cv' - | 'cw' - | 'cy' - | 'cz' - | 'de' - | 'dj' - | 'dk' - | 'dm' - | 'do' - | 'dz' - | 'ec' - | 'ee' - | 'eg' - | 'es' - | 'et' - | 'fi' - | 'fj' - | 'fr' - | 'ga' - | 'gb' - | 'gd' - | 'ge' - | 'gf' - | 'gg' - | 'gh' - | 'gm' - | 'gn' - | 'gp' - | 'gq' - | 'gr' - | 'gt' - | 'gu' - | 'gw' - | 'gy' - | 'hk' - | 'hn' - | 'hr' - | 'ht' - | 'hu' - | 'id' - | 'ie' - | 'il' - | 'im' - | 'in' - | 'iq' - | 'ir' - | 'is' - | 'it' - | 'je' - | 'jm' - | 'jo' - | 'jp' - | 'ke' - | 'kg' - | 'kh' - | 'kn' - | 'kr' - | 'kw' - | 'ky' - | 'kz' - | 'la' - | 'lb' - | 'lc' - | 'lk' - | 'lr' - | 'ls' - | 'lt' - | 'lu' - | 'lv' - | 'ly' - | 'ma' - | 'mc' - | 'md' - | 'me' - | 'mf' - | 'mg' - | 'mk' - | 'ml' - | 'mm' - | 'mn' - | 'mo' - | 'mq' - | 'mr' - | 'mt' - | 'mu' - | 'mv' - | 'mw' - | 'mx' - | 'my' - | 'mz' - | 'na' - | 'nc' - | 'ne' - | 'ng' - | 'ni' - | 'nl' - | 'no' - | 'np' - | 'nz' - | 'om' - | 'pa' - | 'pe' - | 'pf' - | 'pg' - | 'ph' - | 'pk' - | 'pl' - | 'pr' - | 'ps' - | 'pt' - | 'py' - | 'qa' - | 're' - | 'ro' - | 'rs' - | 'ru' - | 'rw' - | 'sa' - | 'sc' - | 'sd' - | 'se' - | 'sg' - | 'si' - | 'sk' - | 'sl' - | 'sm' - | 'sn' - | 'so' - | 'sr' - | 'ss' - | 'st' - | 'sv' - | 'sx' - | 'sy' - | 'sz' - | 'tc' - | 'td' - | 'tg' - | 'th' - | 'tj' - | 'tl' - | 'tm' - | 'tn' - | 'tr' - | 'tt' - | 'tw' - | 'tz' - | 'ua' - | 'ug' - | 'us' - | 'uy' - | 'uz' - | 'vc' - | 've' - | 'vg' - | 'vi' - | 'vn' - | 'ye' - | 'yt' - | 'za' - | 'zm' - | 'zw'; - - /** - * Remove elements matching these CSS selectors. Applied after `includeSelectors`, - * so an element matching both is removed. - */ - excludeSelectors?: Array | null; - - /** - * Keep only elements matching these CSS selectors. Filtered pages ignore - * `maxAgeMs`. - */ - includeSelectors?: Array | null; - - /** - * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 - * year (31536000000 ms). `0` fetches fresh. - */ - maxAgeMs?: number | null; - - /** - * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. - */ - pdf?: Options.Pdf; - - /** - * Wait for CSS animations to finish before extracting, on browser-rendered pages. + /** + * Images found on the page. */ - settleAnimations?: boolean; + images?: boolean; /** - * Return the main content without navigation or footers. + * An object matching `jsonParams.schema`, extracted from the page. */ - useMainContentOnly?: boolean; + json?: boolean; /** - * How long to wait after initial page load, in milliseconds. `0` waits 500 ms. + * Page content as Markdown. */ - waitForMs?: number; - } + markdown?: boolean; - export namespace Options { /** - * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. + * Fields extracted with custom rules or a prebuilt parser, returned as `parsed`. */ - export interface Pdf { - /** - * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must - * be >= start. - */ - end?: number; - - /** - * Read scanned PDF pages with OCR; preserve pages that already have text. - */ - ocr?: boolean; + parse?: boolean; - /** - * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. - */ - shouldParse?: boolean; + /** + * Product details such as name, price, and availability. + */ + product?: boolean; - /** - * First 1-based PDF page to parse. - */ - start?: number; - } + /** + * A screenshot of the page. + */ + screenshot?: boolean; } - } - } - - /** - * Crawl pages starting from a URL or from a domain's sitemap. - */ - export interface Crawl { - /** - * Crawl source and output format. - */ - data: Crawl.Markdown | Crawl.HTML; - - /** - * Discover and scrape pages from `data.source`. - */ - mode: 'crawl'; - } - - export namespace Crawl { - /** - * Crawl pages and return Markdown. - */ - export interface Markdown { - /** - * Return page content as Markdown. - */ - format: 'markdown'; - /** - * How to find pages to crawl. - */ - source: Markdown.StartURL | Markdown.Sitemap; - - /** - * Options for Markdown output. - */ - options?: Markdown.Options; - } - - export namespace Markdown { /** * Discover pages by following links from one URL. */ @@ -2116,7 +3600,7 @@ export namespace BatchSubmitParams { maxDepth?: number; /** - * Maximum pages to fetch. Unused reserved credits are refunded. Maximum 25000. + * Maximum pages to fetch. Unused reserved credits are refunded. Maximum 100000. */ maxUrls?: number; @@ -2157,7 +3641,7 @@ export namespace BatchSubmitParams { */ export interface Controls { /** - * Maximum pages to fetch. Unused reserved credits are refunded. Maximum 25000. + * Maximum pages to fetch. Unused reserved credits are refunded. Maximum 100000. */ maxUrls?: number; @@ -2169,694 +3653,458 @@ export namespace BatchSubmitParams { } /** - * Options for Markdown output. - */ - export interface Options { - /** - * Fetch from this country (ISO 3166-1 alpha-2). - */ - country?: - | 'ad' - | 'ae' - | 'af' - | 'ag' - | 'ai' - | 'al' - | 'am' - | 'ao' - | 'ar' - | 'at' - | 'au' - | 'aw' - | 'az' - | 'ba' - | 'bb' - | 'bd' - | 'be' - | 'bf' - | 'bg' - | 'bh' - | 'bi' - | 'bj' - | 'bm' - | 'bn' - | 'bo' - | 'bq' - | 'br' - | 'bs' - | 'bw' - | 'by' - | 'bz' - | 'ca' - | 'cd' - | 'cf' - | 'cg' - | 'ch' - | 'ci' - | 'cl' - | 'cm' - | 'cn' - | 'co' - | 'cr' - | 'cv' - | 'cw' - | 'cy' - | 'cz' - | 'de' - | 'dj' - | 'dk' - | 'dm' - | 'do' - | 'dz' - | 'ec' - | 'ee' - | 'eg' - | 'es' - | 'et' - | 'fi' - | 'fj' - | 'fr' - | 'ga' - | 'gb' - | 'gd' - | 'ge' - | 'gf' - | 'gg' - | 'gh' - | 'gm' - | 'gn' - | 'gp' - | 'gq' - | 'gr' - | 'gt' - | 'gu' - | 'gw' - | 'gy' - | 'hk' - | 'hn' - | 'hr' - | 'ht' - | 'hu' - | 'id' - | 'ie' - | 'il' - | 'im' - | 'in' - | 'iq' - | 'ir' - | 'is' - | 'it' - | 'je' - | 'jm' - | 'jo' - | 'jp' - | 'ke' - | 'kg' - | 'kh' - | 'kn' - | 'kr' - | 'kw' - | 'ky' - | 'kz' - | 'la' - | 'lb' - | 'lc' - | 'lk' - | 'lr' - | 'ls' - | 'lt' - | 'lu' - | 'lv' - | 'ly' - | 'ma' - | 'mc' - | 'md' - | 'me' - | 'mf' - | 'mg' - | 'mk' - | 'ml' - | 'mm' - | 'mn' - | 'mo' - | 'mq' - | 'mr' - | 'mt' - | 'mu' - | 'mv' - | 'mw' - | 'mx' - | 'my' - | 'mz' - | 'na' - | 'nc' - | 'ne' - | 'ng' - | 'ni' - | 'nl' - | 'no' - | 'np' - | 'nz' - | 'om' - | 'pa' - | 'pe' - | 'pf' - | 'pg' - | 'ph' - | 'pk' - | 'pl' - | 'pr' - | 'ps' - | 'pt' - | 'py' - | 'qa' - | 're' - | 'ro' - | 'rs' - | 'ru' - | 'rw' - | 'sa' - | 'sc' - | 'sd' - | 'se' - | 'sg' - | 'si' - | 'sk' - | 'sl' - | 'sm' - | 'sn' - | 'so' - | 'sr' - | 'ss' - | 'st' - | 'sv' - | 'sx' - | 'sy' - | 'sz' - | 'tc' - | 'td' - | 'tg' - | 'th' - | 'tj' - | 'tl' - | 'tm' - | 'tn' - | 'tr' - | 'tt' - | 'tw' - | 'tz' - | 'ua' - | 'ug' - | 'us' - | 'uy' - | 'uz' - | 'vc' - | 've' - | 'vg' - | 'vi' - | 'vn' - | 'ye' - | 'yt' - | 'za' - | 'zm' - | 'zw'; - - /** - * Remove elements matching these CSS selectors. Applied after `includeSelectors`, - * so an element matching both is removed. - */ - excludeSelectors?: Array | null; - - /** - * Also return each page's HTML in `html`. - */ - includeHTML?: boolean; - - /** - * Include image references in the Markdown. + * Requires `formats.highlights: true`; required when it is set. + */ + export interface HighlightsParams { + /** + * The question or topic to find passages for. */ - includeImages?: boolean; + query: string; /** - * Include links in the Markdown. + * Maximum combined length of returned passages. */ - includeLinks?: boolean; + maxCharacters?: number; + } + /** + * Image options. Requires formats.images: true. + */ + export interface ImageParams { /** - * Keep only elements matching these CSS selectors. Filtered pages ignore - * `maxAgeMs`. + * Set `visual` to drop visual duplicates, keeping the largest copy. */ - includeSelectors?: Array | null; + dedupe?: 'none' | 'visual'; /** - * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 - * year (31536000000 ms). `0` fetches fresh. + * Extra data per image: `dimensions`, `classification`, or a hosted `file` URL. */ - maxAgeMs?: number | null; + enrich?: Array<'dimensions' | 'classification' | 'file'>; + } + /** + * Requires `formats.json: true`; required when it is set. + */ + export interface JsonParams { /** - * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. + * JSON Schema (not an example object) for a top-level object, up to 50 KB. Use + * optional or nullable fields for missing facts. */ - pdf?: Options.Pdf; + schema: { [key: string]: unknown }; /** - * Wait for CSS animations to finish before extracting, on browser-rendered pages. + * Extra guidance, such as which facts to prefer or how to read a field. */ - settleAnimations?: boolean; + instructions?: string; + } + /** + * Markdown options. Requires `formats.markdown`. + */ + export interface MarkdownParams { /** - * Shorten inline base64 image data. + * Include images in the Markdown using image syntax with URLs and alt text. */ - shortenBase64Images?: boolean; + includeImages?: boolean; /** - * Return the main content without navigation or footers. + * Keep link URLs in the Markdown. Set false to return link text without URLs. */ - useMainContentOnly?: boolean; + includeLinks?: boolean; /** - * How long to wait after initial page load, in milliseconds. `0` waits 500 ms. + * How base64 images appear: `placeholder` (default) or `preserve`. Requires + * `includeImages`. */ - waitForMs?: number; + inlineImages?: 'placeholder' | 'preserve'; } - export namespace Options { + export interface CustomParser { /** - * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. + * Field names mapped to CSS selectors (`h1`, `a@href`) or rule objects. Max 100 + * fields, 5 levels. */ - export interface Pdf { - /** - * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must - * be >= start. - */ - end?: number; + rules: { [key: string]: string | CustomParser.UnionMember1 }; + + /** + * Extract fields using custom CSS rules. This is the default when type is omitted. + */ + type?: 'custom'; + } + export namespace CustomParser { + export interface UnionMember1 { /** - * Read scanned PDF pages with OCR; preserve pages that already have text. + * CSS selector to match within the current page or parent rule. */ - ocr?: boolean; + selector: string; /** - * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. + * Return text, HTML, an attribute such as `@href`, or nested field rules. Defaults + * to text. */ - shouldParse?: boolean; + output?: 'text' | 'html' | string | unknown; /** - * First 1-based PDF page to parse. + * Return the first match with `item` or all matches with `list`. */ - start?: number; + type?: 'item' | 'list'; } } - } - - /** - * Crawl pages and return HTML. - */ - export interface HTML { - /** - * Return page content as HTML. - */ - format: 'html'; - /** - * How to find pages to crawl. - */ - source: HTML.StartURL | HTML.Sitemap; + export interface PrebuiltParser { + /** + * google-maps parses Google Maps business data into data.results. Accepts Maps + * place, search, and internal data URLs. Uses a US exit and English labels + * regardless of hl or Accept-Language. google-play parses a Play Store app into + * data: details, developer contact, ratings, price, permissions, and data safety. + * google-play-reviews returns the 200 newest reviews of the app, with developer + * replies, in data.reviews. Both Play parsers accept app details URLs + * (play.google.com/store/apps/details?id=…); hl and gl set the language and + * storefront, defaulting to en and us. app-store parses an App Store app into + * data: details, developer, ratings, price, version, and screenshots. + * app-store-reviews returns up to the 500 newest reviews in data.reviews. Both App + * Store parsers accept app URLs (apps.apple.com/us/app/…/id…); the country in the + * path sets the storefront, defaulting to us. emails accepts any page and returns + * its email addresses as data.emails ([{ email }]), read from mailto links, + * Cloudflare-protected addresses, and visible text. phone-numbers accepts any page + * and returns its valid phone numbers in E.164 as data.phone_numbers ([{ phone + * }]), read from tel links and visible text; numbers without a country code are + * read for the country of the site TLD, defaulting to US. links accepts any page + * and returns its unique http(s) links as data.links ([{ url, text }]), with + * absolute URLs; text falls back to aria-label or image alt and is null when a + * link has none. The emails parser reads the rendered page and respects content + * filters; the other prebuilt parsers read their data independently of DOM + * filters. + */ + parser: + | 'google-maps' + | 'google-play' + | 'google-play-reviews' + | 'app-store' + | 'app-store-reviews' + | 'emails' + | 'phone-numbers' + | 'links'; - /** - * Options for HTML output. - */ - options?: HTML.Options; - } + /** + * Use a prebuilt parser instead of custom rules. + */ + type: 'prebuilt'; + } - export namespace HTML { /** - * Discover pages by following links from one URL. + * Product options. Requires formats.product: true. */ - export interface StartURL { + export interface ProductParams { /** - * Start from one page. + * Drop visually duplicate product images, keeping the largest copy. */ - type: 'start_url'; + dedupeImages?: boolean; + } + /** + * Screenshot options. Requires formats.screenshot: true. + */ + export interface ScreenshotParams { /** - * Page where crawling begins. A URL without a scheme is read as https://. + * What to capture: `viewport`, `fullPage`, one element, or a rectangle. Max 40 + * megapixels. */ - url: string; + area?: 'viewport' | 'fullPage' | ScreenshotParams.Element | ScreenshotParams.Rectangle; /** - * Limits and filters for page discovery. + * Image format for the screenshot. */ - controls?: StartURL.Controls; + format?: 'png' | 'jpeg' | 'webp'; } - export namespace StartURL { + export namespace ScreenshotParams { + export interface Element { + /** + * CSS selector matching exactly one visible element. + */ + selector: string; + } + /** - * Limits and filters for page discovery. + * Pixels from the document origin. */ - export interface Controls { + export interface Rectangle { /** - * Follow links to subdomains. + * Height of the capture in pixels. */ - followSubdomains?: boolean; + height: number; /** - * Maximum link depth. Source pages are depth 0. No limit when omitted. + * Width of the capture in pixels. */ - maxDepth?: number; + width: number; /** - * Maximum pages to fetch. Unused reserved credits are refunded. Maximum 25000. + * Left edge of the capture, in pixels from the document origin. */ - maxUrls?: number; + x: number; /** - * RE2 pattern for URLs to include. The `start_url` itself is always included. + * Top edge of the capture, in pixels from the document origin. */ - regex?: string; + y: number; } } /** - * Scrape the pages listed in a domain's sitemap. Links on those pages are not - * followed. + * Browser and content settings shared by all outputs. */ - export interface Sitemap { + export interface SharedParams { /** - * Domain whose sitemap lists the pages to scrape. A full URL is reduced to its - * domain. + * Browser steps run in order before capture. Requires a paid plan. Skips the + * cache. */ - domain: string; + actions?: Array< + SharedParams.Perform | SharedParams.Scroll | SharedParams.Wait | SharedParams.WaitFor + >; /** - * Scrape the URLs in the domain's sitemap. + * Proxy country as a two-letter code, such as `US`. Case-insensitive. */ - type: 'sitemap'; + country?: string; /** - * Limits and filters for the sitemap URLs. A sitemap batch scrapes exactly those - * URLs and never follows links off them, so there is no crawl depth here. + * Accept cookie banners before actions and capture. */ - controls?: Sitemap.Controls; - } + dismissCookies?: boolean; - export namespace Sitemap { /** - * Limits and filters for the sitemap URLs. A sitemap batch scrapes exactly those - * URLs and never follows links off them, so there is no crawl depth here. + * Close other popups before actions and capture. */ - export interface Controls { - /** - * Maximum pages to fetch. Unused reserved credits are refunded. Maximum 25000. - */ - maxUrls?: number; + dismissPopups?: boolean; - /** - * RE2 pattern; only sitemap URLs matching it are scraped. - */ - regex?: string; - } - } + /** + * Remove elements matching these CSS selectors. Overrides `includeSelectors`. + */ + excludeSelectors?: Array; - /** - * Options for HTML output. - */ - export interface Options { - /** - * Fetch from this country (ISO 3166-1 alpha-2). - */ - country?: - | 'ad' - | 'ae' - | 'af' - | 'ag' - | 'ai' - | 'al' - | 'am' - | 'ao' - | 'ar' - | 'at' - | 'au' - | 'aw' - | 'az' - | 'ba' - | 'bb' - | 'bd' - | 'be' - | 'bf' - | 'bg' - | 'bh' - | 'bi' - | 'bj' - | 'bm' - | 'bn' - | 'bo' - | 'bq' - | 'br' - | 'bs' - | 'bw' - | 'by' - | 'bz' - | 'ca' - | 'cd' - | 'cf' - | 'cg' - | 'ch' - | 'ci' - | 'cl' - | 'cm' - | 'cn' - | 'co' - | 'cr' - | 'cv' - | 'cw' - | 'cy' - | 'cz' - | 'de' - | 'dj' - | 'dk' - | 'dm' - | 'do' - | 'dz' - | 'ec' - | 'ee' - | 'eg' - | 'es' - | 'et' - | 'fi' - | 'fj' - | 'fr' - | 'ga' - | 'gb' - | 'gd' - | 'ge' - | 'gf' - | 'gg' - | 'gh' - | 'gm' - | 'gn' - | 'gp' - | 'gq' - | 'gr' - | 'gt' - | 'gu' - | 'gw' - | 'gy' - | 'hk' - | 'hn' - | 'hr' - | 'ht' - | 'hu' - | 'id' - | 'ie' - | 'il' - | 'im' - | 'in' - | 'iq' - | 'ir' - | 'is' - | 'it' - | 'je' - | 'jm' - | 'jo' - | 'jp' - | 'ke' - | 'kg' - | 'kh' - | 'kn' - | 'kr' - | 'kw' - | 'ky' - | 'kz' - | 'la' - | 'lb' - | 'lc' - | 'lk' - | 'lr' - | 'ls' - | 'lt' - | 'lu' - | 'lv' - | 'ly' - | 'ma' - | 'mc' - | 'md' - | 'me' - | 'mf' - | 'mg' - | 'mk' - | 'ml' - | 'mm' - | 'mn' - | 'mo' - | 'mq' - | 'mr' - | 'mt' - | 'mu' - | 'mv' - | 'mw' - | 'mx' - | 'my' - | 'mz' - | 'na' - | 'nc' - | 'ne' - | 'ng' - | 'ni' - | 'nl' - | 'no' - | 'np' - | 'nz' - | 'om' - | 'pa' - | 'pe' - | 'pf' - | 'pg' - | 'ph' - | 'pk' - | 'pl' - | 'pr' - | 'ps' - | 'pt' - | 'py' - | 'qa' - | 're' - | 'ro' - | 'rs' - | 'ru' - | 'rw' - | 'sa' - | 'sc' - | 'sd' - | 'se' - | 'sg' - | 'si' - | 'sk' - | 'sl' - | 'sm' - | 'sn' - | 'so' - | 'sr' - | 'ss' - | 'st' - | 'sv' - | 'sx' - | 'sy' - | 'sz' - | 'tc' - | 'td' - | 'tg' - | 'th' - | 'tj' - | 'tl' - | 'tm' - | 'tn' - | 'tr' - | 'tt' - | 'tw' - | 'tz' - | 'ua' - | 'ug' - | 'us' - | 'uy' - | 'uz' - | 'vc' - | 've' - | 'vg' - | 'vi' - | 'vn' - | 'ye' - | 'yt' - | 'za' - | 'zm' - | 'zw'; - - /** - * Remove elements matching these CSS selectors. Applied after `includeSelectors`, - * so an element matching both is removed. - */ - excludeSelectors?: Array | null; - - /** - * Keep only elements matching these CSS selectors. Filtered pages ignore - * `maxAgeMs`. - */ - includeSelectors?: Array | null; - - /** - * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 - * year (31536000000 ms). `0` fetches fresh. - */ - maxAgeMs?: number | null; - - /** - * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. - */ - pdf?: Options.Pdf; - - /** - * Wait for CSS animations to finish before extracting, on browser-rendered pages. + /** + * HTTP headers to send to the target site. Requests with headers skip the cache. + */ + headers?: { [key: string]: string }; + + /** + * Include iframe content in HTML and text outputs. Screenshots always show visible + * frames. + */ + includeFrames?: boolean; + + /** + * Keep only elements matching these CSS selectors. + */ + includeSelectors?: Array; + + /** + * Keep only the main content. Doesn't affect `screenshot`, `bytes`, or `product`. + */ + mainContentOnly?: boolean; + + /** + * Document parsing options. + */ + parsers?: SharedParams.Parsers; + + /** + * Create or reuse an authenticated browser profile. Requires a paid plan and an + * HTTPS target. Profiles persist session state, bypass shared caches, and cannot + * be combined with ZDR, custom headers, raw bytes, or prebuilt parsers. + */ + profile?: SharedParams.Existing | SharedParams.New; + + /** + * Wait for CSS animations to finish before capture. Defaults to `true` when + * `screenshot` is requested. */ settleAnimations?: boolean; /** - * Return the main content without navigation or footers. + * Emulate a light or dark color scheme. + */ + theme?: 'light' | 'dark'; + + /** + * Browser size in pixels. Omit for 1920 × 1080. When provided, missing dimensions + * default to 1440 × 900. */ - useMainContentOnly?: boolean; + viewport?: SharedParams.Viewport; /** - * How long to wait after initial page load, in milliseconds. `0` waits 500 ms. + * Milliseconds, or a CSS selector to wait for, after actions. Defaults to 500 + * (2000 with frames or XML). */ - waitForMs?: number; + waitFor?: number | string; } - export namespace Options { + export namespace SharedParams { + export interface Perform { + /** + * One browser instruction, such as clicking a button or entering text. + */ + action: string; + + /** + * Use `perform` for a plain-language browser instruction. + */ + type: 'perform'; + } + + export interface Scroll { + /** + * Use `scroll` to move through the page or a container. + */ + type: 'scroll'; + + /** + * Distance per scroll: pixels, one `viewport`, or `max` to reach the end. + */ + amount?: number | 'viewport' | 'max'; + + /** + * Direction to scroll. + */ + direction?: 'down' | 'up' | 'left' | 'right'; + + /** + * Maximum number of scroll steps for this action. + */ + maxScrolls?: number; + + /** + * Scroll this container. Omit to scroll the page. + */ + selector?: string; + } + + export interface Wait { + /** + * Time to pause in milliseconds before the next action. + */ + milliseconds: number; + + /** + * Use `wait` to pause for a fixed duration. + */ + type: 'wait'; + } + + export interface WaitFor { + /** + * CSS selector to wait for before continuing. + */ + selector: string; + + /** + * Use `waitFor` to wait for a matching element. + */ + type: 'waitFor'; + } + /** - * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. + * Document parsing options. */ - export interface Pdf { + export interface Parsers { + /** + * PDF page range and OCR. + */ + pdf?: Parsers.Pdf; + } + + export namespace Parsers { + /** + * PDF page range and OCR. + */ + export interface Pdf { + /** + * Last page to parse. Must be at least `startPage`. + */ + endPage?: number; + + /** + * Set `auto` to read scanned pages with OCR. + */ + ocr?: 'off' | 'auto'; + + /** + * First page to parse, starting at 1. + */ + startPage?: number; + } + } + + export interface Existing { + /** + * The ID returned in profile.id by an earlier scrape. + */ + profileId: string; + + /** + * Reuse a saved browser profile. + */ + type: 'existing'; + } + + export interface New { + /** + * Username or email for the target website. + */ + identifier: string; + + /** + * Password used to sign in. It is never stored in the profile. + */ + password: string; + /** - * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must - * be >= start. + * Sign in and create a browser profile. */ - end?: number; + type: 'new'; /** - * Read scanned PDF pages with OCR; preserve pages that already have text. + * Optional label shown when listing profiles with `GET /org/browser/profiles`. */ - ocr?: boolean; + description?: string; + } + /** + * Browser size in pixels. Omit for 1920 × 1080. When provided, missing dimensions + * default to 1440 × 900. + */ + export interface Viewport { /** - * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. + * Browser viewport height in pixels. */ - shouldParse?: boolean; + height?: number; /** - * First 1-based PDF page to parse. + * Browser viewport width in pixels. */ - start?: number; + width?: number; } } + + /** + * Deadline for each page, using the same behavior and defaults as POST + * /web/scrape. + */ + export interface TimeoutOpts { + /** + * Deadline in milliseconds. + */ + milliseconds: number; + + /** + * "fail" returns 408 at the deadline. "return-partial" returns available results; + * inspect the response’s partial flag. "return-partial" requires at least 5000 ms. + */ + behavior?: 'fail' | 'return-partial'; + } } } diff --git a/tests/api-resources/batch.test.ts b/tests/api-resources/batch.test.ts index 393f6e97..b8036553 100644 --- a/tests/api-resources/batch.test.ts +++ b/tests/api-resources/batch.test.ts @@ -42,6 +42,7 @@ describe('resource batch', () => { limit: 1, q: 'batch_1a2b', search_type: 'exact', + shouldIncludeUnified: true, status: 'queued', tags: 'docs,competitor', }, @@ -103,7 +104,7 @@ describe('resource batch', () => { const responsePromise = client.batch.submit({ input: { data: { - format: 'markdown', + formats: {}, urls: [ { url: 'https://example.com/products/anvil' }, { url: 'https://example.com/products/hammer' }, @@ -126,7 +127,17 @@ describe('resource batch', () => { const response = await client.batch.submit({ input: { data: { - format: 'markdown', + formats: { + bytes: true, + highlights: true, + html: true, + images: true, + json: true, + markdown: true, + parse: true, + product: true, + screenshot: true, + }, urls: [ { url: 'https://example.com/products/anvil', @@ -139,25 +150,62 @@ describe('resource batch', () => { meta: { foo: 'bar' }, }, ], - options: { - country: 'de', - excludeSelectors: ['x'], - includeHTML: true, + highlightsParams: { query: 'x', maxCharacters: 100 }, + imageParams: { dedupe: 'none', enrich: ['dimensions'] }, + jsonParams: { + schema: { + type: 'bar', + properties: 'bar', + required: 'bar', + additionalProperties: 'bar', + }, + instructions: 'instructions', + }, + markdownParams: { includeImages: true, includeLinks: true, - includeSelectors: ['x'], - maxAgeMs: 0, - pdf: { - end: 1, - ocr: true, - shouldParse: true, - start: 1, + inlineImages: 'placeholder', + }, + maxAgeMs: 0, + parseParams: { + rules: { + title: 'h1', + links: { + selector: 'a', + output: '@href', + type: 'list', + }, + }, + type: 'custom', + }, + productParams: { dedupeImages: true }, + screenshotParams: { area: 'viewport', format: 'png' }, + sharedParams: { + actions: [{ action: 'Click the product details tab', type: 'perform' }], + country: 'US', + dismissCookies: true, + dismissPopups: true, + excludeSelectors: ['P'], + headers: { 'Accept-Language': 'en-US' }, + includeFrames: true, + includeSelectors: ['P'], + mainContentOnly: true, + parsers: { + pdf: { + endPage: 1, + ocr: 'off', + startPage: 1, + }, }, + profile: { profileId: 'prof_210b9798eb53baa4e69d31c1071cf03d', type: 'existing' }, settleAnimations: true, - shortenBase64Images: true, - useMainContentOnly: true, - waitForMs: 0, + theme: 'light', + viewport: { height: 240, width: 240 }, + waitFor: 500, }, + tags: ['production', 'team-alpha'], + timeoutOpts: { milliseconds: 1, behavior: 'fail' }, + zdr: 'disabled', }, mode: 'scrape', }, From 6cd4e91aa35e71e5be9f4e080edfdf30dbefcc3b Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Fri, 16 Oct 2026 07:08:57 +0200 Subject: [PATCH 156/232] release: 3.7.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 15 +++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 18 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index dc703804..2a266f81 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.6.0" + ".": "3.7.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 0733bb3c..65d88fb1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,20 @@ # Changelog +## [3.7.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.6.0...v3.7.0) (2026-10-16) + + +### Features + +* **batch:** support Scrape Anything batches up to 100k URLs ([#1883](https://github.com/context-dot-dev/context-typescript-sdk/issues/1883)) ([c447e68](https://github.com/context-dot-dev/context-typescript-sdk/commit/c447e68b5d39b322d2c159a46938cce67e4c8a16)) +* **scrape:** add App Store app and reviews prebuilt parsers ([#1859](https://github.com/context-dot-dev/context-typescript-sdk/issues/1859)) ([9ea0075](https://github.com/context-dot-dev/context-typescript-sdk/commit/9ea0075732b70dcc403ae6479cd453835471d369)) +* **scrape:** add emails prebuilt parser ([#1862](https://github.com/context-dot-dev/context-typescript-sdk/issues/1862)) ([9ea0075](https://github.com/context-dot-dev/context-typescript-sdk/commit/9ea0075732b70dcc403ae6479cd453835471d369)) +* **scrape:** add Google Play app and reviews prebuilt parsers ([#1857](https://github.com/context-dot-dev/context-typescript-sdk/issues/1857)) ([9ea0075](https://github.com/context-dot-dev/context-typescript-sdk/commit/9ea0075732b70dcc403ae6479cd453835471d369)) +* **scrape:** add links prebuilt parser ([#1865](https://github.com/context-dot-dev/context-typescript-sdk/issues/1865)) ([9ea0075](https://github.com/context-dot-dev/context-typescript-sdk/commit/9ea0075732b70dcc403ae6479cd453835471d369)) +* **scrape:** add phone-numbers prebuilt parser ([#1863](https://github.com/context-dot-dev/context-typescript-sdk/issues/1863)) ([9ea0075](https://github.com/context-dot-dev/context-typescript-sdk/commit/9ea0075732b70dcc403ae6479cd453835471d369)) +* **scrape:** list browser profiles and label them with descriptions ([#1914](https://github.com/context-dot-dev/context-typescript-sdk/issues/1914)) ([9cc6cfc](https://github.com/context-dot-dev/context-typescript-sdk/commit/9cc6cfceebd5ec12c4ee6dccceb2628a8574625a)) +* **search:** allow requesting a single result ([#1880](https://github.com/context-dot-dev/context-typescript-sdk/issues/1880)) ([06afee3](https://github.com/context-dot-dev/context-typescript-sdk/commit/06afee30979ed4ce08b6e2eb9062a06d916296c9)) +* **search:** order company search results by headcount, traffic, funding or founding year ([#1916](https://github.com/context-dot-dev/context-typescript-sdk/issues/1916)) ([9cc6cfc](https://github.com/context-dot-dev/context-typescript-sdk/commit/9cc6cfceebd5ec12c4ee6dccceb2628a8574625a)) + ## [3.6.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.5.0...v3.6.0) (2026-10-14) diff --git a/package.json b/package.json index 392bed8a..0dc178de 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.6.0", + "version": "3.7.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 73e38377..dd90c738 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.6.0'; // x-release-please-version +export const VERSION = '3.7.0'; // x-release-please-version From e07f6c3c09327a969ca5641cb1eca1cc8cfbaa64 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 16 Oct 2026 16:02:25 +0000 Subject: [PATCH 157/232] feat(search): add languages filter to web search (#1833) Stainless-Generated-From: fd53e25d6ed0c9bd7dc6623958c0f1a4ebe9fc90 --- src/resources/news.ts | 75 ++++++++++++++++++++++++++++- src/resources/web.ts | 83 ++++++++++++++++++++++++++++++++ tests/api-resources/news.test.ts | 2 +- tests/api-resources/web.test.ts | 1 + 4 files changed, 159 insertions(+), 2 deletions(-) diff --git a/src/resources/news.ts b/src/resources/news.ts index c13c271d..c3d6fa44 100644 --- a/src/resources/news.ts +++ b/src/resources/news.ts @@ -397,7 +397,80 @@ export namespace NewsSearchParams { * Article languages to include. Up to 3. */ articleLanguage?: Array< - 'ar' | 'de' | 'en' | 'es' | 'fr' | 'hi' | 'it' | 'ja' | 'ko' | 'nl' | 'pt' | 'ru' | 'zh' + | 'am' + | 'ar' + | 'az' + | 'be' + | 'bg' + | 'bn' + | 'ca' + | 'ceb' + | 'cs' + | 'cy' + | 'da' + | 'de' + | 'el' + | 'en' + | 'es' + | 'et' + | 'eu' + | 'fa' + | 'fi' + | 'fr' + | 'gu' + | 'ha' + | 'haw' + | 'he' + | 'hi' + | 'hr' + | 'hu' + | 'hy' + | 'id' + | 'is' + | 'it' + | 'ja' + | 'ka' + | 'kk' + | 'kn' + | 'ko' + | 'ku' + | 'ky' + | 'lo' + | 'lt' + | 'lv' + | 'mk' + | 'ml' + | 'mn' + | 'mr' + | 'ms' + | 'ne' + | 'nl' + | 'no' + | 'or' + | 'pa' + | 'pl' + | 'ps' + | 'pt' + | 'ro' + | 'ru' + | 'sk' + | 'sl' + | 'so' + | 'sq' + | 'sr' + | 'sv' + | 'sw' + | 'ta' + | 'te' + | 'th' + | 'tl' + | 'tr' + | 'uk' + | 'ur' + | 'uz' + | 'vi' + | 'yo' + | 'zh' >; /** diff --git a/src/resources/web.ts b/src/resources/web.ts index cbdb20ea..5d0516f1 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -3549,6 +3549,89 @@ export interface WebSearchParams { */ includeDomains?: Array; + /** + * Languages to return results in, as BCP 47 language codes such as `en` or `de`, + * or "all" for any language. Defaults to "all". Example: ["en", "de"]. + */ + languages?: + | 'all' + | Array< + | 'am' + | 'ar' + | 'az' + | 'be' + | 'bg' + | 'bn' + | 'ca' + | 'ceb' + | 'cs' + | 'cy' + | 'da' + | 'de' + | 'el' + | 'en' + | 'es' + | 'et' + | 'eu' + | 'fa' + | 'fi' + | 'fr' + | 'gu' + | 'ha' + | 'haw' + | 'he' + | 'hi' + | 'hr' + | 'hu' + | 'hy' + | 'id' + | 'is' + | 'it' + | 'ja' + | 'ka' + | 'kk' + | 'kn' + | 'ko' + | 'ku' + | 'ky' + | 'lo' + | 'lt' + | 'lv' + | 'mk' + | 'ml' + | 'mn' + | 'mr' + | 'ms' + | 'ne' + | 'nl' + | 'no' + | 'or' + | 'pa' + | 'pl' + | 'ps' + | 'pt' + | 'ro' + | 'ru' + | 'sk' + | 'sl' + | 'so' + | 'sq' + | 'sr' + | 'sv' + | 'sw' + | 'ta' + | 'te' + | 'th' + | 'tl' + | 'tr' + | 'uk' + | 'ur' + | 'uz' + | 'vi' + | 'yo' + | 'zh' + >; + /** * Inline Markdown scraping for each result. Set `enabled: true` to activate. */ diff --git a/tests/api-resources/news.test.ts b/tests/api-resources/news.test.ts index 7f486ac7..c6c423f5 100644 --- a/tests/api-resources/news.test.ts +++ b/tests/api-resources/news.test.ts @@ -34,7 +34,7 @@ describe('resource news', () => { }, cursor: 'cursor', filterBy: { - articleLanguage: ['ar'], + articleLanguage: ['am'], articleType: ['editorial'], date: { from: 0, to: 0 }, sourceCountry: ['ae'], diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 899c1b15..22cfaae3 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -267,6 +267,7 @@ describe('resource web', () => { freshness: 'last_24_hours', highlightsOptions: { enabled: true, maxCharacters: 100 }, includeDomains: ['xxx'], + languages: 'all', markdownOptions: { enabled: true, includeFrames: true, From 30315d037ab9024b2efea6e9b8d3337da8afcb03 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 17 Oct 2026 04:13:04 +0000 Subject: [PATCH 158/232] feat(scrape): add google-maps-reviews prebuilt parser with oldest-first sort (#1928) Stainless-Generated-From: b4a751eedc0f9682f71ad271dd96c13acd641ccb --- src/resources/batch.ts | 106 ++++++++++++++++++++++++++++++----------- src/resources/web.ts | 53 +++++++++++++++------ 2 files changed, 117 insertions(+), 42 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index ec385dd6..c979b29a 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -1120,12 +1120,13 @@ export namespace BatchGetResultsResponse { /** * Custom rules return fields after content filters; unmatched fields are null ([] - * for lists). The google-maps parser returns business records in data.results, and - * the google-play parser returns one app record as data, google-play-reviews - * returns data.reviews, app-store and app-store-reviews do the same for the App - * Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, - * and data.links from the rendered page; the store and Maps parsers read their - * data directly, independently of DOM filters and other outputs. + * for lists). The google-maps parser returns business records in data.results, + * google-maps-reviews returns data.reviews, and the google-play parser returns one + * app record as data, google-play-reviews returns data.reviews, app-store and + * app-store-reviews do the same for the App Store, emails, phone-numbers, and + * links return data.emails, data.phone_numbers, and data.links from the rendered + * page; the store and Maps parsers read their data directly, independently of DOM + * filters and other outputs. */ parsed: Result.Parsed; @@ -1514,12 +1515,13 @@ export namespace BatchGetResultsResponse { /** * Custom rules return fields after content filters; unmatched fields are null ([] - * for lists). The google-maps parser returns business records in data.results, and - * the google-play parser returns one app record as data, google-play-reviews - * returns data.reviews, app-store and app-store-reviews do the same for the App - * Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, - * and data.links from the rendered page; the store and Maps parsers read their - * data directly, independently of DOM filters and other outputs. + * for lists). The google-maps parser returns business records in data.results, + * google-maps-reviews returns data.reviews, and the google-play parser returns one + * app record as data, google-play-reviews returns data.reviews, app-store and + * app-store-reviews do the same for the App Store, emails, phone-numbers, and + * links return data.emails, data.phone_numbers, and data.links from the rendered + * page; the store and Maps parsers read their data directly, independently of DOM + * filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1538,6 +1540,7 @@ export namespace BatchGetResultsResponse { type: | 'custom' | 'google-maps' + | 'google-maps-reviews' | 'google-play' | 'google-play-reviews' | 'app-store' @@ -1868,12 +1871,13 @@ export namespace BatchGetResultsResponse { /** * Custom rules return fields after content filters; unmatched fields are null ([] - * for lists). The google-maps parser returns business records in data.results, and - * the google-play parser returns one app record as data, google-play-reviews - * returns data.reviews, app-store and app-store-reviews do the same for the App - * Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, - * and data.links from the rendered page; the store and Maps parsers read their - * data directly, independently of DOM filters and other outputs. + * for lists). The google-maps parser returns business records in data.results, + * google-maps-reviews returns data.reviews, and the google-play parser returns one + * app record as data, google-play-reviews returns data.reviews, app-store and + * app-store-reviews do the same for the App Store, emails, phone-numbers, and + * links return data.emails, data.phone_numbers, and data.links from the rendered + * page; the store and Maps parsers read their data directly, independently of DOM + * filters and other outputs. */ parsed: Result.Parsed; @@ -2262,12 +2266,13 @@ export namespace BatchGetResultsResponse { /** * Custom rules return fields after content filters; unmatched fields are null ([] - * for lists). The google-maps parser returns business records in data.results, and - * the google-play parser returns one app record as data, google-play-reviews - * returns data.reviews, app-store and app-store-reviews do the same for the App - * Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, - * and data.links from the rendered page; the store and Maps parsers read their - * data directly, independently of DOM filters and other outputs. + * for lists). The google-maps parser returns business records in data.results, + * google-maps-reviews returns data.reviews, and the google-play parser returns one + * app record as data, google-play-reviews returns data.reviews, app-store and + * app-store-reviews do the same for the App Store, emails, phone-numbers, and + * links return data.emails, data.phone_numbers, and data.links from the rendered + * page; the store and Maps parsers read their data directly, independently of DOM + * filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -2286,6 +2291,7 @@ export namespace BatchGetResultsResponse { type: | 'custom' | 'google-maps' + | 'google-maps-reviews' | 'google-play' | 'google-play-reviews' | 'app-store' @@ -3065,8 +3071,16 @@ export namespace BatchSubmitParams { /** * google-maps parses Google Maps business data into data.results. Accepts Maps * place, search, and internal data URLs. Uses a US exit and English labels - * regardless of hl or Accept-Language. google-play parses a Play Store app into - * data: details, developer contact, ratings, price, permissions, and data safety. + * regardless of hl or Accept-Language. google-maps-reviews returns the reviews of + * a place in data.reviews, in the same shape as the Serper reviews API (rating, + * date, isoDate, snippet, translatedSnippet, likes, user, media, response, link, + * id), plus language, guided ratings in details, and user.isLocalGuide; data also + * carries the place featureId, cid, and sort. sort and limit pick the order and + * count, and oldest is exact. It accepts Maps place, search, and ?cid= URLs, plus + * search.google.com/local/reviews URLs, so the google_maps_url and + * google_reviews_url fields of google-maps results work as input. An unknown place + * returns no reviews. google-play parses a Play Store app into data: details, + * developer contact, ratings, price, permissions, and data safety. * google-play-reviews returns the 200 newest reviews of the app, with developer * replies, in data.reviews. Both Play parsers accept app details URLs * (play.google.com/store/apps/details?id=…); hl and gl set the language and @@ -3088,6 +3102,7 @@ export namespace BatchSubmitParams { */ parser: | 'google-maps' + | 'google-maps-reviews' | 'google-play' | 'google-play-reviews' | 'app-store' @@ -3100,6 +3115,19 @@ export namespace BatchSubmitParams { * Use a prebuilt parser instead of custom rules. */ type: 'prebuilt'; + + /** + * google-maps-reviews only. Maximum number of reviews to return. Defaults to 100; + * maximum 1000. + */ + limit?: number; + + /** + * google-maps-reviews only. Order of data.reviews. newest, relevant, highest, and + * lowest follow Google; oldest returns the earliest reviews first, which Google + * itself does not offer. + */ + sort?: 'newest' | 'oldest' | 'relevant' | 'highest' | 'lowest'; } /** @@ -3756,8 +3784,16 @@ export namespace BatchSubmitParams { /** * google-maps parses Google Maps business data into data.results. Accepts Maps * place, search, and internal data URLs. Uses a US exit and English labels - * regardless of hl or Accept-Language. google-play parses a Play Store app into - * data: details, developer contact, ratings, price, permissions, and data safety. + * regardless of hl or Accept-Language. google-maps-reviews returns the reviews of + * a place in data.reviews, in the same shape as the Serper reviews API (rating, + * date, isoDate, snippet, translatedSnippet, likes, user, media, response, link, + * id), plus language, guided ratings in details, and user.isLocalGuide; data also + * carries the place featureId, cid, and sort. sort and limit pick the order and + * count, and oldest is exact. It accepts Maps place, search, and ?cid= URLs, plus + * search.google.com/local/reviews URLs, so the google_maps_url and + * google_reviews_url fields of google-maps results work as input. An unknown place + * returns no reviews. google-play parses a Play Store app into data: details, + * developer contact, ratings, price, permissions, and data safety. * google-play-reviews returns the 200 newest reviews of the app, with developer * replies, in data.reviews. Both Play parsers accept app details URLs * (play.google.com/store/apps/details?id=…); hl and gl set the language and @@ -3779,6 +3815,7 @@ export namespace BatchSubmitParams { */ parser: | 'google-maps' + | 'google-maps-reviews' | 'google-play' | 'google-play-reviews' | 'app-store' @@ -3791,6 +3828,19 @@ export namespace BatchSubmitParams { * Use a prebuilt parser instead of custom rules. */ type: 'prebuilt'; + + /** + * google-maps-reviews only. Maximum number of reviews to return. Defaults to 100; + * maximum 1000. + */ + limit?: number; + + /** + * google-maps-reviews only. Order of data.reviews. newest, relevant, highest, and + * lowest follow Google; oldest returns the earliest reviews first, which Google + * itself does not offer. + */ + sort?: 'newest' | 'oldest' | 'relevant' | 'highest' | 'lowest'; } /** diff --git a/src/resources/web.ts b/src/resources/web.ts index 5d0516f1..9e9c70ed 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -951,12 +951,13 @@ export interface WebScrapeResponse { /** * Custom rules return fields after content filters; unmatched fields are null ([] - * for lists). The google-maps parser returns business records in data.results, and - * the google-play parser returns one app record as data, google-play-reviews - * returns data.reviews, app-store and app-store-reviews do the same for the App - * Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, - * and data.links from the rendered page; the store and Maps parsers read their - * data directly, independently of DOM filters and other outputs. + * for lists). The google-maps parser returns business records in data.results, + * google-maps-reviews returns data.reviews, and the google-play parser returns one + * app record as data, google-play-reviews returns data.reviews, app-store and + * app-store-reviews do the same for the App Store, emails, phone-numbers, and + * links return data.emails, data.phone_numbers, and data.links from the rendered + * page; the store and Maps parsers read their data directly, independently of DOM + * filters and other outputs. */ parsed: WebScrapeResponse.Parsed; @@ -1345,12 +1346,13 @@ export namespace WebScrapeResponse { /** * Custom rules return fields after content filters; unmatched fields are null ([] - * for lists). The google-maps parser returns business records in data.results, and - * the google-play parser returns one app record as data, google-play-reviews - * returns data.reviews, app-store and app-store-reviews do the same for the App - * Store, emails, phone-numbers, and links return data.emails, data.phone_numbers, - * and data.links from the rendered page; the store and Maps parsers read their - * data directly, independently of DOM filters and other outputs. + * for lists). The google-maps parser returns business records in data.results, + * google-maps-reviews returns data.reviews, and the google-play parser returns one + * app record as data, google-play-reviews returns data.reviews, app-store and + * app-store-reviews do the same for the App Store, emails, phone-numbers, and + * links return data.emails, data.phone_numbers, and data.links from the rendered + * page; the store and Maps parsers read their data directly, independently of DOM + * filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1369,6 +1371,7 @@ export namespace WebScrapeResponse { type: | 'custom' | 'google-maps' + | 'google-maps-reviews' | 'google-play' | 'google-play-reviews' | 'app-store' @@ -2566,8 +2569,16 @@ export namespace WebScrapeParams { /** * google-maps parses Google Maps business data into data.results. Accepts Maps * place, search, and internal data URLs. Uses a US exit and English labels - * regardless of hl or Accept-Language. google-play parses a Play Store app into - * data: details, developer contact, ratings, price, permissions, and data safety. + * regardless of hl or Accept-Language. google-maps-reviews returns the reviews of + * a place in data.reviews, in the same shape as the Serper reviews API (rating, + * date, isoDate, snippet, translatedSnippet, likes, user, media, response, link, + * id), plus language, guided ratings in details, and user.isLocalGuide; data also + * carries the place featureId, cid, and sort. sort and limit pick the order and + * count, and oldest is exact. It accepts Maps place, search, and ?cid= URLs, plus + * search.google.com/local/reviews URLs, so the google_maps_url and + * google_reviews_url fields of google-maps results work as input. An unknown place + * returns no reviews. google-play parses a Play Store app into data: details, + * developer contact, ratings, price, permissions, and data safety. * google-play-reviews returns the 200 newest reviews of the app, with developer * replies, in data.reviews. Both Play parsers accept app details URLs * (play.google.com/store/apps/details?id=…); hl and gl set the language and @@ -2589,6 +2600,7 @@ export namespace WebScrapeParams { */ parser: | 'google-maps' + | 'google-maps-reviews' | 'google-play' | 'google-play-reviews' | 'app-store' @@ -2601,6 +2613,19 @@ export namespace WebScrapeParams { * Use a prebuilt parser instead of custom rules. */ type: 'prebuilt'; + + /** + * google-maps-reviews only. Maximum number of reviews to return. Defaults to 100; + * maximum 1000. + */ + limit?: number; + + /** + * google-maps-reviews only. Order of data.reviews. newest, relevant, highest, and + * lowest follow Google; oldest returns the earliest reviews first, which Google + * itself does not offer. + */ + sort?: 'newest' | 'oldest' | 'relevant' | 'highest' | 'lowest'; } /** From 8d2fa9efc4d8925f09c51194f305e32818f0ca3e Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 17 Oct 2026 04:36:55 +0000 Subject: [PATCH 159/232] feat(scrape): add g2-reviews prebuilt parser (#1933) Stainless-Generated-From: 1af0d2bf2882cc12871ad56f5e43cda722254dac --- src/resources/batch.ts | 94 +++++++++++++++++++++++++----------------- src/resources/web.ts | 47 ++++++++++++--------- 2 files changed, 84 insertions(+), 57 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index c979b29a..6cb5b388 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -1123,10 +1123,11 @@ export namespace BatchGetResultsResponse { * for lists). The google-maps parser returns business records in data.results, * google-maps-reviews returns data.reviews, and the google-play parser returns one * app record as data, google-play-reviews returns data.reviews, app-store and - * app-store-reviews do the same for the App Store, emails, phone-numbers, and - * links return data.emails, data.phone_numbers, and data.links from the rendered - * page; the store and Maps parsers read their data directly, independently of DOM - * filters and other outputs. + * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews + * for a G2 product, emails, phone-numbers, and links return data.emails, + * data.phone_numbers, and data.links from the rendered page; the store, Maps, and + * G2 parsers read their data directly, independently of DOM filters and other + * outputs. */ parsed: Result.Parsed; @@ -1518,10 +1519,11 @@ export namespace BatchGetResultsResponse { * for lists). The google-maps parser returns business records in data.results, * google-maps-reviews returns data.reviews, and the google-play parser returns one * app record as data, google-play-reviews returns data.reviews, app-store and - * app-store-reviews do the same for the App Store, emails, phone-numbers, and - * links return data.emails, data.phone_numbers, and data.links from the rendered - * page; the store and Maps parsers read their data directly, independently of DOM - * filters and other outputs. + * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews + * for a G2 product, emails, phone-numbers, and links return data.emails, + * data.phone_numbers, and data.links from the rendered page; the store, Maps, and + * G2 parsers read their data directly, independently of DOM filters and other + * outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1545,6 +1547,7 @@ export namespace BatchGetResultsResponse { | 'google-play-reviews' | 'app-store' | 'app-store-reviews' + | 'g2-reviews' | 'emails' | 'phone-numbers' | 'links'; @@ -1874,10 +1877,11 @@ export namespace BatchGetResultsResponse { * for lists). The google-maps parser returns business records in data.results, * google-maps-reviews returns data.reviews, and the google-play parser returns one * app record as data, google-play-reviews returns data.reviews, app-store and - * app-store-reviews do the same for the App Store, emails, phone-numbers, and - * links return data.emails, data.phone_numbers, and data.links from the rendered - * page; the store and Maps parsers read their data directly, independently of DOM - * filters and other outputs. + * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews + * for a G2 product, emails, phone-numbers, and links return data.emails, + * data.phone_numbers, and data.links from the rendered page; the store, Maps, and + * G2 parsers read their data directly, independently of DOM filters and other + * outputs. */ parsed: Result.Parsed; @@ -2269,10 +2273,11 @@ export namespace BatchGetResultsResponse { * for lists). The google-maps parser returns business records in data.results, * google-maps-reviews returns data.reviews, and the google-play parser returns one * app record as data, google-play-reviews returns data.reviews, app-store and - * app-store-reviews do the same for the App Store, emails, phone-numbers, and - * links return data.emails, data.phone_numbers, and data.links from the rendered - * page; the store and Maps parsers read their data directly, independently of DOM - * filters and other outputs. + * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews + * for a G2 product, emails, phone-numbers, and links return data.emails, + * data.phone_numbers, and data.links from the rendered page; the store, Maps, and + * G2 parsers read their data directly, independently of DOM filters and other + * outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -2296,6 +2301,7 @@ export namespace BatchGetResultsResponse { | 'google-play-reviews' | 'app-store' | 'app-store-reviews' + | 'g2-reviews' | 'emails' | 'phone-numbers' | 'links'; @@ -3088,17 +3094,22 @@ export namespace BatchSubmitParams { * data: details, developer, ratings, price, version, and screenshots. * app-store-reviews returns up to the 500 newest reviews in data.reviews. Both App * Store parsers accept app URLs (apps.apple.com/us/app/…/id…); the country in the - * path sets the storefront, defaulting to us. emails accepts any page and returns - * its email addresses as data.emails ([{ email }]), read from mailto links, - * Cloudflare-protected addresses, and visible text. phone-numbers accepts any page - * and returns its valid phone numbers in E.164 as data.phone_numbers ([{ phone - * }]), read from tel links and visible text; numbers without a country code are - * read for the country of the site TLD, defaulting to US. links accepts any page - * and returns its unique http(s) links as data.links ([{ url, text }]), with - * absolute URLs; text falls back to aria-label or image alt and is null when a - * link has none. The emails parser reads the rendered page and respects content - * filters; the other prebuilt parsers read their data independently of DOM - * filters. + * path sets the storefront, defaulting to us. g2-reviews returns the 25 most + * recently published reviews of a G2 product in data.reviews (rating, title, + * likes, dislikes, problems_solved, reviewer role, company size, and industry), + * plus data.product. It accepts G2 product URLs (g2.com/products/…), follows + * renamed products, and keeps star-rating filters from the URL + * (filters[nps_score][]=1 to 5); other filters, sort orders, and pages are + * ignored. emails accepts any page and returns its email addresses as data.emails + * ([{ email }]), read from mailto links, Cloudflare-protected addresses, and + * visible text. phone-numbers accepts any page and returns its valid phone numbers + * in E.164 as data.phone_numbers ([{ phone }]), read from tel links and visible + * text; numbers without a country code are read for the country of the site TLD, + * defaulting to US. links accepts any page and returns its unique http(s) links as + * data.links ([{ url, text }]), with absolute URLs; text falls back to aria-label + * or image alt and is null when a link has none. The emails parser reads the + * rendered page and respects content filters; the other prebuilt parsers read + * their data independently of DOM filters. */ parser: | 'google-maps' @@ -3107,6 +3118,7 @@ export namespace BatchSubmitParams { | 'google-play-reviews' | 'app-store' | 'app-store-reviews' + | 'g2-reviews' | 'emails' | 'phone-numbers' | 'links'; @@ -3801,17 +3813,22 @@ export namespace BatchSubmitParams { * data: details, developer, ratings, price, version, and screenshots. * app-store-reviews returns up to the 500 newest reviews in data.reviews. Both App * Store parsers accept app URLs (apps.apple.com/us/app/…/id…); the country in the - * path sets the storefront, defaulting to us. emails accepts any page and returns - * its email addresses as data.emails ([{ email }]), read from mailto links, - * Cloudflare-protected addresses, and visible text. phone-numbers accepts any page - * and returns its valid phone numbers in E.164 as data.phone_numbers ([{ phone - * }]), read from tel links and visible text; numbers without a country code are - * read for the country of the site TLD, defaulting to US. links accepts any page - * and returns its unique http(s) links as data.links ([{ url, text }]), with - * absolute URLs; text falls back to aria-label or image alt and is null when a - * link has none. The emails parser reads the rendered page and respects content - * filters; the other prebuilt parsers read their data independently of DOM - * filters. + * path sets the storefront, defaulting to us. g2-reviews returns the 25 most + * recently published reviews of a G2 product in data.reviews (rating, title, + * likes, dislikes, problems_solved, reviewer role, company size, and industry), + * plus data.product. It accepts G2 product URLs (g2.com/products/…), follows + * renamed products, and keeps star-rating filters from the URL + * (filters[nps_score][]=1 to 5); other filters, sort orders, and pages are + * ignored. emails accepts any page and returns its email addresses as data.emails + * ([{ email }]), read from mailto links, Cloudflare-protected addresses, and + * visible text. phone-numbers accepts any page and returns its valid phone numbers + * in E.164 as data.phone_numbers ([{ phone }]), read from tel links and visible + * text; numbers without a country code are read for the country of the site TLD, + * defaulting to US. links accepts any page and returns its unique http(s) links as + * data.links ([{ url, text }]), with absolute URLs; text falls back to aria-label + * or image alt and is null when a link has none. The emails parser reads the + * rendered page and respects content filters; the other prebuilt parsers read + * their data independently of DOM filters. */ parser: | 'google-maps' @@ -3820,6 +3837,7 @@ export namespace BatchSubmitParams { | 'google-play-reviews' | 'app-store' | 'app-store-reviews' + | 'g2-reviews' | 'emails' | 'phone-numbers' | 'links'; diff --git a/src/resources/web.ts b/src/resources/web.ts index 9e9c70ed..9ae75325 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -954,10 +954,11 @@ export interface WebScrapeResponse { * for lists). The google-maps parser returns business records in data.results, * google-maps-reviews returns data.reviews, and the google-play parser returns one * app record as data, google-play-reviews returns data.reviews, app-store and - * app-store-reviews do the same for the App Store, emails, phone-numbers, and - * links return data.emails, data.phone_numbers, and data.links from the rendered - * page; the store and Maps parsers read their data directly, independently of DOM - * filters and other outputs. + * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews + * for a G2 product, emails, phone-numbers, and links return data.emails, + * data.phone_numbers, and data.links from the rendered page; the store, Maps, and + * G2 parsers read their data directly, independently of DOM filters and other + * outputs. */ parsed: WebScrapeResponse.Parsed; @@ -1349,10 +1350,11 @@ export namespace WebScrapeResponse { * for lists). The google-maps parser returns business records in data.results, * google-maps-reviews returns data.reviews, and the google-play parser returns one * app record as data, google-play-reviews returns data.reviews, app-store and - * app-store-reviews do the same for the App Store, emails, phone-numbers, and - * links return data.emails, data.phone_numbers, and data.links from the rendered - * page; the store and Maps parsers read their data directly, independently of DOM - * filters and other outputs. + * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews + * for a G2 product, emails, phone-numbers, and links return data.emails, + * data.phone_numbers, and data.links from the rendered page; the store, Maps, and + * G2 parsers read their data directly, independently of DOM filters and other + * outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1376,6 +1378,7 @@ export namespace WebScrapeResponse { | 'google-play-reviews' | 'app-store' | 'app-store-reviews' + | 'g2-reviews' | 'emails' | 'phone-numbers' | 'links'; @@ -2586,17 +2589,22 @@ export namespace WebScrapeParams { * data: details, developer, ratings, price, version, and screenshots. * app-store-reviews returns up to the 500 newest reviews in data.reviews. Both App * Store parsers accept app URLs (apps.apple.com/us/app/…/id…); the country in the - * path sets the storefront, defaulting to us. emails accepts any page and returns - * its email addresses as data.emails ([{ email }]), read from mailto links, - * Cloudflare-protected addresses, and visible text. phone-numbers accepts any page - * and returns its valid phone numbers in E.164 as data.phone_numbers ([{ phone - * }]), read from tel links and visible text; numbers without a country code are - * read for the country of the site TLD, defaulting to US. links accepts any page - * and returns its unique http(s) links as data.links ([{ url, text }]), with - * absolute URLs; text falls back to aria-label or image alt and is null when a - * link has none. The emails parser reads the rendered page and respects content - * filters; the other prebuilt parsers read their data independently of DOM - * filters. + * path sets the storefront, defaulting to us. g2-reviews returns the 25 most + * recently published reviews of a G2 product in data.reviews (rating, title, + * likes, dislikes, problems_solved, reviewer role, company size, and industry), + * plus data.product. It accepts G2 product URLs (g2.com/products/…), follows + * renamed products, and keeps star-rating filters from the URL + * (filters[nps_score][]=1 to 5); other filters, sort orders, and pages are + * ignored. emails accepts any page and returns its email addresses as data.emails + * ([{ email }]), read from mailto links, Cloudflare-protected addresses, and + * visible text. phone-numbers accepts any page and returns its valid phone numbers + * in E.164 as data.phone_numbers ([{ phone }]), read from tel links and visible + * text; numbers without a country code are read for the country of the site TLD, + * defaulting to US. links accepts any page and returns its unique http(s) links as + * data.links ([{ url, text }]), with absolute URLs; text falls back to aria-label + * or image alt and is null when a link has none. The emails parser reads the + * rendered page and respects content filters; the other prebuilt parsers read + * their data independently of DOM filters. */ parser: | 'google-maps' @@ -2605,6 +2613,7 @@ export namespace WebScrapeParams { | 'google-play-reviews' | 'app-store' | 'app-store-reviews' + | 'g2-reviews' | 'emails' | 'phone-numbers' | 'links'; From ae45c503c70bc4903562e7324acc4c76554e7a7f Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 17 Oct 2026 04:54:36 +0000 Subject: [PATCH 160/232] feat(scrape): add Instagram profile, post, and feed prebuilt parsers (#1905) Stainless-Generated-From: c4cb8e8d2c5235b4b8aac1e2eb32b71a192948dd --- src/resources/batch.ts | 110 +++++++++++++++++++++++++++-------------- src/resources/web.ts | 55 ++++++++++++++------- 2 files changed, 111 insertions(+), 54 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 6cb5b388..745e1e67 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -1124,10 +1124,11 @@ export namespace BatchGetResultsResponse { * google-maps-reviews returns data.reviews, and the google-play parser returns one * app record as data, google-play-reviews returns data.reviews, app-store and * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews - * for a G2 product, emails, phone-numbers, and links return data.emails, - * data.phone_numbers, and data.links from the rendered page; the store, Maps, and - * G2 parsers read their data directly, independently of DOM filters and other - * outputs. + * for a G2 product, instagram-profile and instagram-post return one record as + * data, instagram-feed returns data.posts, emails, phone-numbers, and links return + * data.emails, data.phone_numbers, and data.links from the rendered page; the + * store, Maps, G2, and Instagram parsers read their data directly, independently + * of DOM filters and other outputs. */ parsed: Result.Parsed; @@ -1520,10 +1521,11 @@ export namespace BatchGetResultsResponse { * google-maps-reviews returns data.reviews, and the google-play parser returns one * app record as data, google-play-reviews returns data.reviews, app-store and * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews - * for a G2 product, emails, phone-numbers, and links return data.emails, - * data.phone_numbers, and data.links from the rendered page; the store, Maps, and - * G2 parsers read their data directly, independently of DOM filters and other - * outputs. + * for a G2 product, instagram-profile and instagram-post return one record as + * data, instagram-feed returns data.posts, emails, phone-numbers, and links return + * data.emails, data.phone_numbers, and data.links from the rendered page; the + * store, Maps, G2, and Instagram parsers read their data directly, independently + * of DOM filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1548,6 +1550,9 @@ export namespace BatchGetResultsResponse { | 'app-store' | 'app-store-reviews' | 'g2-reviews' + | 'instagram-profile' + | 'instagram-post' + | 'instagram-feed' | 'emails' | 'phone-numbers' | 'links'; @@ -1878,10 +1883,11 @@ export namespace BatchGetResultsResponse { * google-maps-reviews returns data.reviews, and the google-play parser returns one * app record as data, google-play-reviews returns data.reviews, app-store and * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews - * for a G2 product, emails, phone-numbers, and links return data.emails, - * data.phone_numbers, and data.links from the rendered page; the store, Maps, and - * G2 parsers read their data directly, independently of DOM filters and other - * outputs. + * for a G2 product, instagram-profile and instagram-post return one record as + * data, instagram-feed returns data.posts, emails, phone-numbers, and links return + * data.emails, data.phone_numbers, and data.links from the rendered page; the + * store, Maps, G2, and Instagram parsers read their data directly, independently + * of DOM filters and other outputs. */ parsed: Result.Parsed; @@ -2274,10 +2280,11 @@ export namespace BatchGetResultsResponse { * google-maps-reviews returns data.reviews, and the google-play parser returns one * app record as data, google-play-reviews returns data.reviews, app-store and * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews - * for a G2 product, emails, phone-numbers, and links return data.emails, - * data.phone_numbers, and data.links from the rendered page; the store, Maps, and - * G2 parsers read their data directly, independently of DOM filters and other - * outputs. + * for a G2 product, instagram-profile and instagram-post return one record as + * data, instagram-feed returns data.posts, emails, phone-numbers, and links return + * data.emails, data.phone_numbers, and data.links from the rendered page; the + * store, Maps, G2, and Instagram parsers read their data directly, independently + * of DOM filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -2302,6 +2309,9 @@ export namespace BatchGetResultsResponse { | 'app-store' | 'app-store-reviews' | 'g2-reviews' + | 'instagram-profile' + | 'instagram-post' + | 'instagram-feed' | 'emails' | 'phone-numbers' | 'links'; @@ -3100,16 +3110,27 @@ export namespace BatchSubmitParams { * plus data.product. It accepts G2 product URLs (g2.com/products/…), follows * renamed products, and keeps star-rating filters from the URL * (filters[nps_score][]=1 to 5); other filters, sort orders, and pages are - * ignored. emails accepts any page and returns its email addresses as data.emails - * ([{ email }]), read from mailto links, Cloudflare-protected addresses, and - * visible text. phone-numbers accepts any page and returns its valid phone numbers - * in E.164 as data.phone_numbers ([{ phone }]), read from tel links and visible - * text; numbers without a country code are read for the country of the site TLD, - * defaulting to US. links accepts any page and returns its unique http(s) links as - * data.links ([{ url, text }]), with absolute URLs; text falls back to aria-label - * or image alt and is null when a link has none. The emails parser reads the - * rendered page and respects content filters; the other prebuilt parsers read - * their data independently of DOM filters. + * ignored. instagram-profile parses a public profile (instagram.com/{username}) + * into data: bio, links, follower and post counts, category, business address, + * similar_accounts, and latest_posts (the 12 newest). instagram-post parses a post + * or reel (/p/…, /reel/…) into data: caption, hashtags, mentions, like, comment, + * and view counts, media URLs, tagged users, collaborators, location, and the top + * ~14 comments in data.comments. instagram-feed returns the top posts for a + * hashtag or keyword (/explore/tags/…, /popular/…) or the recent posts at a + * location (/explore/locations/{id}/…) in data.posts; keyword posts carry only the + * shortcode, owner, thumbnail, and views, plus the caption when Instagram shows + * it. All three Instagram parsers read public data without logging in, so private + * accounts return no posts and follower lists are unavailable. emails accepts any + * page and returns its email addresses as data.emails ([{ email }]), read from + * mailto links, Cloudflare-protected addresses, and visible text. phone-numbers + * accepts any page and returns its valid phone numbers in E.164 as + * data.phone_numbers ([{ phone }]), read from tel links and visible text; numbers + * without a country code are read for the country of the site TLD, defaulting to + * US. links accepts any page and returns its unique http(s) links as data.links + * ([{ url, text }]), with absolute URLs; text falls back to aria-label or image + * alt and is null when a link has none. The emails parser reads the rendered page + * and respects content filters; the other prebuilt parsers read their data + * independently of DOM filters. */ parser: | 'google-maps' @@ -3119,6 +3140,9 @@ export namespace BatchSubmitParams { | 'app-store' | 'app-store-reviews' | 'g2-reviews' + | 'instagram-profile' + | 'instagram-post' + | 'instagram-feed' | 'emails' | 'phone-numbers' | 'links'; @@ -3819,16 +3843,27 @@ export namespace BatchSubmitParams { * plus data.product. It accepts G2 product URLs (g2.com/products/…), follows * renamed products, and keeps star-rating filters from the URL * (filters[nps_score][]=1 to 5); other filters, sort orders, and pages are - * ignored. emails accepts any page and returns its email addresses as data.emails - * ([{ email }]), read from mailto links, Cloudflare-protected addresses, and - * visible text. phone-numbers accepts any page and returns its valid phone numbers - * in E.164 as data.phone_numbers ([{ phone }]), read from tel links and visible - * text; numbers without a country code are read for the country of the site TLD, - * defaulting to US. links accepts any page and returns its unique http(s) links as - * data.links ([{ url, text }]), with absolute URLs; text falls back to aria-label - * or image alt and is null when a link has none. The emails parser reads the - * rendered page and respects content filters; the other prebuilt parsers read - * their data independently of DOM filters. + * ignored. instagram-profile parses a public profile (instagram.com/{username}) + * into data: bio, links, follower and post counts, category, business address, + * similar_accounts, and latest_posts (the 12 newest). instagram-post parses a post + * or reel (/p/…, /reel/…) into data: caption, hashtags, mentions, like, comment, + * and view counts, media URLs, tagged users, collaborators, location, and the top + * ~14 comments in data.comments. instagram-feed returns the top posts for a + * hashtag or keyword (/explore/tags/…, /popular/…) or the recent posts at a + * location (/explore/locations/{id}/…) in data.posts; keyword posts carry only the + * shortcode, owner, thumbnail, and views, plus the caption when Instagram shows + * it. All three Instagram parsers read public data without logging in, so private + * accounts return no posts and follower lists are unavailable. emails accepts any + * page and returns its email addresses as data.emails ([{ email }]), read from + * mailto links, Cloudflare-protected addresses, and visible text. phone-numbers + * accepts any page and returns its valid phone numbers in E.164 as + * data.phone_numbers ([{ phone }]), read from tel links and visible text; numbers + * without a country code are read for the country of the site TLD, defaulting to + * US. links accepts any page and returns its unique http(s) links as data.links + * ([{ url, text }]), with absolute URLs; text falls back to aria-label or image + * alt and is null when a link has none. The emails parser reads the rendered page + * and respects content filters; the other prebuilt parsers read their data + * independently of DOM filters. */ parser: | 'google-maps' @@ -3838,6 +3873,9 @@ export namespace BatchSubmitParams { | 'app-store' | 'app-store-reviews' | 'g2-reviews' + | 'instagram-profile' + | 'instagram-post' + | 'instagram-feed' | 'emails' | 'phone-numbers' | 'links'; diff --git a/src/resources/web.ts b/src/resources/web.ts index 9ae75325..d4c63e70 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -955,10 +955,11 @@ export interface WebScrapeResponse { * google-maps-reviews returns data.reviews, and the google-play parser returns one * app record as data, google-play-reviews returns data.reviews, app-store and * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews - * for a G2 product, emails, phone-numbers, and links return data.emails, - * data.phone_numbers, and data.links from the rendered page; the store, Maps, and - * G2 parsers read their data directly, independently of DOM filters and other - * outputs. + * for a G2 product, instagram-profile and instagram-post return one record as + * data, instagram-feed returns data.posts, emails, phone-numbers, and links return + * data.emails, data.phone_numbers, and data.links from the rendered page; the + * store, Maps, G2, and Instagram parsers read their data directly, independently + * of DOM filters and other outputs. */ parsed: WebScrapeResponse.Parsed; @@ -1351,10 +1352,11 @@ export namespace WebScrapeResponse { * google-maps-reviews returns data.reviews, and the google-play parser returns one * app record as data, google-play-reviews returns data.reviews, app-store and * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews - * for a G2 product, emails, phone-numbers, and links return data.emails, - * data.phone_numbers, and data.links from the rendered page; the store, Maps, and - * G2 parsers read their data directly, independently of DOM filters and other - * outputs. + * for a G2 product, instagram-profile and instagram-post return one record as + * data, instagram-feed returns data.posts, emails, phone-numbers, and links return + * data.emails, data.phone_numbers, and data.links from the rendered page; the + * store, Maps, G2, and Instagram parsers read their data directly, independently + * of DOM filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1379,6 +1381,9 @@ export namespace WebScrapeResponse { | 'app-store' | 'app-store-reviews' | 'g2-reviews' + | 'instagram-profile' + | 'instagram-post' + | 'instagram-feed' | 'emails' | 'phone-numbers' | 'links'; @@ -2595,16 +2600,27 @@ export namespace WebScrapeParams { * plus data.product. It accepts G2 product URLs (g2.com/products/…), follows * renamed products, and keeps star-rating filters from the URL * (filters[nps_score][]=1 to 5); other filters, sort orders, and pages are - * ignored. emails accepts any page and returns its email addresses as data.emails - * ([{ email }]), read from mailto links, Cloudflare-protected addresses, and - * visible text. phone-numbers accepts any page and returns its valid phone numbers - * in E.164 as data.phone_numbers ([{ phone }]), read from tel links and visible - * text; numbers without a country code are read for the country of the site TLD, - * defaulting to US. links accepts any page and returns its unique http(s) links as - * data.links ([{ url, text }]), with absolute URLs; text falls back to aria-label - * or image alt and is null when a link has none. The emails parser reads the - * rendered page and respects content filters; the other prebuilt parsers read - * their data independently of DOM filters. + * ignored. instagram-profile parses a public profile (instagram.com/{username}) + * into data: bio, links, follower and post counts, category, business address, + * similar_accounts, and latest_posts (the 12 newest). instagram-post parses a post + * or reel (/p/…, /reel/…) into data: caption, hashtags, mentions, like, comment, + * and view counts, media URLs, tagged users, collaborators, location, and the top + * ~14 comments in data.comments. instagram-feed returns the top posts for a + * hashtag or keyword (/explore/tags/…, /popular/…) or the recent posts at a + * location (/explore/locations/{id}/…) in data.posts; keyword posts carry only the + * shortcode, owner, thumbnail, and views, plus the caption when Instagram shows + * it. All three Instagram parsers read public data without logging in, so private + * accounts return no posts and follower lists are unavailable. emails accepts any + * page and returns its email addresses as data.emails ([{ email }]), read from + * mailto links, Cloudflare-protected addresses, and visible text. phone-numbers + * accepts any page and returns its valid phone numbers in E.164 as + * data.phone_numbers ([{ phone }]), read from tel links and visible text; numbers + * without a country code are read for the country of the site TLD, defaulting to + * US. links accepts any page and returns its unique http(s) links as data.links + * ([{ url, text }]), with absolute URLs; text falls back to aria-label or image + * alt and is null when a link has none. The emails parser reads the rendered page + * and respects content filters; the other prebuilt parsers read their data + * independently of DOM filters. */ parser: | 'google-maps' @@ -2614,6 +2630,9 @@ export namespace WebScrapeParams { | 'app-store' | 'app-store-reviews' | 'g2-reviews' + | 'instagram-profile' + | 'instagram-post' + | 'instagram-feed' | 'emails' | 'phone-numbers' | 'links'; From 8782f4e71a5f391b1f414fcf587d41219b26a746 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 17 Oct 2026 05:28:56 +0000 Subject: [PATCH 161/232] feat(brand): add search metadata and country and language filters (#1945) Stainless-Generated-From: a9f6285aa5087eda610745d38aa7bc23e5c7b120 --- src/resources/brand.ts | 770 +++++++++++++++++++++++++++++- tests/api-resources/brand.test.ts | 2 + 2 files changed, 770 insertions(+), 2 deletions(-) diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 7a104fef..9cc71291 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -22,8 +22,10 @@ export class Brand extends APIResource { } /** - * Find up to 10 brands by name or domain, ordered by popularity. Use the returned - * domain to retrieve a full brand profile. + * Find up to 10 brands by name or domain, ordered by popularity. Optionally filter + * by country and primary language; both filters must match when provided together. + * Results include description, country, and language when available. Use the + * returned domain to retrieve a full brand profile. * * @example * ```ts @@ -917,6 +919,390 @@ export namespace BrandSearchResponse { * The brand's name. Empty string when unknown. */ name: string; + + /** + * The brand's country, when available, as an uppercase ISO 3166-1 alpha-2 code. + */ + country?: + | 'AD' + | 'AE' + | 'AF' + | 'AG' + | 'AI' + | 'AL' + | 'AM' + | 'AO' + | 'AQ' + | 'AR' + | 'AS' + | 'AT' + | 'AU' + | 'AW' + | 'AX' + | 'AZ' + | 'BA' + | 'BB' + | 'BD' + | 'BE' + | 'BF' + | 'BG' + | 'BH' + | 'BI' + | 'BJ' + | 'BL' + | 'BM' + | 'BN' + | 'BO' + | 'BQ' + | 'BR' + | 'BS' + | 'BT' + | 'BV' + | 'BW' + | 'BY' + | 'BZ' + | 'CA' + | 'CC' + | 'CD' + | 'CF' + | 'CG' + | 'CH' + | 'CI' + | 'CK' + | 'CL' + | 'CM' + | 'CN' + | 'CO' + | 'CR' + | 'CU' + | 'CV' + | 'CW' + | 'CX' + | 'CY' + | 'CZ' + | 'DE' + | 'DJ' + | 'DK' + | 'DM' + | 'DO' + | 'DZ' + | 'EC' + | 'EE' + | 'EG' + | 'EH' + | 'ER' + | 'ES' + | 'ET' + | 'FI' + | 'FJ' + | 'FK' + | 'FM' + | 'FO' + | 'FR' + | 'GA' + | 'GB' + | 'GD' + | 'GE' + | 'GF' + | 'GG' + | 'GH' + | 'GI' + | 'GL' + | 'GM' + | 'GN' + | 'GP' + | 'GQ' + | 'GR' + | 'GS' + | 'GT' + | 'GU' + | 'GW' + | 'GY' + | 'HK' + | 'HM' + | 'HN' + | 'HR' + | 'HT' + | 'HU' + | 'ID' + | 'IE' + | 'IL' + | 'IM' + | 'IN' + | 'IO' + | 'IQ' + | 'IR' + | 'IS' + | 'IT' + | 'JE' + | 'JM' + | 'JO' + | 'JP' + | 'KE' + | 'KG' + | 'KH' + | 'KI' + | 'KM' + | 'KN' + | 'KP' + | 'KR' + | 'KW' + | 'KY' + | 'KZ' + | 'LA' + | 'LB' + | 'LC' + | 'LI' + | 'LK' + | 'LR' + | 'LS' + | 'LT' + | 'LU' + | 'LV' + | 'LY' + | 'MA' + | 'MC' + | 'MD' + | 'ME' + | 'MF' + | 'MG' + | 'MH' + | 'MK' + | 'ML' + | 'MM' + | 'MN' + | 'MO' + | 'MP' + | 'MQ' + | 'MR' + | 'MS' + | 'MT' + | 'MU' + | 'MV' + | 'MW' + | 'MX' + | 'MY' + | 'MZ' + | 'NA' + | 'NC' + | 'NE' + | 'NF' + | 'NG' + | 'NI' + | 'NL' + | 'NO' + | 'NP' + | 'NR' + | 'NU' + | 'NZ' + | 'OM' + | 'PA' + | 'PE' + | 'PF' + | 'PG' + | 'PH' + | 'PK' + | 'PL' + | 'PM' + | 'PN' + | 'PR' + | 'PS' + | 'PT' + | 'PW' + | 'PY' + | 'QA' + | 'RE' + | 'RO' + | 'RS' + | 'RU' + | 'RW' + | 'SA' + | 'SB' + | 'SC' + | 'SD' + | 'SE' + | 'SG' + | 'SH' + | 'SI' + | 'SJ' + | 'SK' + | 'SL' + | 'SM' + | 'SN' + | 'SO' + | 'SR' + | 'SS' + | 'ST' + | 'SV' + | 'SX' + | 'SY' + | 'SZ' + | 'TC' + | 'TD' + | 'TF' + | 'TG' + | 'TH' + | 'TJ' + | 'TK' + | 'TL' + | 'TM' + | 'TN' + | 'TO' + | 'TR' + | 'TT' + | 'TV' + | 'TW' + | 'TZ' + | 'UA' + | 'UG' + | 'UM' + | 'US' + | 'UY' + | 'UZ' + | 'VA' + | 'VC' + | 'VE' + | 'VG' + | 'VI' + | 'VN' + | 'VU' + | 'WF' + | 'WS' + | 'YE' + | 'YT' + | 'ZA' + | 'ZM' + | 'ZW'; + + /** + * The brand's description, when available. + */ + description?: string; + + /** + * The brand's primary language, when available. + */ + language?: + | 'afrikaans' + | 'albanian' + | 'amharic' + | 'arabic' + | 'armenian' + | 'assamese' + | 'aymara' + | 'azeri' + | 'basque' + | 'belarusian' + | 'bengali' + | 'bosnian' + | 'bulgarian' + | 'burmese' + | 'cantonese' + | 'catalan' + | 'cebuano' + | 'chinese' + | 'corsican' + | 'croatian' + | 'czech' + | 'danish' + | 'dutch' + | 'english' + | 'esperanto' + | 'estonian' + | 'farsi' + | 'fijian' + | 'finnish' + | 'french' + | 'galician' + | 'georgian' + | 'german' + | 'greek' + | 'guarani' + | 'gujarati' + | 'haitian-creole' + | 'hausa' + | 'hawaiian' + | 'hebrew' + | 'hindi' + | 'hmong' + | 'hungarian' + | 'icelandic' + | 'igbo' + | 'indonesian' + | 'irish' + | 'italian' + | 'japanese' + | 'javanese' + | 'kannada' + | 'kazakh' + | 'khmer' + | 'kinyarwanda' + | 'korean' + | 'kurdish' + | 'kyrgyz' + | 'lao' + | 'latin' + | 'latvian' + | 'lingala' + | 'lithuanian' + | 'luxembourgish' + | 'macedonian' + | 'malagasy' + | 'malay' + | 'malayalam' + | 'maltese' + | 'maori' + | 'marathi' + | 'mongolian' + | 'nepali' + | 'norwegian' + | 'odia' + | 'oromo' + | 'pashto' + | 'pidgin' + | 'polish' + | 'portuguese' + | 'punjabi' + | 'quechua' + | 'romanian' + | 'russian' + | 'samoan' + | 'scottish-gaelic' + | 'serbian' + | 'sesotho' + | 'shona' + | 'sindhi' + | 'sinhala' + | 'slovak' + | 'slovene' + | 'somali' + | 'spanish' + | 'sundanese' + | 'swahili' + | 'swedish' + | 'tagalog' + | 'tajik' + | 'tamil' + | 'tatar' + | 'telugu' + | 'thai' + | 'tibetan' + | 'tigrinya' + | 'tongan' + | 'tswana' + | 'turkish' + | 'turkmen' + | 'ukrainian' + | 'urdu' + | 'uyghur' + | 'uzbek' + | 'vietnamese' + | 'welsh' + | 'wolof' + | 'xhosa' + | 'yiddish' + | 'yoruba' + | 'zulu'; } /** @@ -2463,6 +2849,386 @@ export interface BrandSearchParams { */ autocomplete?: boolean; + /** + * Only return brands in this country, as an uppercase ISO 3166-1 alpha-2 code such + * as US or GB. + */ + country?: + | 'AD' + | 'AE' + | 'AF' + | 'AG' + | 'AI' + | 'AL' + | 'AM' + | 'AO' + | 'AQ' + | 'AR' + | 'AS' + | 'AT' + | 'AU' + | 'AW' + | 'AX' + | 'AZ' + | 'BA' + | 'BB' + | 'BD' + | 'BE' + | 'BF' + | 'BG' + | 'BH' + | 'BI' + | 'BJ' + | 'BL' + | 'BM' + | 'BN' + | 'BO' + | 'BQ' + | 'BR' + | 'BS' + | 'BT' + | 'BV' + | 'BW' + | 'BY' + | 'BZ' + | 'CA' + | 'CC' + | 'CD' + | 'CF' + | 'CG' + | 'CH' + | 'CI' + | 'CK' + | 'CL' + | 'CM' + | 'CN' + | 'CO' + | 'CR' + | 'CU' + | 'CV' + | 'CW' + | 'CX' + | 'CY' + | 'CZ' + | 'DE' + | 'DJ' + | 'DK' + | 'DM' + | 'DO' + | 'DZ' + | 'EC' + | 'EE' + | 'EG' + | 'EH' + | 'ER' + | 'ES' + | 'ET' + | 'FI' + | 'FJ' + | 'FK' + | 'FM' + | 'FO' + | 'FR' + | 'GA' + | 'GB' + | 'GD' + | 'GE' + | 'GF' + | 'GG' + | 'GH' + | 'GI' + | 'GL' + | 'GM' + | 'GN' + | 'GP' + | 'GQ' + | 'GR' + | 'GS' + | 'GT' + | 'GU' + | 'GW' + | 'GY' + | 'HK' + | 'HM' + | 'HN' + | 'HR' + | 'HT' + | 'HU' + | 'ID' + | 'IE' + | 'IL' + | 'IM' + | 'IN' + | 'IO' + | 'IQ' + | 'IR' + | 'IS' + | 'IT' + | 'JE' + | 'JM' + | 'JO' + | 'JP' + | 'KE' + | 'KG' + | 'KH' + | 'KI' + | 'KM' + | 'KN' + | 'KP' + | 'KR' + | 'KW' + | 'KY' + | 'KZ' + | 'LA' + | 'LB' + | 'LC' + | 'LI' + | 'LK' + | 'LR' + | 'LS' + | 'LT' + | 'LU' + | 'LV' + | 'LY' + | 'MA' + | 'MC' + | 'MD' + | 'ME' + | 'MF' + | 'MG' + | 'MH' + | 'MK' + | 'ML' + | 'MM' + | 'MN' + | 'MO' + | 'MP' + | 'MQ' + | 'MR' + | 'MS' + | 'MT' + | 'MU' + | 'MV' + | 'MW' + | 'MX' + | 'MY' + | 'MZ' + | 'NA' + | 'NC' + | 'NE' + | 'NF' + | 'NG' + | 'NI' + | 'NL' + | 'NO' + | 'NP' + | 'NR' + | 'NU' + | 'NZ' + | 'OM' + | 'PA' + | 'PE' + | 'PF' + | 'PG' + | 'PH' + | 'PK' + | 'PL' + | 'PM' + | 'PN' + | 'PR' + | 'PS' + | 'PT' + | 'PW' + | 'PY' + | 'QA' + | 'RE' + | 'RO' + | 'RS' + | 'RU' + | 'RW' + | 'SA' + | 'SB' + | 'SC' + | 'SD' + | 'SE' + | 'SG' + | 'SH' + | 'SI' + | 'SJ' + | 'SK' + | 'SL' + | 'SM' + | 'SN' + | 'SO' + | 'SR' + | 'SS' + | 'ST' + | 'SV' + | 'SX' + | 'SY' + | 'SZ' + | 'TC' + | 'TD' + | 'TF' + | 'TG' + | 'TH' + | 'TJ' + | 'TK' + | 'TL' + | 'TM' + | 'TN' + | 'TO' + | 'TR' + | 'TT' + | 'TV' + | 'TW' + | 'TZ' + | 'UA' + | 'UG' + | 'UM' + | 'US' + | 'UY' + | 'UZ' + | 'VA' + | 'VC' + | 'VE' + | 'VG' + | 'VI' + | 'VN' + | 'VU' + | 'WF' + | 'WS' + | 'YE' + | 'YT' + | 'ZA' + | 'ZM' + | 'ZW'; + + /** + * Only return brands with this primary language, such as english or french. + */ + language?: + | 'afrikaans' + | 'albanian' + | 'amharic' + | 'arabic' + | 'armenian' + | 'assamese' + | 'aymara' + | 'azeri' + | 'basque' + | 'belarusian' + | 'bengali' + | 'bosnian' + | 'bulgarian' + | 'burmese' + | 'cantonese' + | 'catalan' + | 'cebuano' + | 'chinese' + | 'corsican' + | 'croatian' + | 'czech' + | 'danish' + | 'dutch' + | 'english' + | 'esperanto' + | 'estonian' + | 'farsi' + | 'fijian' + | 'finnish' + | 'french' + | 'galician' + | 'georgian' + | 'german' + | 'greek' + | 'guarani' + | 'gujarati' + | 'haitian-creole' + | 'hausa' + | 'hawaiian' + | 'hebrew' + | 'hindi' + | 'hmong' + | 'hungarian' + | 'icelandic' + | 'igbo' + | 'indonesian' + | 'irish' + | 'italian' + | 'japanese' + | 'javanese' + | 'kannada' + | 'kazakh' + | 'khmer' + | 'kinyarwanda' + | 'korean' + | 'kurdish' + | 'kyrgyz' + | 'lao' + | 'latin' + | 'latvian' + | 'lingala' + | 'lithuanian' + | 'luxembourgish' + | 'macedonian' + | 'malagasy' + | 'malay' + | 'malayalam' + | 'maltese' + | 'maori' + | 'marathi' + | 'mongolian' + | 'nepali' + | 'norwegian' + | 'odia' + | 'oromo' + | 'pashto' + | 'pidgin' + | 'polish' + | 'portuguese' + | 'punjabi' + | 'quechua' + | 'romanian' + | 'russian' + | 'samoan' + | 'scottish-gaelic' + | 'serbian' + | 'sesotho' + | 'shona' + | 'sindhi' + | 'sinhala' + | 'slovak' + | 'slovene' + | 'somali' + | 'spanish' + | 'sundanese' + | 'swahili' + | 'swedish' + | 'tagalog' + | 'tajik' + | 'tamil' + | 'tatar' + | 'telugu' + | 'thai' + | 'tibetan' + | 'tigrinya' + | 'tongan' + | 'tswana' + | 'turkish' + | 'turkmen' + | 'ukrainian' + | 'urdu' + | 'uyghur' + | 'uzbek' + | 'vietnamese' + | 'welsh' + | 'wolof' + | 'xhosa' + | 'yiddish' + | 'yoruba' + | 'zulu'; + /** * Fields to match the search term against, as a comma-separated list or repeated * parameter: 'name', 'domain', or both. Defaults to both. diff --git a/tests/api-resources/brand.test.ts b/tests/api-resources/brand.test.ts index f1c14028..c7e9de92 100644 --- a/tests/api-resources/brand.test.ts +++ b/tests/api-resources/brand.test.ts @@ -50,6 +50,8 @@ describe('resource brand', () => { const response = await client.brand.search({ query: 'x', autocomplete: true, + country: 'US', + language: 'afrikaans', queryBy: ['name'], tags: ['production', 'team-alpha'], typoTolerance: 0, From 827c2476a24a188e5088b2e404cadf83b312b8c8 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Sat, 17 Oct 2026 09:21:13 +0200 Subject: [PATCH 162/232] release: 3.8.0 (#89) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 11 +++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 14 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 2a266f81..573f0901 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.7.0" + ".": "3.8.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 65d88fb1..cf22106d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog +## [3.8.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.7.0...v3.8.0) (2026-10-17) + + +### Features + +* **brand:** add search metadata and country and language filters ([#1945](https://github.com/context-dot-dev/context-typescript-sdk/issues/1945)) ([8782f4e](https://github.com/context-dot-dev/context-typescript-sdk/commit/8782f4e71a5f391b1f414fcf587d41219b26a746)) +* **scrape:** add g2-reviews prebuilt parser ([#1933](https://github.com/context-dot-dev/context-typescript-sdk/issues/1933)) ([8d2fa9e](https://github.com/context-dot-dev/context-typescript-sdk/commit/8d2fa9efc4d8925f09c51194f305e32818f0ca3e)) +* **scrape:** add google-maps-reviews prebuilt parser with oldest-first sort ([#1928](https://github.com/context-dot-dev/context-typescript-sdk/issues/1928)) ([30315d0](https://github.com/context-dot-dev/context-typescript-sdk/commit/30315d037ab9024b2efea6e9b8d3337da8afcb03)) +* **scrape:** add Instagram profile, post, and feed prebuilt parsers ([#1905](https://github.com/context-dot-dev/context-typescript-sdk/issues/1905)) ([ae45c50](https://github.com/context-dot-dev/context-typescript-sdk/commit/ae45c503c70bc4903562e7324acc4c76554e7a7f)) +* **search:** add languages filter to web search ([#1833](https://github.com/context-dot-dev/context-typescript-sdk/issues/1833)) ([e07f6c3](https://github.com/context-dot-dev/context-typescript-sdk/commit/e07f6c3c09327a969ca5641cb1eca1cc8cfbaa64)) + ## [3.7.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.6.0...v3.7.0) (2026-10-16) diff --git a/package.json b/package.json index 0dc178de..dfd2f936 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.7.0", + "version": "3.8.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index dd90c738..315b1f99 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.7.0'; // x-release-please-version +export const VERSION = '3.8.0'; // x-release-please-version From 355cd7dc5b406402127c657a81d799ff9915f8e4 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 18 Oct 2026 01:06:06 +0000 Subject: [PATCH 163/232] feat(people): allow enrichment on free plans (#1961) Stainless-Generated-From: c20db5f53012578a5eaba615adf631f246e53933 --- src/resources/people.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/resources/people.ts b/src/resources/people.ts index e20303b5..bd48e313 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -7,7 +7,7 @@ import { RequestOptions } from '../internal/request-options'; export class People extends APIResource { /** * Find a person from identity clues and return their profile with a match score. - * Requires a paid plan; free or disposable email addresses return 422. + * Available on all plans; free or disposable email addresses return 422. * * @example * ```ts From 2c9653b1b01a12c9b8c9e1b6a24478714ccd90d0 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Sun, 18 Oct 2026 03:33:13 +0200 Subject: [PATCH 164/232] release: 3.9.0 (#90) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 573f0901..f1c8ae50 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.8.0" + ".": "3.9.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index cf22106d..10a4fc15 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.9.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.8.0...v3.9.0) (2026-10-18) + + +### Features + +* **people:** allow enrichment on free plans ([#1961](https://github.com/context-dot-dev/context-typescript-sdk/issues/1961)) ([355cd7d](https://github.com/context-dot-dev/context-typescript-sdk/commit/355cd7dc5b406402127c657a81d799ff9915f8e4)) + ## [3.8.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.7.0...v3.8.0) (2026-10-17) diff --git a/package.json b/package.json index dfd2f936..8f2c3539 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.8.0", + "version": "3.9.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 315b1f99..e0223e3e 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.8.0'; // x-release-please-version +export const VERSION = '3.9.0'; // x-release-please-version From 2b7a9223088c1aa018205300fa489d4877dd981b Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 18 Oct 2026 07:18:23 +0000 Subject: [PATCH 165/232] feat(scrape): add TikTok profile and video prebuilt parsers (#1956) Stainless-Generated-From: 5196e2d7ef6c1ebf797d487cffaa177071d12dda --- src/resources/batch.ts | 154 +++++++++++++++++++++++++++++++---------- src/resources/web.ts | 77 ++++++++++++++++----- 2 files changed, 174 insertions(+), 57 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 745e1e67..2c5ea636 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -1125,10 +1125,13 @@ export namespace BatchGetResultsResponse { * app record as data, google-play-reviews returns data.reviews, app-store and * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews * for a G2 product, instagram-profile and instagram-post return one record as - * data, instagram-feed returns data.posts, emails, phone-numbers, and links return - * data.emails, data.phone_numbers, and data.links from the rendered page; the - * store, Maps, G2, and Instagram parsers read their data directly, independently - * of DOM filters and other outputs. + * data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return + * one record as data, tiktok-feed returns data.videos, tiktok-comments returns + * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return + * data.users, emails, phone-numbers, and links return data.emails, + * data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, + * Instagram, and TikTok parsers read their data directly, independently of DOM + * filters and other outputs. */ parsed: Result.Parsed; @@ -1522,10 +1525,13 @@ export namespace BatchGetResultsResponse { * app record as data, google-play-reviews returns data.reviews, app-store and * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews * for a G2 product, instagram-profile and instagram-post return one record as - * data, instagram-feed returns data.posts, emails, phone-numbers, and links return - * data.emails, data.phone_numbers, and data.links from the rendered page; the - * store, Maps, G2, and Instagram parsers read their data directly, independently - * of DOM filters and other outputs. + * data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return + * one record as data, tiktok-feed returns data.videos, tiktok-comments returns + * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return + * data.users, emails, phone-numbers, and links return data.emails, + * data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, + * Instagram, and TikTok parsers read their data directly, independently of DOM + * filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1553,6 +1559,13 @@ export namespace BatchGetResultsResponse { | 'instagram-profile' | 'instagram-post' | 'instagram-feed' + | 'tiktok-profile' + | 'tiktok-video' + | 'tiktok-feed' + | 'tiktok-comments' + | 'tiktok-followers' + | 'tiktok-following' + | 'tiktok-user-search' | 'emails' | 'phone-numbers' | 'links'; @@ -1884,10 +1897,13 @@ export namespace BatchGetResultsResponse { * app record as data, google-play-reviews returns data.reviews, app-store and * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews * for a G2 product, instagram-profile and instagram-post return one record as - * data, instagram-feed returns data.posts, emails, phone-numbers, and links return - * data.emails, data.phone_numbers, and data.links from the rendered page; the - * store, Maps, G2, and Instagram parsers read their data directly, independently - * of DOM filters and other outputs. + * data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return + * one record as data, tiktok-feed returns data.videos, tiktok-comments returns + * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return + * data.users, emails, phone-numbers, and links return data.emails, + * data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, + * Instagram, and TikTok parsers read their data directly, independently of DOM + * filters and other outputs. */ parsed: Result.Parsed; @@ -2281,10 +2297,13 @@ export namespace BatchGetResultsResponse { * app record as data, google-play-reviews returns data.reviews, app-store and * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews * for a G2 product, instagram-profile and instagram-post return one record as - * data, instagram-feed returns data.posts, emails, phone-numbers, and links return - * data.emails, data.phone_numbers, and data.links from the rendered page; the - * store, Maps, G2, and Instagram parsers read their data directly, independently - * of DOM filters and other outputs. + * data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return + * one record as data, tiktok-feed returns data.videos, tiktok-comments returns + * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return + * data.users, emails, phone-numbers, and links return data.emails, + * data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, + * Instagram, and TikTok parsers read their data directly, independently of DOM + * filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -2312,6 +2331,13 @@ export namespace BatchGetResultsResponse { | 'instagram-profile' | 'instagram-post' | 'instagram-feed' + | 'tiktok-profile' + | 'tiktok-video' + | 'tiktok-feed' + | 'tiktok-comments' + | 'tiktok-followers' + | 'tiktok-following' + | 'tiktok-user-search' | 'emails' | 'phone-numbers' | 'links'; @@ -3120,17 +3146,36 @@ export namespace BatchSubmitParams { * location (/explore/locations/{id}/…) in data.posts; keyword posts carry only the * shortcode, owner, thumbnail, and views, plus the caption when Instagram shows * it. All three Instagram parsers read public data without logging in, so private - * accounts return no posts and follower lists are unavailable. emails accepts any - * page and returns its email addresses as data.emails ([{ email }]), read from - * mailto links, Cloudflare-protected addresses, and visible text. phone-numbers - * accepts any page and returns its valid phone numbers in E.164 as - * data.phone_numbers ([{ phone }]), read from tel links and visible text; numbers - * without a country code are read for the country of the site TLD, defaulting to - * US. links accepts any page and returns its unique http(s) links as data.links - * ([{ url, text }]), with absolute URLs; text falls back to aria-label or image - * alt and is null when a link has none. The emails parser reads the rendered page - * and respects content filters; the other prebuilt parsers read their data - * independently of DOM filters. + * accounts return no posts and follower lists are unavailable. tiktok-profile + * parses a public profile (tiktok.com/@{username}) into data: nickname, bio, bio + * link, follower, following, like, and video counts, verified, private, and + * business flags, and business category; it does not list videos. tiktok-video + * parses a video or photo post (/@{username}/video/{id} or + * /@{username}/photo/{id}) into data: caption, hashtags, mentions, author, view, + * like, comment, share, save, and repost counts, duration, thumbnail, a video_url + * that downloads without cookies, image_urls for photo posts, music, location, and + * ad, paid-partnership, and AI-generated flags. tiktok-feed returns videos in the + * tiktok-video shape as data.videos: the latest 15 from a profile URL, the top 30 + * from a hashtag URL (/tag/{name}), or the top 12 from a search URL + * (/search?q={query}). tiktok-comments returns the first 20 comments of a video or + * photo post as data.comments: text, posted_at, like and reply counts, whether the + * author liked it, and the commenter. tiktok-followers and tiktok-following return + * up to 30 accounts of a profile as data.users, in the tiktok-profile shape. + * tiktok-user-search returns the top 10 accounts for a user search URL + * (/search/user?q={query}) as data.users: id, username, nickname, biography, + * avatar_url, sec_uid, follower_count, like_count, and is_verified. The TikTok + * parsers accept tiktok.com, www.tiktok.com, and m.tiktok.com URLs but not short + * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). emails accepts any page + * and returns its email addresses as data.emails ([{ email }]), read from mailto + * links, Cloudflare-protected addresses, and visible text. phone-numbers accepts + * any page and returns its valid phone numbers in E.164 as data.phone_numbers ([{ + * phone }]), read from tel links and visible text; numbers without a country code + * are read for the country of the site TLD, defaulting to US. links accepts any + * page and returns its unique http(s) links as data.links ([{ url, text }]), with + * absolute URLs; text falls back to aria-label or image alt and is null when a + * link has none. The emails parser reads the rendered page and respects content + * filters; the other prebuilt parsers read their data independently of DOM + * filters. */ parser: | 'google-maps' @@ -3143,6 +3188,13 @@ export namespace BatchSubmitParams { | 'instagram-profile' | 'instagram-post' | 'instagram-feed' + | 'tiktok-profile' + | 'tiktok-video' + | 'tiktok-feed' + | 'tiktok-comments' + | 'tiktok-followers' + | 'tiktok-following' + | 'tiktok-user-search' | 'emails' | 'phone-numbers' | 'links'; @@ -3853,17 +3905,36 @@ export namespace BatchSubmitParams { * location (/explore/locations/{id}/…) in data.posts; keyword posts carry only the * shortcode, owner, thumbnail, and views, plus the caption when Instagram shows * it. All three Instagram parsers read public data without logging in, so private - * accounts return no posts and follower lists are unavailable. emails accepts any - * page and returns its email addresses as data.emails ([{ email }]), read from - * mailto links, Cloudflare-protected addresses, and visible text. phone-numbers - * accepts any page and returns its valid phone numbers in E.164 as - * data.phone_numbers ([{ phone }]), read from tel links and visible text; numbers - * without a country code are read for the country of the site TLD, defaulting to - * US. links accepts any page and returns its unique http(s) links as data.links - * ([{ url, text }]), with absolute URLs; text falls back to aria-label or image - * alt and is null when a link has none. The emails parser reads the rendered page - * and respects content filters; the other prebuilt parsers read their data - * independently of DOM filters. + * accounts return no posts and follower lists are unavailable. tiktok-profile + * parses a public profile (tiktok.com/@{username}) into data: nickname, bio, bio + * link, follower, following, like, and video counts, verified, private, and + * business flags, and business category; it does not list videos. tiktok-video + * parses a video or photo post (/@{username}/video/{id} or + * /@{username}/photo/{id}) into data: caption, hashtags, mentions, author, view, + * like, comment, share, save, and repost counts, duration, thumbnail, a video_url + * that downloads without cookies, image_urls for photo posts, music, location, and + * ad, paid-partnership, and AI-generated flags. tiktok-feed returns videos in the + * tiktok-video shape as data.videos: the latest 15 from a profile URL, the top 30 + * from a hashtag URL (/tag/{name}), or the top 12 from a search URL + * (/search?q={query}). tiktok-comments returns the first 20 comments of a video or + * photo post as data.comments: text, posted_at, like and reply counts, whether the + * author liked it, and the commenter. tiktok-followers and tiktok-following return + * up to 30 accounts of a profile as data.users, in the tiktok-profile shape. + * tiktok-user-search returns the top 10 accounts for a user search URL + * (/search/user?q={query}) as data.users: id, username, nickname, biography, + * avatar_url, sec_uid, follower_count, like_count, and is_verified. The TikTok + * parsers accept tiktok.com, www.tiktok.com, and m.tiktok.com URLs but not short + * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). emails accepts any page + * and returns its email addresses as data.emails ([{ email }]), read from mailto + * links, Cloudflare-protected addresses, and visible text. phone-numbers accepts + * any page and returns its valid phone numbers in E.164 as data.phone_numbers ([{ + * phone }]), read from tel links and visible text; numbers without a country code + * are read for the country of the site TLD, defaulting to US. links accepts any + * page and returns its unique http(s) links as data.links ([{ url, text }]), with + * absolute URLs; text falls back to aria-label or image alt and is null when a + * link has none. The emails parser reads the rendered page and respects content + * filters; the other prebuilt parsers read their data independently of DOM + * filters. */ parser: | 'google-maps' @@ -3876,6 +3947,13 @@ export namespace BatchSubmitParams { | 'instagram-profile' | 'instagram-post' | 'instagram-feed' + | 'tiktok-profile' + | 'tiktok-video' + | 'tiktok-feed' + | 'tiktok-comments' + | 'tiktok-followers' + | 'tiktok-following' + | 'tiktok-user-search' | 'emails' | 'phone-numbers' | 'links'; diff --git a/src/resources/web.ts b/src/resources/web.ts index d4c63e70..298a42fa 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -956,10 +956,13 @@ export interface WebScrapeResponse { * app record as data, google-play-reviews returns data.reviews, app-store and * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews * for a G2 product, instagram-profile and instagram-post return one record as - * data, instagram-feed returns data.posts, emails, phone-numbers, and links return - * data.emails, data.phone_numbers, and data.links from the rendered page; the - * store, Maps, G2, and Instagram parsers read their data directly, independently - * of DOM filters and other outputs. + * data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return + * one record as data, tiktok-feed returns data.videos, tiktok-comments returns + * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return + * data.users, emails, phone-numbers, and links return data.emails, + * data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, + * Instagram, and TikTok parsers read their data directly, independently of DOM + * filters and other outputs. */ parsed: WebScrapeResponse.Parsed; @@ -1353,10 +1356,13 @@ export namespace WebScrapeResponse { * app record as data, google-play-reviews returns data.reviews, app-store and * app-store-reviews do the same for the App Store, g2-reviews returns data.reviews * for a G2 product, instagram-profile and instagram-post return one record as - * data, instagram-feed returns data.posts, emails, phone-numbers, and links return - * data.emails, data.phone_numbers, and data.links from the rendered page; the - * store, Maps, G2, and Instagram parsers read their data directly, independently - * of DOM filters and other outputs. + * data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return + * one record as data, tiktok-feed returns data.videos, tiktok-comments returns + * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return + * data.users, emails, phone-numbers, and links return data.emails, + * data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, + * Instagram, and TikTok parsers read their data directly, independently of DOM + * filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1384,6 +1390,13 @@ export namespace WebScrapeResponse { | 'instagram-profile' | 'instagram-post' | 'instagram-feed' + | 'tiktok-profile' + | 'tiktok-video' + | 'tiktok-feed' + | 'tiktok-comments' + | 'tiktok-followers' + | 'tiktok-following' + | 'tiktok-user-search' | 'emails' | 'phone-numbers' | 'links'; @@ -2610,17 +2623,36 @@ export namespace WebScrapeParams { * location (/explore/locations/{id}/…) in data.posts; keyword posts carry only the * shortcode, owner, thumbnail, and views, plus the caption when Instagram shows * it. All three Instagram parsers read public data without logging in, so private - * accounts return no posts and follower lists are unavailable. emails accepts any - * page and returns its email addresses as data.emails ([{ email }]), read from - * mailto links, Cloudflare-protected addresses, and visible text. phone-numbers - * accepts any page and returns its valid phone numbers in E.164 as - * data.phone_numbers ([{ phone }]), read from tel links and visible text; numbers - * without a country code are read for the country of the site TLD, defaulting to - * US. links accepts any page and returns its unique http(s) links as data.links - * ([{ url, text }]), with absolute URLs; text falls back to aria-label or image - * alt and is null when a link has none. The emails parser reads the rendered page - * and respects content filters; the other prebuilt parsers read their data - * independently of DOM filters. + * accounts return no posts and follower lists are unavailable. tiktok-profile + * parses a public profile (tiktok.com/@{username}) into data: nickname, bio, bio + * link, follower, following, like, and video counts, verified, private, and + * business flags, and business category; it does not list videos. tiktok-video + * parses a video or photo post (/@{username}/video/{id} or + * /@{username}/photo/{id}) into data: caption, hashtags, mentions, author, view, + * like, comment, share, save, and repost counts, duration, thumbnail, a video_url + * that downloads without cookies, image_urls for photo posts, music, location, and + * ad, paid-partnership, and AI-generated flags. tiktok-feed returns videos in the + * tiktok-video shape as data.videos: the latest 15 from a profile URL, the top 30 + * from a hashtag URL (/tag/{name}), or the top 12 from a search URL + * (/search?q={query}). tiktok-comments returns the first 20 comments of a video or + * photo post as data.comments: text, posted_at, like and reply counts, whether the + * author liked it, and the commenter. tiktok-followers and tiktok-following return + * up to 30 accounts of a profile as data.users, in the tiktok-profile shape. + * tiktok-user-search returns the top 10 accounts for a user search URL + * (/search/user?q={query}) as data.users: id, username, nickname, biography, + * avatar_url, sec_uid, follower_count, like_count, and is_verified. The TikTok + * parsers accept tiktok.com, www.tiktok.com, and m.tiktok.com URLs but not short + * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). emails accepts any page + * and returns its email addresses as data.emails ([{ email }]), read from mailto + * links, Cloudflare-protected addresses, and visible text. phone-numbers accepts + * any page and returns its valid phone numbers in E.164 as data.phone_numbers ([{ + * phone }]), read from tel links and visible text; numbers without a country code + * are read for the country of the site TLD, defaulting to US. links accepts any + * page and returns its unique http(s) links as data.links ([{ url, text }]), with + * absolute URLs; text falls back to aria-label or image alt and is null when a + * link has none. The emails parser reads the rendered page and respects content + * filters; the other prebuilt parsers read their data independently of DOM + * filters. */ parser: | 'google-maps' @@ -2633,6 +2665,13 @@ export namespace WebScrapeParams { | 'instagram-profile' | 'instagram-post' | 'instagram-feed' + | 'tiktok-profile' + | 'tiktok-video' + | 'tiktok-feed' + | 'tiktok-comments' + | 'tiktok-followers' + | 'tiktok-following' + | 'tiktok-user-search' | 'emails' | 'phone-numbers' | 'links'; From 5b2552b7ed099c4a1e2441cd954f31e36f8aea91 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Sun, 18 Oct 2026 09:26:26 +0200 Subject: [PATCH 166/232] release: 3.10.0 (#91) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index f1c8ae50..0b9e26a6 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.9.0" + ".": "3.10.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 10a4fc15..57ed1675 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.10.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.9.0...v3.10.0) (2026-10-18) + + +### Features + +* **scrape:** add TikTok profile and video prebuilt parsers ([#1956](https://github.com/context-dot-dev/context-typescript-sdk/issues/1956)) ([2b7a922](https://github.com/context-dot-dev/context-typescript-sdk/commit/2b7a9223088c1aa018205300fa489d4877dd981b)) + ## [3.9.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.8.0...v3.9.0) (2026-10-18) diff --git a/package.json b/package.json index 8f2c3539..b2ff3508 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.9.0", + "version": "3.10.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index e0223e3e..fa1001bc 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.9.0'; // x-release-please-version +export const VERSION = '3.10.0'; // x-release-please-version From d2afbbee526024e7e5b497474dbcccd0a668c4a3 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 19 Oct 2026 04:02:09 +0000 Subject: [PATCH 167/232] feat(news): add natural-language search to POST /news/search (#1975) Stainless-Generated-From: 9310ecf65c30726f2f1611f040e22df3c10f0a7f --- src/resources/news.ts | 57 ++++++++++++++++++++++++++++++------------- 1 file changed, 40 insertions(+), 17 deletions(-) diff --git a/src/resources/news.ts b/src/resources/news.ts index c3d6fa44..03d259ad 100644 --- a/src/resources/news.ts +++ b/src/resources/news.ts @@ -9,8 +9,9 @@ import { RequestOptions } from '../internal/request-options'; */ export class News extends APIResource { /** - * Find company news by name, domain, ticker, or ISIN. Filter articles and continue - * through results with a cursor. + * Find news about a company by name, domain, ticker, or ISIN, or search all news + * with a natural-language query. Filter articles and continue through results with + * a cursor. * * @example * ```ts @@ -91,9 +92,10 @@ export namespace NewsSearchResponse { language: string | null; /** - * How the article relates to the company you searched for. + * How the article relates to the company you searched for. Null for + * natural-language searches. */ - match: Data.Match; + match: Data.Match | null; /** * When the article was published, as an ISO 8601 timestamp. Null when the @@ -131,7 +133,8 @@ export namespace NewsSearchResponse { export namespace Data { /** - * How the article relates to the company you searched for. + * How the article relates to the company you searched for. Null for + * natural-language searches. */ export interface Match { /** @@ -195,9 +198,10 @@ export namespace NewsSearchResponse { export interface NewsSearchParams { /** - * What to search for. + * What to search for: a specific company, or a natural-language query across all + * news. */ - searchBy: NewsSearchParams.SearchBy; + searchBy: NewsSearchParams.NewsSearchByNaturalLanguage | NewsSearchParams.NewsSearchByEntity; /** * Opaque next_cursor from the previous response, or null for the first page. @@ -217,7 +221,8 @@ export interface NewsSearchParams { limit?: number; /** - * Result ordering. Defaults to newest. + * Result ordering. Defaults to newest for entity searches. Natural-language + * searches are always ordered by relevance. */ sortBy?: NewsSearchParams.SortBy; @@ -229,25 +234,42 @@ export interface NewsSearchParams { export namespace NewsSearchParams { /** - * What to search for. + * Search all news with a plain-language query. Returns up to 100 matches, ordered + * by relevance. */ - export interface SearchBy { + export interface NewsSearchByNaturalLanguage { + /** + * What to search for, in plain language, such as "chip export restrictions to + * China". + */ + query: string; + + /** + * Use `natural_language` to search all news with a plain-language query. + */ + type: 'natural_language'; + } + + /** + * Find news about a specific company. + */ + export interface NewsSearchByEntity { /** * The company to search news for, identified by name, domain, ticker, or ISIN. */ entity: - | SearchBy.NewsSearchEntityByName - | SearchBy.NewsSearchEntityByDomain - | SearchBy.NewsSearchEntityByTicker - | SearchBy.NewsSearchEntityByIsin; + | NewsSearchByEntity.NewsSearchEntityByName + | NewsSearchByEntity.NewsSearchEntityByDomain + | NewsSearchByEntity.NewsSearchEntityByTicker + | NewsSearchByEntity.NewsSearchEntityByIsin; /** - * How to search. Only entity search is supported. + * Use `entity` to find news about a specific company. */ type: 'entity'; } - export namespace SearchBy { + export namespace NewsSearchByEntity { /** * Identify the company by name. */ @@ -540,7 +562,8 @@ export namespace NewsSearchParams { } /** - * Result ordering. Defaults to newest. + * Result ordering. Defaults to newest for entity searches. Natural-language + * searches are always ordered by relevance. */ export interface SortBy { /** From 565ee87e175da02334146238ffd9204240cf760a Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Mon, 19 Oct 2026 06:06:34 +0200 Subject: [PATCH 168/232] release: 3.11.0 (#92) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 0b9e26a6..b5505621 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.10.0" + ".": "3.11.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 57ed1675..2f50e565 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.11.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.10.0...v3.11.0) (2026-10-19) + + +### Features + +* **news:** add natural-language search to POST /news/search ([#1975](https://github.com/context-dot-dev/context-typescript-sdk/issues/1975)) ([d2afbbe](https://github.com/context-dot-dev/context-typescript-sdk/commit/d2afbbee526024e7e5b497474dbcccd0a668c4a3)) + ## [3.10.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.9.0...v3.10.0) (2026-10-18) diff --git a/package.json b/package.json index b2ff3508..26a07ffe 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.10.0", + "version": "3.11.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index fa1001bc..4a5c3f74 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.10.0'; // x-release-please-version +export const VERSION = '3.11.0'; // x-release-please-version From 892d6fb350603d4e620c07daef9cd5442f279a94 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 19 Oct 2026 15:38:48 +0000 Subject: [PATCH 169/232] feat(crawl): add exclude URL regex to crawl and sitemap endpoints (#1982) Stainless-Generated-From: ae03df0a50b8dd60ff731ca7b84c567e5b02607d --- src/resources/batch.ts | 17 +++++++++++++++++ src/resources/web.ts | 16 ++++++++++++++-- tests/api-resources/web.test.ts | 2 ++ 3 files changed, 33 insertions(+), 2 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 2c5ea636..18c370c8 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -164,6 +164,11 @@ export interface Failure { * Crawl settings as submitted. */ export interface CrawlControls { + /** + * RE2 pattern URLs must not match to be crawled. Null when the crawl set none. + */ + exclude_url_pattern: string | null; + /** * Whether links to subdomains were followed. Always false for a sitemap crawl. */ @@ -3705,6 +3710,12 @@ export namespace BatchSubmitParams { * Limits and filters for page discovery. */ export interface Controls { + /** + * RE2 pattern for URLs to exclude, even when they match `regex`. The `start_url` + * itself is always included. + */ + excludeRegex?: string; + /** * Follow links to subdomains. */ @@ -3756,6 +3767,12 @@ export namespace BatchSubmitParams { * URLs and never follows links off them, so there is no crawl depth here. */ export interface Controls { + /** + * RE2 pattern; sitemap URLs matching it are not scraped, even when they match + * `regex`. + */ + excludeRegex?: string; + /** * Maximum pages to fetch. Unused reserved credits are refunded. Maximum 100000. */ diff --git a/src/resources/web.ts b/src/resources/web.ts index 298a42fa..a4b081a9 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1924,8 +1924,8 @@ export namespace WebWebCrawlMdResponse { numFailed: number; /** - * Number of URLs skipped (PDFs when pdf.shouldParse=false, or URLs not matching - * urlRegex) + * Number of URLs skipped (PDFs when pdf.shouldParse=false, URLs not matching + * urlRegex, or URLs matching excludeUrlRegex) */ numSkipped: number; @@ -2294,6 +2294,12 @@ export interface WebMapURLsParams { */ domain: string; + /** + * Optional RE2-compatible regex pattern. URLs matching this pattern are not + * returned, even when they match urlRegex. + */ + excludeUrlRegex?: string; + /** * HTTP headers for the target origin. Non-empty headers bypass caching. */ @@ -4108,6 +4114,12 @@ export interface WebWebCrawlMdParams { */ excludeSelectors?: Array | null; + /** + * RE2 regex pattern. URLs matching this pattern are never followed or scraped, + * even when they match urlRegex. The starting URL is always scraped. + */ + excludeUrlRegex?: string; + /** * When true, follow links on subdomains of the starting URL's domain (e.g. * docs.example.com when starting from example.com). www and apex are always diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 22cfaae3..ca0625f6 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -104,6 +104,7 @@ describe('resource web', () => { test.skip('mapUrls: required and optional params', async () => { const response = await client.web.mapUrls({ domain: 'stripe.com', + excludeUrlRegex: '/tag/|/author/', headers: { foo: 'J!' }, includeSubdomains: true, maxLinks: 1, @@ -310,6 +311,7 @@ describe('resource web', () => { url: 'https://example.com', country: 'de', excludeSelectors: ['x'], + excludeUrlRegex: '/tag/|/author/', followSubdomains: true, includeFrames: true, includeImages: true, From 9aff16a143f5e7e136aba2227f9514c28609f3d8 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Mon, 19 Oct 2026 18:28:58 +0200 Subject: [PATCH 170/232] release: 3.12.0 (#93) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index b5505621..24e095ae 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.11.0" + ".": "3.12.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 2f50e565..60607106 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.12.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.11.0...v3.12.0) (2026-10-19) + + +### Features + +* **crawl:** add exclude URL regex to crawl and sitemap endpoints ([#1982](https://github.com/context-dot-dev/context-typescript-sdk/issues/1982)) ([892d6fb](https://github.com/context-dot-dev/context-typescript-sdk/commit/892d6fb350603d4e620c07daef9cd5442f279a94)) + ## [3.11.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.10.0...v3.11.0) (2026-10-19) diff --git a/package.json b/package.json index 26a07ffe..31537568 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.11.0", + "version": "3.12.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 4a5c3f74..4c203580 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.11.0'; // x-release-please-version +export const VERSION = '3.12.0'; // x-release-please-version From 99f1f90fd28d2e9b6c39efd7a2c9024f37206bb0 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 21 Oct 2026 04:21:58 +0000 Subject: [PATCH 171/232] fix(news): return extended descriptions for index search (#2019) Stainless-Generated-From: 89c5ca071d6dc8314a36573d046505fa210ddf2e --- src/resources/news.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/resources/news.ts b/src/resources/news.ts index 03d259ad..1682b22c 100644 --- a/src/resources/news.ts +++ b/src/resources/news.ts @@ -76,7 +76,8 @@ export namespace NewsSearchResponse { authors: Array; /** - * Short summary or excerpt of the article, when the publisher provides one. + * Article summary or excerpt. Natural-language search descriptions include + * matching passages and are capped at 2,000 characters. */ description: string | null; From ac5b1cc0da20891c4e614fa2dc9ba5c4bf7d3e26 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Wed, 21 Oct 2026 06:29:00 +0200 Subject: [PATCH 172/232] release: 3.12.1 (#94) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 24e095ae..40befa07 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.12.0" + ".": "3.12.1" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 60607106..7f471df1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.12.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.12.0...v3.12.1) (2026-10-21) + + +### Bug Fixes + +* **news:** return extended descriptions for index search ([#2019](https://github.com/context-dot-dev/context-typescript-sdk/issues/2019)) ([99f1f90](https://github.com/context-dot-dev/context-typescript-sdk/commit/99f1f90fd28d2e9b6c39efd7a2c9024f37206bb0)) + ## [3.12.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.11.0...v3.12.0) (2026-10-19) diff --git a/package.json b/package.json index 31537568..b40d8123 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.12.0", + "version": "3.12.1", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 4c203580..3a137f42 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.12.0'; // x-release-please-version +export const VERSION = '3.12.1'; // x-release-please-version From 31814309db43f2f76876a13cb46823a247663ff0 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 21 Oct 2026 15:01:55 +0000 Subject: [PATCH 173/232] fix(answers): document request_id in the /web/answers response (#2040) Stainless-Generated-From: 6ae90589ed6e06e6249c553bf393d102d365988e --- src/resources/web.ts | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/resources/web.ts b/src/resources/web.ts index a4b081a9..ee3b3086 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -143,6 +143,12 @@ export interface WebAnswersResponse { */ json_content: { [key: string]: unknown }; + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + /** * URLs of the pages and company/profile records read for the answer, followed by * URLs cited in json_content. From 895b2c307563aa2465d255eadff012937033b054 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Wed, 21 Oct 2026 17:26:28 +0200 Subject: [PATCH 174/232] release: 3.12.2 (#95) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 40befa07..0e5ac191 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.12.1" + ".": "3.12.2" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f471df1..0f79f2fe 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.12.2](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.12.1...v3.12.2) (2026-10-21) + + +### Bug Fixes + +* **answers:** document request_id in the /web/answers response ([#2040](https://github.com/context-dot-dev/context-typescript-sdk/issues/2040)) ([3181430](https://github.com/context-dot-dev/context-typescript-sdk/commit/31814309db43f2f76876a13cb46823a247663ff0)) + ## [3.12.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.12.0...v3.12.1) (2026-10-21) diff --git a/package.json b/package.json index b40d8123..94b57e92 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.12.1", + "version": "3.12.2", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 3a137f42..5a9bfed2 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.12.1'; // x-release-please-version +export const VERSION = '3.12.2'; // x-release-please-version From 867de4d4e66c5bbe8e7be5ba28537bd42e5a1518 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 21 Oct 2026 16:05:31 +0000 Subject: [PATCH 175/232] fix(openapi): document request_id and key_metadata on every response in one place (#2042) Stainless-Generated-From: 90ad5fb536e58939fddd45c16485b41586d14d77 --- src/resources/batch.ts | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 18c370c8..4f43bff7 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -334,7 +334,7 @@ export interface BatchRetrieveResponse { timing: BatchRetrieveResponse.Timing; /** - * API key usage for this request. + * Credits this request used and your remaining balance. */ key_metadata?: BatchRetrieveResponse.KeyMetadata; @@ -506,7 +506,7 @@ export namespace BatchRetrieveResponse { } /** - * API key usage for this request. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** @@ -890,7 +890,7 @@ export interface BatchCancelResponse { timing: BatchCancelResponse.Timing; /** - * API key usage for this request. + * Credits this request used and your remaining balance. */ key_metadata?: BatchCancelResponse.KeyMetadata; } @@ -992,7 +992,7 @@ export namespace BatchCancelResponse { } /** - * API key usage for this request. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** @@ -2647,7 +2647,7 @@ export interface BatchSubmitResponse { tags: Array; /** - * API key usage for this request. + * Credits this request used and your remaining balance. */ key_metadata?: BatchSubmitResponse.KeyMetadata; @@ -2747,7 +2747,7 @@ export namespace BatchSubmitResponse { } /** - * API key usage for this request. + * Credits this request used and your remaining balance. */ export interface KeyMetadata { /** From 1be9d03689d4cf8d4b67b6db77dc71086099b47e Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Wed, 21 Oct 2026 18:26:46 +0200 Subject: [PATCH 176/232] release: 3.12.3 (#96) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 0e5ac191..f3fe2c8f 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.12.2" + ".": "3.12.3" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 0f79f2fe..ec352c3f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.12.3](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.12.2...v3.12.3) (2026-10-21) + + +### Bug Fixes + +* **openapi:** document request_id and key_metadata on every response in one place ([#2042](https://github.com/context-dot-dev/context-typescript-sdk/issues/2042)) ([867de4d](https://github.com/context-dot-dev/context-typescript-sdk/commit/867de4d4e66c5bbe8e7be5ba28537bd42e5a1518)) + ## [3.12.2](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.12.1...v3.12.2) (2026-10-21) diff --git a/package.json b/package.json index 94b57e92..174e9bce 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.12.2", + "version": "3.12.3", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 5a9bfed2..a5db0bfe 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.12.2'; // x-release-please-version +export const VERSION = '3.12.3'; // x-release-please-version From 86dfa4d3ca8490c221f380de480f400a987f1b4c Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 21 Oct 2026 19:02:29 +0000 Subject: [PATCH 177/232] feat(batch): follow only chosen languages in start_url crawls (#2003) Stainless-Generated-From: 6c9424191bdc5d8fdc29806c8f69604f9faa672f --- src/resources/batch.ts | 170 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 4f43bff7..b9b02378 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -174,6 +174,91 @@ export interface CrawlControls { */ follow_subdomains: boolean; + /** + * Languages whose pages were followed: `same_as_start_url` or a list of language + * codes. Null when every language was followed, which is always the case for a + * sitemap crawl. + */ + languages: + | 'same_as_start_url' + | Array< + | 'am' + | 'ar' + | 'az' + | 'be' + | 'bg' + | 'bn' + | 'ca' + | 'ceb' + | 'cs' + | 'cy' + | 'da' + | 'de' + | 'el' + | 'en' + | 'es' + | 'et' + | 'eu' + | 'fa' + | 'fi' + | 'fr' + | 'gu' + | 'ha' + | 'haw' + | 'he' + | 'hi' + | 'hr' + | 'hu' + | 'hy' + | 'id' + | 'is' + | 'it' + | 'ja' + | 'ka' + | 'kk' + | 'kn' + | 'ko' + | 'ku' + | 'ky' + | 'lo' + | 'lt' + | 'lv' + | 'mk' + | 'ml' + | 'mn' + | 'mr' + | 'ms' + | 'ne' + | 'nl' + | 'no' + | 'or' + | 'pa' + | 'pl' + | 'ps' + | 'pt' + | 'ro' + | 'ru' + | 'sk' + | 'sl' + | 'so' + | 'sq' + | 'sr' + | 'sv' + | 'sw' + | 'ta' + | 'te' + | 'th' + | 'tl' + | 'tr' + | 'uk' + | 'ur' + | 'uz' + | 'vi' + | 'yo' + | 'zh' + > + | null; + /** * Link depth limit. Always 0 for a sitemap crawl, which never follows links off * its URLs; null when a `start_url` crawl set no limit. @@ -3721,6 +3806,91 @@ export namespace BatchSubmitParams { */ followSubdomains?: boolean; + /** + * Languages whose pages are followed. `same_as_start_url` follows only the start + * page's language; a list of language codes such as `["en"]` follows those + * languages. Links whose language cannot be determined are followed. When omitted + * all urls are crawled. + */ + languages?: + | 'same_as_start_url' + | Array< + | 'am' + | 'ar' + | 'az' + | 'be' + | 'bg' + | 'bn' + | 'ca' + | 'ceb' + | 'cs' + | 'cy' + | 'da' + | 'de' + | 'el' + | 'en' + | 'es' + | 'et' + | 'eu' + | 'fa' + | 'fi' + | 'fr' + | 'gu' + | 'ha' + | 'haw' + | 'he' + | 'hi' + | 'hr' + | 'hu' + | 'hy' + | 'id' + | 'is' + | 'it' + | 'ja' + | 'ka' + | 'kk' + | 'kn' + | 'ko' + | 'ku' + | 'ky' + | 'lo' + | 'lt' + | 'lv' + | 'mk' + | 'ml' + | 'mn' + | 'mr' + | 'ms' + | 'ne' + | 'nl' + | 'no' + | 'or' + | 'pa' + | 'pl' + | 'ps' + | 'pt' + | 'ro' + | 'ru' + | 'sk' + | 'sl' + | 'so' + | 'sq' + | 'sr' + | 'sv' + | 'sw' + | 'ta' + | 'te' + | 'th' + | 'tl' + | 'tr' + | 'uk' + | 'ur' + | 'uz' + | 'vi' + | 'yo' + | 'zh' + >; + /** * Maximum link depth. Source pages are depth 0. No limit when omitted. */ From 93e1f4f084354e3ef7fcb6d511ea3171a485af4e Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Wed, 21 Oct 2026 21:21:52 +0200 Subject: [PATCH 178/232] release: 3.13.0 (#97) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index f3fe2c8f..6a8e33bb 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.12.3" + ".": "3.13.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index ec352c3f..92504e96 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.13.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.12.3...v3.13.0) (2026-10-21) + + +### Features + +* **batch:** follow only chosen languages in start_url crawls ([#2003](https://github.com/context-dot-dev/context-typescript-sdk/issues/2003)) ([86dfa4d](https://github.com/context-dot-dev/context-typescript-sdk/commit/86dfa4d3ca8490c221f380de480f400a987f1b4c)) + ## [3.12.3](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.12.2...v3.12.3) (2026-10-21) diff --git a/package.json b/package.json index 174e9bce..c7b4e856 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.12.3", + "version": "3.13.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index a5db0bfe..df9d0cdc 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.12.3'; // x-release-please-version +export const VERSION = '3.13.0'; // x-release-please-version From d2084ac777f950c1b3b92c7bc6a17d012759425a Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 21 Oct 2026 20:10:17 +0000 Subject: [PATCH 179/232] feat(scrape): add sourcePreference to choose between HTML conversion and published Markdown (#2010) Stainless-Generated-From: 66ea30a659bb9c46eb22676a7ad4d0a97d628d8e --- src/resources/batch.ts | 42 +++++++++++++++++++++++++----- src/resources/web.ts | 43 ++++++++++++++++++++++++++----- tests/api-resources/batch.test.ts | 1 + tests/api-resources/web.test.ts | 2 ++ 4 files changed, 76 insertions(+), 12 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index b9b02378..ed0e404b 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -3150,20 +3150,35 @@ export namespace BatchSubmitParams { */ export interface MarkdownParams { /** - * Include images in the Markdown using image syntax with URLs and alt text. + * Include images in the Markdown using image syntax with URLs and alt text. Only + * applies to `html-conversion` extractions. */ includeImages?: boolean; /** - * Keep link URLs in the Markdown. Set false to return link text without URLs. + * Keep link URLs in the Markdown. Set false to return link text without URLs. Only + * applies to `html-conversion` extractions. */ includeLinks?: boolean; /** * How base64 images appear: `placeholder` (default) or `preserve`. Requires - * `includeImages`. + * `includeImages`. Only applies to `html-conversion` extractions. */ inlineImages?: 'placeholder' | 'preserve'; + + /** + * Where the Markdown should come from, in order of preference; the first usable + * source wins. `html-conversion` converts the page HTML, and counts as unusable + * when the conversion has almost no content (under 200 characters). + * `markdown-direct` uses the official Markdown version the page publishes through, + * returned as the site serves it. Defaults to + * `["html-conversion", "markdown-direct"]`. With only `markdown-direct`, a page + * that publishes no Markdown fails with `NO_PUBLISHED_MARKDOWN` and is not billed. + * Requests with include or exclude selectors never use `markdown-direct`, so they + * must include `html-conversion`. + */ + sourcePreference?: Array<'html-conversion' | 'markdown-direct'>; } export interface CustomParser { @@ -4006,20 +4021,35 @@ export namespace BatchSubmitParams { */ export interface MarkdownParams { /** - * Include images in the Markdown using image syntax with URLs and alt text. + * Include images in the Markdown using image syntax with URLs and alt text. Only + * applies to `html-conversion` extractions. */ includeImages?: boolean; /** - * Keep link URLs in the Markdown. Set false to return link text without URLs. + * Keep link URLs in the Markdown. Set false to return link text without URLs. Only + * applies to `html-conversion` extractions. */ includeLinks?: boolean; /** * How base64 images appear: `placeholder` (default) or `preserve`. Requires - * `includeImages`. + * `includeImages`. Only applies to `html-conversion` extractions. */ inlineImages?: 'placeholder' | 'preserve'; + + /** + * Where the Markdown should come from, in order of preference; the first usable + * source wins. `html-conversion` converts the page HTML, and counts as unusable + * when the conversion has almost no content (under 200 characters). + * `markdown-direct` uses the official Markdown version the page publishes through, + * returned as the site serves it. Defaults to + * `["html-conversion", "markdown-direct"]`. With only `markdown-direct`, a page + * that publishes no Markdown fails with `NO_PUBLISHED_MARKDOWN` and is not billed. + * Requests with include or exclude selectors never use `markdown-direct`, so they + * must include `html-conversion`. + */ + sourcePreference?: Array<'html-conversion' | 'markdown-direct'>; } export interface CustomParser { diff --git a/src/resources/web.ts b/src/resources/web.ts index ee3b3086..d311c56c 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2549,20 +2549,35 @@ export namespace WebScrapeParams { */ export interface MarkdownParams { /** - * Include images in the Markdown using image syntax with URLs and alt text. + * Include images in the Markdown using image syntax with URLs and alt text. Only + * applies to `html-conversion` extractions. */ includeImages?: boolean; /** - * Keep link URLs in the Markdown. Set false to return link text without URLs. + * Keep link URLs in the Markdown. Set false to return link text without URLs. Only + * applies to `html-conversion` extractions. */ includeLinks?: boolean; /** * How base64 images appear: `placeholder` (default) or `preserve`. Requires - * `includeImages`. + * `includeImages`. Only applies to `html-conversion` extractions. */ inlineImages?: 'placeholder' | 'preserve'; + + /** + * Where the Markdown should come from, in order of preference; the first usable + * source wins. `html-conversion` converts the page HTML, and counts as unusable + * when the conversion has almost no content (under 200 characters). + * `markdown-direct` uses the official Markdown version the page publishes through, + * returned as the site serves it. Defaults to + * `["html-conversion", "markdown-direct"]`. With only `markdown-direct`, a page + * that publishes no Markdown fails with `NO_PUBLISHED_MARKDOWN` and is not billed. + * Requests with include or exclude selectors never use `markdown-direct`, so they + * must include `html-conversion`. + */ + sourcePreference?: Array<'html-conversion' | 'markdown-direct'>; } export interface CustomParser { @@ -4140,12 +4155,14 @@ export interface WebWebCrawlMdParams { includeFrames?: boolean; /** - * Include image references in the Markdown output + * Include image references in the Markdown output Only applies to + * `html-conversion` extractions. */ includeImages?: boolean; /** - * Preserve hyperlinks in the Markdown output + * Preserve hyperlinks in the Markdown output Only applies to `html-conversion` + * extractions. */ includeLinks?: boolean; @@ -4181,10 +4198,24 @@ export interface WebWebCrawlMdParams { settleAnimations?: boolean; /** - * Truncate base64-encoded image data in the Markdown output + * Truncate base64-encoded image data in the Markdown output Only applies to + * `html-conversion` extractions. */ shortenBase64Images?: boolean; + /** + * Where the Markdown should come from, in order of preference; the first usable + * source wins. `html-conversion` converts the page HTML, and counts as unusable + * when the conversion has almost no content (under 200 characters). + * `markdown-direct` uses the official Markdown version the page publishes through, + * returned as the site serves it. Defaults to + * `["html-conversion", "markdown-direct"]`. With only `markdown-direct`, a page + * that publishes no Markdown fails with `NO_PUBLISHED_MARKDOWN` and is not billed. + * Requests with include or exclude selectors never use `markdown-direct`, so they + * must include `html-conversion`. + */ + sourcePreference?: Array<'html-conversion' | 'markdown-direct'>; + /** * Soft crawl deadline in milliseconds. Returns pages collected before the next * deadline check. diff --git a/tests/api-resources/batch.test.ts b/tests/api-resources/batch.test.ts index b8036553..710ef783 100644 --- a/tests/api-resources/batch.test.ts +++ b/tests/api-resources/batch.test.ts @@ -165,6 +165,7 @@ describe('resource batch', () => { includeImages: true, includeLinks: true, inlineImages: 'placeholder', + sourcePreference: ['html-conversion'], }, maxAgeMs: 0, parseParams: { diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index ca0625f6..a93b94ef 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -162,6 +162,7 @@ describe('resource web', () => { includeImages: true, includeLinks: true, inlineImages: 'placeholder', + sourcePreference: ['html-conversion'], }, maxAgeMs: 0, parseParams: { @@ -328,6 +329,7 @@ describe('resource web', () => { }, settleAnimations: true, shortenBase64Images: true, + sourcePreference: ['html-conversion'], stopAfterMs: 10000, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, From 3e1919b89609c92bf36991b662f7b99692c37679 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Wed, 21 Oct 2026 22:25:13 +0200 Subject: [PATCH 180/232] release: 3.14.0 (#98) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 6a8e33bb..6060e604 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.13.0" + ".": "3.14.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 92504e96..1d2d16cf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.14.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.13.0...v3.14.0) (2026-10-21) + + +### Features + +* **scrape:** add sourcePreference to choose between HTML conversion and published Markdown ([#2010](https://github.com/context-dot-dev/context-typescript-sdk/issues/2010)) ([d2084ac](https://github.com/context-dot-dev/context-typescript-sdk/commit/d2084ac777f950c1b3b92c7bc6a17d012759425a)) + ## [3.13.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.12.3...v3.13.0) (2026-10-21) diff --git a/package.json b/package.json index c7b4e856..d6e31544 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.13.0", + "version": "3.14.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index df9d0cdc..aa28658a 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.13.0'; // x-release-please-version +export const VERSION = '3.14.0'; // x-release-please-version From 28f76b70ff490c29e44c80ce078cd026f0256998 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 21 Oct 2026 21:02:38 +0000 Subject: [PATCH 181/232] docs(openapi): unify regex wording and shorten sourcePreference descriptions (#2051) Stainless-Generated-From: bda1f72b69aa9c2868534e117b510beb8b8d3cb2 --- src/resources/batch.ts | 62 +++++++++++++----------------------------- src/resources/web.ts | 53 ++++++++++++------------------------ 2 files changed, 36 insertions(+), 79 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index ed0e404b..d32f04a9 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -165,7 +165,7 @@ export interface Failure { */ export interface CrawlControls { /** - * RE2 pattern URLs must not match to be crawled. Null when the crawl set none. + * Regex pattern URLs must not match to be crawled. Null when the crawl set none. */ exclude_url_pattern: string | null; @@ -175,9 +175,7 @@ export interface CrawlControls { follow_subdomains: boolean; /** - * Languages whose pages were followed: `same_as_start_url` or a list of language - * codes. Null when every language was followed, which is always the case for a - * sitemap crawl. + * Languages whose pages were followed; null when all languages were. */ languages: | 'same_as_start_url' @@ -277,7 +275,7 @@ export interface CrawlControls { source: CrawlControls.StartURL | CrawlControls.Sitemap; /** - * RE2 pattern URLs had to match to be crawled. Null when the crawl set none. + * Regex pattern URLs had to match to be crawled. Null when the crawl set none. */ url_pattern: string | null; } @@ -3150,33 +3148,23 @@ export namespace BatchSubmitParams { */ export interface MarkdownParams { /** - * Include images in the Markdown using image syntax with URLs and alt text. Only - * applies to `html-conversion` extractions. + * Include images in the Markdown (`html-conversion` only). */ includeImages?: boolean; /** - * Keep link URLs in the Markdown. Set false to return link text without URLs. Only - * applies to `html-conversion` extractions. + * Keep link URLs in the Markdown (`html-conversion` only). */ includeLinks?: boolean; /** - * How base64 images appear: `placeholder` (default) or `preserve`. Requires - * `includeImages`. Only applies to `html-conversion` extractions. + * How base64 images appear when `includeImages` is set (`html-conversion` only). */ inlineImages?: 'placeholder' | 'preserve'; /** - * Where the Markdown should come from, in order of preference; the first usable - * source wins. `html-conversion` converts the page HTML, and counts as unusable - * when the conversion has almost no content (under 200 characters). - * `markdown-direct` uses the official Markdown version the page publishes through, - * returned as the site serves it. Defaults to - * `["html-conversion", "markdown-direct"]`. With only `markdown-direct`, a page - * that publishes no Markdown fails with `NO_PUBLISHED_MARKDOWN` and is not billed. - * Requests with include or exclude selectors never use `markdown-direct`, so they - * must include `html-conversion`. + * Markdown sources in order of preference: `html-conversion` converts the page + * HTML, `markdown-direct` uses Markdown the site publishes. */ sourcePreference?: Array<'html-conversion' | 'markdown-direct'>; } @@ -3811,7 +3799,7 @@ export namespace BatchSubmitParams { */ export interface Controls { /** - * RE2 pattern for URLs to exclude, even when they match `regex`. The `start_url` + * Regex pattern for URLs to exclude, even when they match `regex`. The `start_url` * itself is always included. */ excludeRegex?: string; @@ -3822,10 +3810,8 @@ export namespace BatchSubmitParams { followSubdomains?: boolean; /** - * Languages whose pages are followed. `same_as_start_url` follows only the start - * page's language; a list of language codes such as `["en"]` follows those - * languages. Links whose language cannot be determined are followed. When omitted - * all urls are crawled. + * Only follow pages in these languages, or `same_as_start_url`; all languages when + * omitted. */ languages?: | 'same_as_start_url' @@ -3917,7 +3903,7 @@ export namespace BatchSubmitParams { maxUrls?: number; /** - * RE2 pattern for URLs to include. The `start_url` itself is always included. + * Regex pattern for URLs to include. The `start_url` itself is always included. */ regex?: string; } @@ -3953,7 +3939,7 @@ export namespace BatchSubmitParams { */ export interface Controls { /** - * RE2 pattern; sitemap URLs matching it are not scraped, even when they match + * Regex pattern; sitemap URLs matching it are not scraped, even when they match * `regex`. */ excludeRegex?: string; @@ -3964,7 +3950,7 @@ export namespace BatchSubmitParams { maxUrls?: number; /** - * RE2 pattern; only sitemap URLs matching it are scraped. + * Regex pattern; only sitemap URLs matching it are scraped. */ regex?: string; } @@ -4021,33 +4007,23 @@ export namespace BatchSubmitParams { */ export interface MarkdownParams { /** - * Include images in the Markdown using image syntax with URLs and alt text. Only - * applies to `html-conversion` extractions. + * Include images in the Markdown (`html-conversion` only). */ includeImages?: boolean; /** - * Keep link URLs in the Markdown. Set false to return link text without URLs. Only - * applies to `html-conversion` extractions. + * Keep link URLs in the Markdown (`html-conversion` only). */ includeLinks?: boolean; /** - * How base64 images appear: `placeholder` (default) or `preserve`. Requires - * `includeImages`. Only applies to `html-conversion` extractions. + * How base64 images appear when `includeImages` is set (`html-conversion` only). */ inlineImages?: 'placeholder' | 'preserve'; /** - * Where the Markdown should come from, in order of preference; the first usable - * source wins. `html-conversion` converts the page HTML, and counts as unusable - * when the conversion has almost no content (under 200 characters). - * `markdown-direct` uses the official Markdown version the page publishes through, - * returned as the site serves it. Defaults to - * `["html-conversion", "markdown-direct"]`. With only `markdown-direct`, a page - * that publishes no Markdown fails with `NO_PUBLISHED_MARKDOWN` and is not billed. - * Requests with include or exclude selectors never use `markdown-direct`, so they - * must include `html-conversion`. + * Markdown sources in order of preference: `html-conversion` converts the page + * HTML, `markdown-direct` uses Markdown the site publishes. */ sourcePreference?: Array<'html-conversion' | 'markdown-direct'>; } diff --git a/src/resources/web.ts b/src/resources/web.ts index d311c56c..aa8082b2 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2301,8 +2301,8 @@ export interface WebMapURLsParams { domain: string; /** - * Optional RE2-compatible regex pattern. URLs matching this pattern are not - * returned, even when they match urlRegex. + * Regex pattern. URLs matching this pattern are not returned, even when they match + * urlRegex. */ excludeUrlRegex?: string; @@ -2343,8 +2343,8 @@ export interface WebMapURLsParams { timeoutOpts?: WebMapURLsParams.TimeoutOpts; /** - * Optional RE2-compatible regex pattern. Only URLs matching this pattern are - * returned and counted against maxLinks. + * Regex pattern. Only URLs matching this pattern are returned and counted against + * maxLinks. */ urlRegex?: string; @@ -2549,33 +2549,23 @@ export namespace WebScrapeParams { */ export interface MarkdownParams { /** - * Include images in the Markdown using image syntax with URLs and alt text. Only - * applies to `html-conversion` extractions. + * Include images in the Markdown (`html-conversion` only). */ includeImages?: boolean; /** - * Keep link URLs in the Markdown. Set false to return link text without URLs. Only - * applies to `html-conversion` extractions. + * Keep link URLs in the Markdown (`html-conversion` only). */ includeLinks?: boolean; /** - * How base64 images appear: `placeholder` (default) or `preserve`. Requires - * `includeImages`. Only applies to `html-conversion` extractions. + * How base64 images appear when `includeImages` is set (`html-conversion` only). */ inlineImages?: 'placeholder' | 'preserve'; /** - * Where the Markdown should come from, in order of preference; the first usable - * source wins. `html-conversion` converts the page HTML, and counts as unusable - * when the conversion has almost no content (under 200 characters). - * `markdown-direct` uses the official Markdown version the page publishes through, - * returned as the site serves it. Defaults to - * `["html-conversion", "markdown-direct"]`. With only `markdown-direct`, a page - * that publishes no Markdown fails with `NO_PUBLISHED_MARKDOWN` and is not billed. - * Requests with include or exclude selectors never use `markdown-direct`, so they - * must include `html-conversion`. + * Markdown sources in order of preference: `html-conversion` converts the page + * HTML, `markdown-direct` uses Markdown the site publishes. */ sourcePreference?: Array<'html-conversion' | 'markdown-direct'>; } @@ -4136,8 +4126,8 @@ export interface WebWebCrawlMdParams { excludeSelectors?: Array | null; /** - * RE2 regex pattern. URLs matching this pattern are never followed or scraped, - * even when they match urlRegex. The starting URL is always scraped. + * Regex pattern. URLs matching this pattern are never followed or scraped, even + * when they match urlRegex. The starting URL is always scraped. */ excludeUrlRegex?: string; @@ -4155,14 +4145,12 @@ export interface WebWebCrawlMdParams { includeFrames?: boolean; /** - * Include image references in the Markdown output Only applies to - * `html-conversion` extractions. + * Include image references in the Markdown output (`html-conversion` only). */ includeImages?: boolean; /** - * Preserve hyperlinks in the Markdown output Only applies to `html-conversion` - * extractions. + * Preserve hyperlinks in the Markdown output (`html-conversion` only). */ includeLinks?: boolean; @@ -4198,21 +4186,14 @@ export interface WebWebCrawlMdParams { settleAnimations?: boolean; /** - * Truncate base64-encoded image data in the Markdown output Only applies to - * `html-conversion` extractions. + * Truncate base64-encoded image data in the Markdown output (`html-conversion` + * only). */ shortenBase64Images?: boolean; /** - * Where the Markdown should come from, in order of preference; the first usable - * source wins. `html-conversion` converts the page HTML, and counts as unusable - * when the conversion has almost no content (under 200 characters). - * `markdown-direct` uses the official Markdown version the page publishes through, - * returned as the site serves it. Defaults to - * `["html-conversion", "markdown-direct"]`. With only `markdown-direct`, a page - * that publishes no Markdown fails with `NO_PUBLISHED_MARKDOWN` and is not billed. - * Requests with include or exclude selectors never use `markdown-direct`, so they - * must include `html-conversion`. + * Markdown sources in order of preference: `html-conversion` converts the page + * HTML, `markdown-direct` uses Markdown the site publishes. */ sourcePreference?: Array<'html-conversion' | 'markdown-direct'>; From 560cde9a233eec942325b956f8dba15a38b9b0ba Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Wed, 21 Oct 2026 23:23:39 +0200 Subject: [PATCH 182/232] release: 3.14.1 (#99) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 6060e604..60bb6868 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.14.0" + ".": "3.14.1" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d2d16cf..92d2d8be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.14.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.14.0...v3.14.1) (2026-10-21) + + +### Documentation + +* **openapi:** unify regex wording and shorten sourcePreference descriptions ([#2051](https://github.com/context-dot-dev/context-typescript-sdk/issues/2051)) ([28f76b7](https://github.com/context-dot-dev/context-typescript-sdk/commit/28f76b70ff490c29e44c80ce078cd026f0256998)) + ## [3.14.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.13.0...v3.14.0) (2026-10-21) diff --git a/package.json b/package.json index d6e31544..2c16955f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.14.0", + "version": "3.14.1", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index aa28658a..768675de 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.14.0'; // x-release-please-version +export const VERSION = '3.14.1'; // x-release-please-version From 02285374860c2548591d3fe0abd76c2033671aca Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 23 Oct 2026 07:46:57 +0000 Subject: [PATCH 183/232] feat(people): publish people search in the API specification (#2094) Stainless-Generated-From: 359da51f974abed8824e221f27da8d64e0618d1a --- .stats.yml | 2 +- api.md | 2 + src/client.ts | 10 +- src/resources/index.ts | 8 +- src/resources/people.ts | 224 ++++++++++++++++++++++++++++- tests/api-resources/people.test.ts | 26 ++++ 6 files changed, 268 insertions(+), 4 deletions(-) diff --git a/.stats.yml b/.stats.yml index c7c071bd..364b6123 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 45 +configured_endpoints: 46 diff --git a/api.md b/api.md index a00558e2..c717263b 100644 --- a/api.md +++ b/api.md @@ -159,10 +159,12 @@ Methods: Types: - PersonEnrichResponse +- PersonSearchResponse Methods: - client.people.enrich({ ...params }) -> PersonEnrichResponse +- client.people.search({ ...params }) -> PersonSearchResponse # News diff --git a/src/client.ts b/src/client.ts index 05af2c84..4461a79d 100644 --- a/src/client.ts +++ b/src/client.ts @@ -79,7 +79,13 @@ import { } from './resources/monitors'; import { News, NewsSearchParams, NewsSearchResponse } from './resources/news'; import { Parse, ParseHandleParams, ParseHandleResponse } from './resources/parse'; -import { People, PersonEnrichParams, PersonEnrichResponse } from './resources/people'; +import { + People, + PersonEnrichParams, + PersonEnrichResponse, + PersonSearchParams, + PersonSearchResponse, +} from './resources/people'; import { Utility, UtilityPrefetchParams, UtilityPrefetchResponse } from './resources/utility'; import { Web, @@ -965,7 +971,9 @@ export declare namespace ContextDev { export { People as People, type PersonEnrichResponse as PersonEnrichResponse, + type PersonSearchResponse as PersonSearchResponse, type PersonEnrichParams as PersonEnrichParams, + type PersonSearchParams as PersonSearchParams, }; export { diff --git a/src/resources/index.ts b/src/resources/index.ts index 8b696005..3f10e7e0 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -63,7 +63,13 @@ export { } from './monitors'; export { News, type NewsSearchResponse, type NewsSearchParams } from './news'; export { Parse, type ParseHandleResponse, type ParseHandleParams } from './parse'; -export { People, type PersonEnrichResponse, type PersonEnrichParams } from './people'; +export { + People, + type PersonEnrichResponse, + type PersonSearchResponse, + type PersonEnrichParams, + type PersonSearchParams, +} from './people'; export { Utility, type UtilityPrefetchResponse, type UtilityPrefetchParams } from './utility'; export { Web, diff --git a/src/resources/people.ts b/src/resources/people.ts index bd48e313..ab94ec61 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -26,6 +26,20 @@ export class People extends APIResource { enrich(body: PersonEnrichParams, options?: RequestOptions): APIPromise { return this._client.post('/people/enrich', { body, ...options }); } + + /** + * Find people with a natural-language query. + * + * @example + * ```ts + * const response = await client.people.search({ + * query: 'VPs of sales at solar companies in California', + * }); + * ``` + */ + search(body: PersonSearchParams, options?: RequestOptions): APIPromise { + return this._client.post('/people/search', { body, ...options }); + } } export interface PersonEnrichResponse { @@ -278,6 +292,165 @@ export namespace PersonEnrichResponse { } } +export interface PersonSearchResponse { + /** + * Unique ID of this request, also in `X-Request-Id`. Include it when contacting + * support. + */ + request_id: string; + + /** + * Up to 10 matching people, most relevant first. + */ + results: Array; + + /** + * Credits this request used and your remaining balance. + */ + key_metadata?: PersonSearchResponse.KeyMetadata; + + /** + * Pass as cursor to fetch the next page; null when there are no more results. + */ + next_cursor?: string | null; +} + +export namespace PersonSearchResponse { + /** + * A person matching your search; unavailable details are null or empty lists. + */ + export interface Result { + /** + * What the person does. + */ + description: string | null; + + /** + * Whether the person is currently a founder or co-founder. + */ + is_founder: boolean | null; + + /** + * Where the person lives. + */ + location: Result.Location; + + /** + * Full name. + */ + name: string | null; + + /** + * Public professional profile URLs. + */ + profiles: Array; + + /** + * The person’s current role. + */ + role: Result.Role; + + /** + * Schools attended. + */ + schools: Array; + + /** + * Professional skills. + */ + skills: Array; + + /** + * Years of professional experience. + */ + years_of_experience: number | null; + } + + export namespace Result { + /** + * Where the person lives. + */ + export interface Location { + /** + * City. + */ + city: string | null; + + /** + * Country as a two-letter code, such as US or GB. + */ + country_code: string | null; + + /** + * State or region. + */ + region: string | null; + } + + /** + * The person’s current role. + */ + export interface Role { + /** + * Current employer, when known. + */ + company: Role.Company | null; + + /** + * Areas of responsibility. + */ + functions: Array; + + /** + * Seniority level. + */ + seniority: string | null; + + /** + * Role start date (YYYY-MM-DD). + */ + started_on: string | null; + + /** + * Job title. + */ + title: string | null; + } + + export namespace Role { + /** + * Current employer, when known. + */ + export interface Company { + /** + * The company’s website domain. + */ + domain: string | null; + + /** + * Company name. + */ + name: string | null; + } + } + } + + /** + * Credits this request used and your remaining balance. + */ + export interface KeyMetadata { + /** + * Credits charged for this request. + */ + credits_consumed: number; + + /** + * Credits remaining for your organization. + */ + credits_remaining: number; + } +} + export interface PersonEnrichParams { /** * Company context to help identify the person. Provide a name or domain. @@ -438,6 +611,55 @@ export namespace PersonEnrichParams { } } +export interface PersonSearchParams { + /** + * Describe the people to find. + */ + query: string; + + /** + * Use next_cursor with the same query and filters to fetch the next page. + */ + cursor?: string; + + /** + * Additional constraints every result must match. + */ + filters?: PersonSearchParams.Filters; + + /** + * Labels for filtering usage in the dashboard. + */ + tags?: Array; +} + +export namespace PersonSearchParams { + /** + * Additional constraints every result must match. + */ + export interface Filters { + /** + * Countries people live in as two-letter codes, such as US or GB. + */ + countries?: Array; + + /** + * Maximum years of professional experience. + */ + years_of_experience_max?: number; + + /** + * Minimum years of professional experience. + */ + years_of_experience_min?: number; + } +} + export declare namespace People { - export { type PersonEnrichResponse as PersonEnrichResponse, type PersonEnrichParams as PersonEnrichParams }; + export { + type PersonEnrichResponse as PersonEnrichResponse, + type PersonSearchResponse as PersonSearchResponse, + type PersonEnrichParams as PersonEnrichParams, + type PersonSearchParams as PersonSearchParams, + }; } diff --git a/tests/api-resources/people.test.ts b/tests/api-resources/people.test.ts index ecb969f7..b02a8748 100644 --- a/tests/api-resources/people.test.ts +++ b/tests/api-resources/people.test.ts @@ -19,4 +19,30 @@ describe('resource people', () => { expect(dataAndResponse.data).toBe(response); expect(dataAndResponse.response).toBe(rawResponse); }); + + // Mock server tests are disabled + test.skip('search: only required params', async () => { + const responsePromise = client.people.search({ query: 'VPs of sales at solar companies in California' }); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('search: required and optional params', async () => { + const response = await client.people.search({ + query: 'VPs of sales at solar companies in California', + cursor: 'cursor', + filters: { + countries: ['SE'], + years_of_experience_max: 0, + years_of_experience_min: 0, + }, + tags: ['production', 'team-alpha'], + }); + }); }); From 2db37951240d47d5773464c5e9ae40bcac074b7c Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Fri, 23 Oct 2026 09:52:16 +0200 Subject: [PATCH 184/232] release: 3.15.0 (#100) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 60bb6868..9c10c70f 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.14.1" + ".": "3.15.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 92d2d8be..faf07183 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.15.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.14.1...v3.15.0) (2026-10-23) + + +### Features + +* **people:** publish people search in the API specification ([#2094](https://github.com/context-dot-dev/context-typescript-sdk/issues/2094)) ([0228537](https://github.com/context-dot-dev/context-typescript-sdk/commit/02285374860c2548591d3fe0abd76c2033671aca)) + ## [3.14.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.14.0...v3.14.1) (2026-10-21) diff --git a/package.json b/package.json index 2c16955f..1d744ea5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.14.1", + "version": "3.15.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 768675de..888b16f2 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.14.1'; // x-release-please-version +export const VERSION = '3.15.0'; // x-release-please-version From 87349d2037f4973e4b2b4579c5c3b83daa1ebb5a Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 27 Oct 2026 10:16:54 +0000 Subject: [PATCH 185/232] feat(api): serve a public OpenAPI spec and generate the SDKs from it (#2075) Stainless-Generated-From: 03c217a97d5a27b82eebfdf753ec86bd145d7f39 --- src/resources/industry.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/resources/industry.ts b/src/resources/industry.ts index a82ba60d..5100d4d7 100644 --- a/src/resources/industry.ts +++ b/src/resources/industry.ts @@ -7,6 +7,8 @@ import { RequestOptions } from '../internal/request-options'; export class Industry extends APIResource { /** * Classify a company into NAICS industry codes. + * + * @deprecated */ retrieveNaics( query: IndustryRetrieveNaicsParams, @@ -17,6 +19,8 @@ export class Industry extends APIResource { /** * Classify a company into SIC industry codes. + * + * @deprecated */ retrieveSic( query: IndustryRetrieveSicParams, From 09ed28d466b8e283fce57497491e818333b6cd3e Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Tue, 27 Oct 2026 11:27:02 +0100 Subject: [PATCH 186/232] release: 3.16.0 (#101) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 9c10c70f..1a1f3484 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.15.0" + ".": "3.16.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index faf07183..d5cf259f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.16.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.15.0...v3.16.0) (2026-10-27) + + +### Features + +* **api:** serve a public OpenAPI spec and generate the SDKs from it ([#2075](https://github.com/context-dot-dev/context-typescript-sdk/issues/2075)) ([87349d2](https://github.com/context-dot-dev/context-typescript-sdk/commit/87349d2037f4973e4b2b4579c5c3b83daa1ebb5a)) + ## [3.15.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.14.1...v3.15.0) (2026-10-23) diff --git a/package.json b/package.json index 1d744ea5..72daf534 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.15.0", + "version": "3.16.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 888b16f2..441b8462 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.15.0'; // x-release-please-version +export const VERSION = '3.16.0'; // x-release-please-version From cca07576fc137e45bf0ccfd638479dcb4f251cb4 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 27 Oct 2026 15:35:00 +0000 Subject: [PATCH 187/232] feat(people): add ultra mode to people search (#2149) Stainless-Generated-From: ce27143402e16de9feef95b76091dee0cd950cbe --- src/resources/people.ts | 27 +++++++++++++++++++++++++-- tests/api-resources/people.test.ts | 1 + 2 files changed, 26 insertions(+), 2 deletions(-) diff --git a/src/resources/people.ts b/src/resources/people.ts index ab94ec61..c90d0147 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -364,6 +364,11 @@ export namespace PersonSearchResponse { * Years of professional experience. */ years_of_experience: number | null; + + /** + * How well the person matches the query. Only returned in `ultra` mode. + */ + match?: Result.Match; } export namespace Result { @@ -433,6 +438,16 @@ export namespace PersonSearchResponse { name: string | null; } } + + /** + * How well the person matches the query. Only returned in `ultra` mode. + */ + export interface Match { + /** + * How well the person matches the query, from 0 to 1. + */ + confidence: number; + } } /** @@ -613,12 +628,13 @@ export namespace PersonEnrichParams { export interface PersonSearchParams { /** - * Describe the people to find. + * Describe the people to find. Up to 500 characters in `fast` mode and 5000 in + * `ultra` mode. */ query: string; /** - * Use next_cursor with the same query and filters to fetch the next page. + * Use next_cursor with the same query, mode and filters to fetch the next page. */ cursor?: string; @@ -627,6 +643,13 @@ export interface PersonSearchParams { */ filters?: PersonSearchParams.Filters; + /** + * `fast` matches people on basic criteria (e.g. their role, location or + * background); `ultra` plans a deeper search, judges each candidate against every + * criterion in the query and explains each match. + */ + mode?: 'fast' | 'ultra'; + /** * Labels for filtering usage in the dashboard. */ diff --git a/tests/api-resources/people.test.ts b/tests/api-resources/people.test.ts index b02a8748..4f9d2737 100644 --- a/tests/api-resources/people.test.ts +++ b/tests/api-resources/people.test.ts @@ -42,6 +42,7 @@ describe('resource people', () => { years_of_experience_max: 0, years_of_experience_min: 0, }, + mode: 'fast', tags: ['production', 'team-alpha'], }); }); From b941ad003a4ea1772ed398345a19f4d4dc5263d0 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Tue, 27 Oct 2026 16:45:20 +0100 Subject: [PATCH 188/232] release: 3.17.0 (#102) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 1a1f3484..a2914e52 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.16.0" + ".": "3.17.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index d5cf259f..86c8d85c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.17.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.16.0...v3.17.0) (2026-10-27) + + +### Features + +* **people:** add ultra mode to people search ([#2149](https://github.com/context-dot-dev/context-typescript-sdk/issues/2149)) ([cca0757](https://github.com/context-dot-dev/context-typescript-sdk/commit/cca07576fc137e45bf0ccfd638479dcb4f251cb4)) + ## [3.16.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.15.0...v3.16.0) (2026-10-27) diff --git a/package.json b/package.json index 72daf534..bc0d6a91 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.16.0", + "version": "3.17.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 441b8462..4a48e2d6 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.16.0'; // x-release-please-version +export const VERSION = '3.17.0'; // x-release-please-version From 3b35d9a754e095d206804bcf0bfe3cb97dffd81a Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 27 Oct 2026 21:34:15 +0000 Subject: [PATCH 189/232] docs(people): note that complex ultra people searches can take up to 60 seconds (#2206) Stainless-Generated-From: b2b63a76ff958ba916b7e5ecf562d64a09b03e04 --- src/resources/people.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/resources/people.ts b/src/resources/people.ts index c90d0147..2fd483c8 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -646,7 +646,8 @@ export interface PersonSearchParams { /** * `fast` matches people on basic criteria (e.g. their role, location or * background); `ultra` plans a deeper search, judges each candidate against every - * criterion in the query and explains each match. + * criterion in the query. Complex `ultra` searches can take up to 60 seconds to + * complete, so allow for that in your client timeout. */ mode?: 'fast' | 'ultra'; From d12d46b9f339583b55c2b2e9524771f160962598 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Tue, 27 Oct 2026 22:47:16 +0100 Subject: [PATCH 190/232] release: 3.17.1 (#103) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index a2914e52..a3d1f01f 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.17.0" + ".": "3.17.1" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 86c8d85c..526fa442 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.17.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.17.0...v3.17.1) (2026-10-27) + + +### Documentation + +* **people:** note that complex ultra people searches can take up to 60 seconds ([#2206](https://github.com/context-dot-dev/context-typescript-sdk/issues/2206)) ([3b35d9a](https://github.com/context-dot-dev/context-typescript-sdk/commit/3b35d9a754e095d206804bcf0bfe3cb97dffd81a)) + ## [3.17.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.16.0...v3.17.0) (2026-10-27) diff --git a/package.json b/package.json index bc0d6a91..ae5e9fb3 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.17.0", + "version": "3.17.1", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 4a48e2d6..26765409 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.17.0'; // x-release-please-version +export const VERSION = '3.17.1'; // x-release-please-version From 6a3658407f1b0c9f4a4cdf520f305d9149b01d1d Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 27 Oct 2026 22:01:48 +0000 Subject: [PATCH 191/232] fix(people): split ultra people ranking on its strongest phrase signals (#2209) Stainless-Generated-From: f32da8110804511505a5bb5a78fe6eb2cfd5f734 --- src/resources/people.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/resources/people.ts b/src/resources/people.ts index 2fd483c8..416f7785 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -646,7 +646,7 @@ export interface PersonSearchParams { /** * `fast` matches people on basic criteria (e.g. their role, location or * background); `ultra` plans a deeper search, judges each candidate against every - * criterion in the query. Complex `ultra` searches can take up to 60 seconds to + * criterion in the query. Complex `ultra` searches can take up to 30 seconds to * complete, so allow for that in your client timeout. */ mode?: 'fast' | 'ultra'; From eb1e97f29ca78b86611f808632e264cac59c0e53 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 27 Oct 2026 22:27:17 +0000 Subject: [PATCH 192/232] feat(parse): mark PDF page numbers inline in Markdown with includeNumberedPages (#2110) Stainless-Generated-From: 1000c731f07b2c81d737594d334b22e1f9d7ac5f --- src/resources/batch.ts | 12 ++++++++++++ src/resources/parse.ts | 8 ++++++++ src/resources/web.ts | 6 ++++++ tests/api-resources/batch.test.ts | 1 + tests/api-resources/web.test.ts | 1 + 5 files changed, 28 insertions(+) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index d32f04a9..cc128c6e 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -3544,6 +3544,12 @@ export namespace BatchSubmitParams { */ endPage?: number; + /** + * Start each page in the Markdown with a `` line using its original + * 1-based page number; these responses are never served from cache. + */ + includeNumberedPages?: boolean; + /** * Set `auto` to read scanned pages with OCR. */ @@ -4403,6 +4409,12 @@ export namespace BatchSubmitParams { */ endPage?: number; + /** + * Start each page in the Markdown with a `` line using its original + * 1-based page number; these responses are never served from cache. + */ + includeNumberedPages?: boolean; + /** * Set `auto` to read scanned pages with OCR. */ diff --git a/src/resources/parse.ts b/src/resources/parse.ts index 0a48c26b..09ef1142 100644 --- a/src/resources/parse.ts +++ b/src/resources/parse.ts @@ -20,6 +20,7 @@ export class Parse extends APIResource { extension, includeImages, includeLinks, + includeNumberedPages, ocr, pdf, shortenBase64Images, @@ -34,6 +35,7 @@ export class Parse extends APIResource { extension, includeImages, includeLinks, + includeNumberedPages, ocr, pdf, shortenBase64Images, @@ -225,6 +227,12 @@ export interface ParseHandleParams { */ includeLinks?: boolean; + /** + * Query param: Start each PDF page in the Markdown with a `` line, + * where N is the original 1-based page number. + */ + includeNumberedPages?: boolean; + /** * Query param: Read text from images and scanned PDF pages. PDF page ranges still * apply. diff --git a/src/resources/web.ts b/src/resources/web.ts index aa8082b2..781f3829 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2943,6 +2943,12 @@ export namespace WebScrapeParams { */ endPage?: number; + /** + * Start each page in the Markdown with a `` line using its original + * 1-based page number; these responses are never served from cache. + */ + includeNumberedPages?: boolean; + /** * Set `auto` to read scanned pages with OCR. */ diff --git a/tests/api-resources/batch.test.ts b/tests/api-resources/batch.test.ts index 710ef783..d3f02f97 100644 --- a/tests/api-resources/batch.test.ts +++ b/tests/api-resources/batch.test.ts @@ -194,6 +194,7 @@ describe('resource batch', () => { parsers: { pdf: { endPage: 1, + includeNumberedPages: true, ocr: 'off', startPage: 1, }, diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index a93b94ef..d934566e 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -191,6 +191,7 @@ describe('resource web', () => { parsers: { pdf: { endPage: 1, + includeNumberedPages: true, ocr: 'off', startPage: 1, }, From 1e544cd098648874170bef988e7e521a29e9e12d Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Tue, 27 Oct 2026 23:32:38 +0100 Subject: [PATCH 193/232] release: 3.18.0 (#104) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 12 ++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 15 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index a3d1f01f..da0b97f9 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.17.1" + ".": "3.18.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 526fa442..e37e7875 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## [3.18.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.17.1...v3.18.0) (2026-10-27) + + +### Features + +* **parse:** mark PDF page numbers inline in Markdown with includeNumberedPages ([#2110](https://github.com/context-dot-dev/context-typescript-sdk/issues/2110)) ([eb1e97f](https://github.com/context-dot-dev/context-typescript-sdk/commit/eb1e97f29ca78b86611f808632e264cac59c0e53)) + + +### Bug Fixes + +* **people:** split ultra people ranking on its strongest phrase signals ([#2209](https://github.com/context-dot-dev/context-typescript-sdk/issues/2209)) ([6a36584](https://github.com/context-dot-dev/context-typescript-sdk/commit/6a3658407f1b0c9f4a4cdf520f305d9149b01d1d)) + ## [3.17.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.17.0...v3.17.1) (2026-10-27) diff --git a/package.json b/package.json index ae5e9fb3..5a6b13b8 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.17.1", + "version": "3.18.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 26765409..ccc7dec5 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.17.1'; // x-release-please-version +export const VERSION = '3.18.0'; // x-release-please-version From 1bd3e5ca3bebc1a079701c5b8c322a62b6361127 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 28 Oct 2026 14:10:31 +0000 Subject: [PATCH 194/232] fix(openapi): keep legacy batch inputs in the spec as deprecated (#2225) Stainless-Generated-From: 3fa6bfb8496896be80aaf72216e27bdc20013727 --- src/resources/batch.ts | 1730 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 1698 insertions(+), 32 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index cc128c6e..7171e66e 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -2934,10 +2934,9 @@ export namespace BatchSubmitParams { */ export interface Scrape { /** - * Use the same formats and parameters as POST /web/scrape, replacing url with - * urls. Options apply to every page. + * Pages to scrape and their output format. */ - data: Scrape.Data; + data: Scrape.Markdown | Scrape.HTML | Scrape.BatchUnifiedScrapeData; /** * Scrape the pages in `data.urls`. @@ -2946,40 +2945,712 @@ export namespace BatchSubmitParams { } export namespace Scrape { + /** + * @deprecated Scrape the listed pages as Markdown. + */ + export interface Markdown { + /** + * Return page content as Markdown. + */ + format: 'markdown'; + + /** + * Pages to scrape. Maximum 100000. + */ + urls: Array; + + /** + * Options for Markdown output. + */ + options?: Markdown.Options; + } + + export namespace Markdown { + /** + * A page to scrape, with optional data for matching results. + */ + export interface URL { + /** + * Page URL to scrape. + */ + url: string; + + /** + * Your ID for this page, returned with its result. The same URL can use different + * IDs. + */ + itemId?: string; + + /** + * Custom JSON returned unchanged with this page result. + */ + meta?: { [key: string]: unknown }; + } + + /** + * Options for Markdown output. + */ + export interface Options { + /** + * Fetch from this country (ISO 3166-1 alpha-2). + */ + country?: + | 'ad' + | 'ae' + | 'af' + | 'ag' + | 'ai' + | 'al' + | 'am' + | 'ao' + | 'ar' + | 'at' + | 'au' + | 'aw' + | 'az' + | 'ba' + | 'bb' + | 'bd' + | 'be' + | 'bf' + | 'bg' + | 'bh' + | 'bi' + | 'bj' + | 'bm' + | 'bn' + | 'bo' + | 'bq' + | 'br' + | 'bs' + | 'bw' + | 'by' + | 'bz' + | 'ca' + | 'cd' + | 'cf' + | 'cg' + | 'ch' + | 'ci' + | 'cl' + | 'cm' + | 'cn' + | 'co' + | 'cr' + | 'cv' + | 'cw' + | 'cy' + | 'cz' + | 'de' + | 'dj' + | 'dk' + | 'dm' + | 'do' + | 'dz' + | 'ec' + | 'ee' + | 'eg' + | 'es' + | 'et' + | 'fi' + | 'fj' + | 'fr' + | 'ga' + | 'gb' + | 'gd' + | 'ge' + | 'gf' + | 'gg' + | 'gh' + | 'gm' + | 'gn' + | 'gp' + | 'gq' + | 'gr' + | 'gt' + | 'gu' + | 'gw' + | 'gy' + | 'hk' + | 'hn' + | 'hr' + | 'ht' + | 'hu' + | 'id' + | 'ie' + | 'il' + | 'im' + | 'in' + | 'iq' + | 'ir' + | 'is' + | 'it' + | 'je' + | 'jm' + | 'jo' + | 'jp' + | 'ke' + | 'kg' + | 'kh' + | 'kn' + | 'kr' + | 'kw' + | 'ky' + | 'kz' + | 'la' + | 'lb' + | 'lc' + | 'lk' + | 'lr' + | 'ls' + | 'lt' + | 'lu' + | 'lv' + | 'ly' + | 'ma' + | 'mc' + | 'md' + | 'me' + | 'mf' + | 'mg' + | 'mk' + | 'ml' + | 'mm' + | 'mn' + | 'mo' + | 'mq' + | 'mr' + | 'mt' + | 'mu' + | 'mv' + | 'mw' + | 'mx' + | 'my' + | 'mz' + | 'na' + | 'nc' + | 'ne' + | 'ng' + | 'ni' + | 'nl' + | 'no' + | 'np' + | 'nz' + | 'om' + | 'pa' + | 'pe' + | 'pf' + | 'pg' + | 'ph' + | 'pk' + | 'pl' + | 'pr' + | 'ps' + | 'pt' + | 'py' + | 'qa' + | 're' + | 'ro' + | 'rs' + | 'ru' + | 'rw' + | 'sa' + | 'sc' + | 'sd' + | 'se' + | 'sg' + | 'si' + | 'sk' + | 'sl' + | 'sm' + | 'sn' + | 'so' + | 'sr' + | 'ss' + | 'st' + | 'sv' + | 'sx' + | 'sy' + | 'sz' + | 'tc' + | 'td' + | 'tg' + | 'th' + | 'tj' + | 'tl' + | 'tm' + | 'tn' + | 'tr' + | 'tt' + | 'tw' + | 'tz' + | 'ua' + | 'ug' + | 'us' + | 'uy' + | 'uz' + | 'vc' + | 've' + | 'vg' + | 'vi' + | 'vn' + | 'ye' + | 'yt' + | 'za' + | 'zm' + | 'zw'; + + /** + * Remove elements matching these CSS selectors. Applied after `includeSelectors`, + * so an element matching both is removed. + */ + excludeSelectors?: Array | null; + + /** + * Also return each page's HTML in `html`. + */ + includeHTML?: boolean; + + /** + * Include image references in the Markdown (`html-conversion` only). + */ + includeImages?: boolean; + + /** + * Include links in the Markdown (`html-conversion` only). + */ + includeLinks?: boolean; + + /** + * Keep only elements matching these CSS selectors. Filtered pages ignore + * `maxAgeMs`. + */ + includeSelectors?: Array | null; + + /** + * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 + * year (31536000000 ms). `0` fetches fresh. + */ + maxAgeMs?: number | null; + + /** + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. + */ + pdf?: Options.Pdf; + + /** + * Wait for CSS animations to finish before extracting, on browser-rendered pages. + */ + settleAnimations?: boolean; + + /** + * Shorten inline base64 image data (`html-conversion` only). + */ + shortenBase64Images?: boolean; + + /** + * Markdown sources in order of preference: `html-conversion` converts the page + * HTML, `markdown-direct` uses Markdown the site publishes. + */ + sourcePreference?: Array<'html-conversion' | 'markdown-direct'>; + + /** + * Return the main content without navigation or footers. + */ + useMainContentOnly?: boolean; + + /** + * How long to wait after initial page load, in milliseconds. `0` waits 500 ms. + */ + waitForMs?: number; + } + + export namespace Options { + /** + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. + */ + export interface Pdf { + /** + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. + */ + end?: number; + + /** + * Read scanned PDF pages with OCR; preserve pages that already have text. + */ + ocr?: boolean; + + /** + * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. + */ + shouldParse?: boolean; + + /** + * First 1-based PDF page to parse. + */ + start?: number; + } + } + } + + /** + * @deprecated Scrape the listed pages as HTML. + */ + export interface HTML { + /** + * Return page content as HTML. + */ + format: 'html'; + + /** + * Pages to scrape. Maximum 100000. + */ + urls: Array; + + /** + * Options for HTML output. + */ + options?: HTML.Options; + } + + export namespace HTML { + /** + * A page to scrape, with optional data for matching results. + */ + export interface URL { + /** + * Page URL to scrape. + */ + url: string; + + /** + * Your ID for this page, returned with its result. The same URL can use different + * IDs. + */ + itemId?: string; + + /** + * Custom JSON returned unchanged with this page result. + */ + meta?: { [key: string]: unknown }; + } + + /** + * Options for HTML output. + */ + export interface Options { + /** + * Fetch from this country (ISO 3166-1 alpha-2). + */ + country?: + | 'ad' + | 'ae' + | 'af' + | 'ag' + | 'ai' + | 'al' + | 'am' + | 'ao' + | 'ar' + | 'at' + | 'au' + | 'aw' + | 'az' + | 'ba' + | 'bb' + | 'bd' + | 'be' + | 'bf' + | 'bg' + | 'bh' + | 'bi' + | 'bj' + | 'bm' + | 'bn' + | 'bo' + | 'bq' + | 'br' + | 'bs' + | 'bw' + | 'by' + | 'bz' + | 'ca' + | 'cd' + | 'cf' + | 'cg' + | 'ch' + | 'ci' + | 'cl' + | 'cm' + | 'cn' + | 'co' + | 'cr' + | 'cv' + | 'cw' + | 'cy' + | 'cz' + | 'de' + | 'dj' + | 'dk' + | 'dm' + | 'do' + | 'dz' + | 'ec' + | 'ee' + | 'eg' + | 'es' + | 'et' + | 'fi' + | 'fj' + | 'fr' + | 'ga' + | 'gb' + | 'gd' + | 'ge' + | 'gf' + | 'gg' + | 'gh' + | 'gm' + | 'gn' + | 'gp' + | 'gq' + | 'gr' + | 'gt' + | 'gu' + | 'gw' + | 'gy' + | 'hk' + | 'hn' + | 'hr' + | 'ht' + | 'hu' + | 'id' + | 'ie' + | 'il' + | 'im' + | 'in' + | 'iq' + | 'ir' + | 'is' + | 'it' + | 'je' + | 'jm' + | 'jo' + | 'jp' + | 'ke' + | 'kg' + | 'kh' + | 'kn' + | 'kr' + | 'kw' + | 'ky' + | 'kz' + | 'la' + | 'lb' + | 'lc' + | 'lk' + | 'lr' + | 'ls' + | 'lt' + | 'lu' + | 'lv' + | 'ly' + | 'ma' + | 'mc' + | 'md' + | 'me' + | 'mf' + | 'mg' + | 'mk' + | 'ml' + | 'mm' + | 'mn' + | 'mo' + | 'mq' + | 'mr' + | 'mt' + | 'mu' + | 'mv' + | 'mw' + | 'mx' + | 'my' + | 'mz' + | 'na' + | 'nc' + | 'ne' + | 'ng' + | 'ni' + | 'nl' + | 'no' + | 'np' + | 'nz' + | 'om' + | 'pa' + | 'pe' + | 'pf' + | 'pg' + | 'ph' + | 'pk' + | 'pl' + | 'pr' + | 'ps' + | 'pt' + | 'py' + | 'qa' + | 're' + | 'ro' + | 'rs' + | 'ru' + | 'rw' + | 'sa' + | 'sc' + | 'sd' + | 'se' + | 'sg' + | 'si' + | 'sk' + | 'sl' + | 'sm' + | 'sn' + | 'so' + | 'sr' + | 'ss' + | 'st' + | 'sv' + | 'sx' + | 'sy' + | 'sz' + | 'tc' + | 'td' + | 'tg' + | 'th' + | 'tj' + | 'tl' + | 'tm' + | 'tn' + | 'tr' + | 'tt' + | 'tw' + | 'tz' + | 'ua' + | 'ug' + | 'us' + | 'uy' + | 'uz' + | 'vc' + | 've' + | 'vg' + | 'vi' + | 'vn' + | 'ye' + | 'yt' + | 'za' + | 'zm' + | 'zw'; + + /** + * Remove elements matching these CSS selectors. Applied after `includeSelectors`, + * so an element matching both is removed. + */ + excludeSelectors?: Array | null; + + /** + * Keep only elements matching these CSS selectors. Filtered pages ignore + * `maxAgeMs`. + */ + includeSelectors?: Array | null; + + /** + * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 + * year (31536000000 ms). `0` fetches fresh. + */ + maxAgeMs?: number | null; + + /** + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. + */ + pdf?: Options.Pdf; + + /** + * Wait for CSS animations to finish before extracting, on browser-rendered pages. + */ + settleAnimations?: boolean; + + /** + * Return the main content without navigation or footers. + */ + useMainContentOnly?: boolean; + + /** + * How long to wait after initial page load, in milliseconds. `0` waits 500 ms. + */ + waitForMs?: number; + } + + export namespace Options { + /** + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. + */ + export interface Pdf { + /** + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. + */ + end?: number; + + /** + * Read scanned PDF pages with OCR; preserve pages that already have text. + */ + ocr?: boolean; + + /** + * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. + */ + shouldParse?: boolean; + + /** + * First 1-based PDF page to parse. + */ + start?: number; + } + } + } + /** * Use the same formats and parameters as POST /web/scrape, replacing url with * urls. Options apply to every page. */ - export interface Data { + export interface BatchUnifiedScrapeData { /** * Outputs to return. Set at least one to `true`. */ - formats: Data.Formats; + formats: BatchUnifiedScrapeData.Formats; /** * Pages to scrape. Maximum 100000. */ - urls: Array; + urls: Array; /** * Requires `formats.highlights: true`; required when it is set. */ - highlightsParams?: Data.HighlightsParams; + highlightsParams?: BatchUnifiedScrapeData.HighlightsParams; /** * Image options. Requires formats.images: true. */ - imageParams?: Data.ImageParams; + imageParams?: BatchUnifiedScrapeData.ImageParams; /** * Requires `formats.json: true`; required when it is set. */ - jsonParams?: Data.JsonParams; + jsonParams?: BatchUnifiedScrapeData.JsonParams; /** * Markdown options. Requires `formats.markdown`. */ - markdownParams?: Data.MarkdownParams; + markdownParams?: BatchUnifiedScrapeData.MarkdownParams; /** * Maximum age of a cached output, in milliseconds. `0` fetches fresh. Defaults to @@ -2990,22 +3661,22 @@ export namespace BatchSubmitParams { /** * Requires `formats.parse: true`; required when it is set. */ - parseParams?: Data.CustomParser | Data.PrebuiltParser; + parseParams?: BatchUnifiedScrapeData.CustomParser | BatchUnifiedScrapeData.PrebuiltParser; /** * Product options. Requires formats.product: true. */ - productParams?: Data.ProductParams; + productParams?: BatchUnifiedScrapeData.ProductParams; /** * Screenshot options. Requires formats.screenshot: true. */ - screenshotParams?: Data.ScreenshotParams; + screenshotParams?: BatchUnifiedScrapeData.ScreenshotParams; /** * Browser and content settings shared by all outputs. */ - sharedParams?: Data.SharedParams; + sharedParams?: BatchUnifiedScrapeData.SharedParams; /** * Labels for tracking request usage. Not retained when zdr is enabled. @@ -3016,7 +3687,7 @@ export namespace BatchSubmitParams { * Deadline for each page, using the same behavior and defaults as POST * /web/scrape. */ - timeoutOpts?: Data.TimeoutOpts; + timeoutOpts?: BatchUnifiedScrapeData.TimeoutOpts; /** * Batches persist their results. Only disabled is supported; enabled returns @@ -3025,7 +3696,7 @@ export namespace BatchSubmitParams { zdr?: 'disabled'; } - export namespace Data { + export namespace BatchUnifiedScrapeData { /** * Outputs to return. Set at least one to `true`. */ @@ -3637,10 +4308,9 @@ export namespace BatchSubmitParams { */ export interface Crawl { /** - * Use the same formats and parameters as POST /web/scrape, replacing url with - * source. Options apply to every page. + * Crawl source and output format. */ - data: Crawl.Data; + data: Crawl.Markdown | Crawl.HTML | Crawl.BatchUnifiedCrawlData; /** * Discover and scrape pages from `data.source`. @@ -3649,40 +4319,1036 @@ export namespace BatchSubmitParams { } export namespace Crawl { + /** + * @deprecated Crawl pages and return Markdown. + */ + export interface Markdown { + /** + * Return page content as Markdown. + */ + format: 'markdown'; + + /** + * How to find pages to crawl. + */ + source: Markdown.StartURL | Markdown.Sitemap; + + /** + * Options for Markdown output. + */ + options?: Markdown.Options; + } + + export namespace Markdown { + /** + * Discover pages by following links from one URL. + */ + export interface StartURL { + /** + * Start from one page. + */ + type: 'start_url'; + + /** + * Page where crawling begins. A URL without a scheme is read as https://. + */ + url: string; + + /** + * Limits and filters for page discovery. + */ + controls?: StartURL.Controls; + } + + export namespace StartURL { + /** + * Limits and filters for page discovery. + */ + export interface Controls { + /** + * Regex pattern for URLs to exclude, even when they match `regex`. The `start_url` + * itself is always included. + */ + excludeRegex?: string; + + /** + * Follow links to subdomains. + */ + followSubdomains?: boolean; + + /** + * Only follow pages in these languages, or `same_as_start_url`; all languages when + * omitted. + */ + languages?: + | 'same_as_start_url' + | Array< + | 'am' + | 'ar' + | 'az' + | 'be' + | 'bg' + | 'bn' + | 'ca' + | 'ceb' + | 'cs' + | 'cy' + | 'da' + | 'de' + | 'el' + | 'en' + | 'es' + | 'et' + | 'eu' + | 'fa' + | 'fi' + | 'fr' + | 'gu' + | 'ha' + | 'haw' + | 'he' + | 'hi' + | 'hr' + | 'hu' + | 'hy' + | 'id' + | 'is' + | 'it' + | 'ja' + | 'ka' + | 'kk' + | 'kn' + | 'ko' + | 'ku' + | 'ky' + | 'lo' + | 'lt' + | 'lv' + | 'mk' + | 'ml' + | 'mn' + | 'mr' + | 'ms' + | 'ne' + | 'nl' + | 'no' + | 'or' + | 'pa' + | 'pl' + | 'ps' + | 'pt' + | 'ro' + | 'ru' + | 'sk' + | 'sl' + | 'so' + | 'sq' + | 'sr' + | 'sv' + | 'sw' + | 'ta' + | 'te' + | 'th' + | 'tl' + | 'tr' + | 'uk' + | 'ur' + | 'uz' + | 'vi' + | 'yo' + | 'zh' + >; + + /** + * Maximum link depth. Source pages are depth 0. No limit when omitted. + */ + maxDepth?: number; + + /** + * Maximum pages to fetch. Unused reserved credits are refunded. Maximum 100000. + */ + maxUrls?: number; + + /** + * Regex pattern for URLs to include. The `start_url` itself is always included. + */ + regex?: string; + } + } + + /** + * Scrape the pages listed in a domain's sitemap. Links on those pages are not + * followed. + */ + export interface Sitemap { + /** + * Domain whose sitemap lists the pages to scrape. A full URL is reduced to its + * domain. + */ + domain: string; + + /** + * Scrape the URLs in the domain's sitemap. + */ + type: 'sitemap'; + + /** + * Limits and filters for the sitemap URLs. A sitemap batch scrapes exactly those + * URLs and never follows links off them, so there is no crawl depth here. + */ + controls?: Sitemap.Controls; + } + + export namespace Sitemap { + /** + * Limits and filters for the sitemap URLs. A sitemap batch scrapes exactly those + * URLs and never follows links off them, so there is no crawl depth here. + */ + export interface Controls { + /** + * Regex pattern; sitemap URLs matching it are not scraped, even when they match + * `regex`. + */ + excludeRegex?: string; + + /** + * Maximum pages to fetch. Unused reserved credits are refunded. Maximum 100000. + */ + maxUrls?: number; + + /** + * Regex pattern; only sitemap URLs matching it are scraped. + */ + regex?: string; + } + } + + /** + * Options for Markdown output. + */ + export interface Options { + /** + * Fetch from this country (ISO 3166-1 alpha-2). + */ + country?: + | 'ad' + | 'ae' + | 'af' + | 'ag' + | 'ai' + | 'al' + | 'am' + | 'ao' + | 'ar' + | 'at' + | 'au' + | 'aw' + | 'az' + | 'ba' + | 'bb' + | 'bd' + | 'be' + | 'bf' + | 'bg' + | 'bh' + | 'bi' + | 'bj' + | 'bm' + | 'bn' + | 'bo' + | 'bq' + | 'br' + | 'bs' + | 'bw' + | 'by' + | 'bz' + | 'ca' + | 'cd' + | 'cf' + | 'cg' + | 'ch' + | 'ci' + | 'cl' + | 'cm' + | 'cn' + | 'co' + | 'cr' + | 'cv' + | 'cw' + | 'cy' + | 'cz' + | 'de' + | 'dj' + | 'dk' + | 'dm' + | 'do' + | 'dz' + | 'ec' + | 'ee' + | 'eg' + | 'es' + | 'et' + | 'fi' + | 'fj' + | 'fr' + | 'ga' + | 'gb' + | 'gd' + | 'ge' + | 'gf' + | 'gg' + | 'gh' + | 'gm' + | 'gn' + | 'gp' + | 'gq' + | 'gr' + | 'gt' + | 'gu' + | 'gw' + | 'gy' + | 'hk' + | 'hn' + | 'hr' + | 'ht' + | 'hu' + | 'id' + | 'ie' + | 'il' + | 'im' + | 'in' + | 'iq' + | 'ir' + | 'is' + | 'it' + | 'je' + | 'jm' + | 'jo' + | 'jp' + | 'ke' + | 'kg' + | 'kh' + | 'kn' + | 'kr' + | 'kw' + | 'ky' + | 'kz' + | 'la' + | 'lb' + | 'lc' + | 'lk' + | 'lr' + | 'ls' + | 'lt' + | 'lu' + | 'lv' + | 'ly' + | 'ma' + | 'mc' + | 'md' + | 'me' + | 'mf' + | 'mg' + | 'mk' + | 'ml' + | 'mm' + | 'mn' + | 'mo' + | 'mq' + | 'mr' + | 'mt' + | 'mu' + | 'mv' + | 'mw' + | 'mx' + | 'my' + | 'mz' + | 'na' + | 'nc' + | 'ne' + | 'ng' + | 'ni' + | 'nl' + | 'no' + | 'np' + | 'nz' + | 'om' + | 'pa' + | 'pe' + | 'pf' + | 'pg' + | 'ph' + | 'pk' + | 'pl' + | 'pr' + | 'ps' + | 'pt' + | 'py' + | 'qa' + | 're' + | 'ro' + | 'rs' + | 'ru' + | 'rw' + | 'sa' + | 'sc' + | 'sd' + | 'se' + | 'sg' + | 'si' + | 'sk' + | 'sl' + | 'sm' + | 'sn' + | 'so' + | 'sr' + | 'ss' + | 'st' + | 'sv' + | 'sx' + | 'sy' + | 'sz' + | 'tc' + | 'td' + | 'tg' + | 'th' + | 'tj' + | 'tl' + | 'tm' + | 'tn' + | 'tr' + | 'tt' + | 'tw' + | 'tz' + | 'ua' + | 'ug' + | 'us' + | 'uy' + | 'uz' + | 'vc' + | 've' + | 'vg' + | 'vi' + | 'vn' + | 'ye' + | 'yt' + | 'za' + | 'zm' + | 'zw'; + + /** + * Remove elements matching these CSS selectors. Applied after `includeSelectors`, + * so an element matching both is removed. + */ + excludeSelectors?: Array | null; + + /** + * Also return each page's HTML in `html`. + */ + includeHTML?: boolean; + + /** + * Include image references in the Markdown (`html-conversion` only). + */ + includeImages?: boolean; + + /** + * Include links in the Markdown (`html-conversion` only). + */ + includeLinks?: boolean; + + /** + * Keep only elements matching these CSS selectors. Filtered pages ignore + * `maxAgeMs`. + */ + includeSelectors?: Array | null; + + /** + * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 + * year (31536000000 ms). `0` fetches fresh. + */ + maxAgeMs?: number | null; + + /** + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. + */ + pdf?: Options.Pdf; + + /** + * Wait for CSS animations to finish before extracting, on browser-rendered pages. + */ + settleAnimations?: boolean; + + /** + * Shorten inline base64 image data (`html-conversion` only). + */ + shortenBase64Images?: boolean; + + /** + * Markdown sources in order of preference: `html-conversion` converts the page + * HTML, `markdown-direct` uses Markdown the site publishes. + */ + sourcePreference?: Array<'html-conversion' | 'markdown-direct'>; + + /** + * Return the main content without navigation or footers. + */ + useMainContentOnly?: boolean; + + /** + * How long to wait after initial page load, in milliseconds. `0` waits 500 ms. + */ + waitForMs?: number; + } + + export namespace Options { + /** + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. + */ + export interface Pdf { + /** + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. + */ + end?: number; + + /** + * Read scanned PDF pages with OCR; preserve pages that already have text. + */ + ocr?: boolean; + + /** + * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. + */ + shouldParse?: boolean; + + /** + * First 1-based PDF page to parse. + */ + start?: number; + } + } + } + + /** + * @deprecated Crawl pages and return HTML. + */ + export interface HTML { + /** + * Return page content as HTML. + */ + format: 'html'; + + /** + * How to find pages to crawl. + */ + source: HTML.StartURL | HTML.Sitemap; + + /** + * Options for HTML output. + */ + options?: HTML.Options; + } + + export namespace HTML { + /** + * Discover pages by following links from one URL. + */ + export interface StartURL { + /** + * Start from one page. + */ + type: 'start_url'; + + /** + * Page where crawling begins. A URL without a scheme is read as https://. + */ + url: string; + + /** + * Limits and filters for page discovery. + */ + controls?: StartURL.Controls; + } + + export namespace StartURL { + /** + * Limits and filters for page discovery. + */ + export interface Controls { + /** + * Regex pattern for URLs to exclude, even when they match `regex`. The `start_url` + * itself is always included. + */ + excludeRegex?: string; + + /** + * Follow links to subdomains. + */ + followSubdomains?: boolean; + + /** + * Only follow pages in these languages, or `same_as_start_url`; all languages when + * omitted. + */ + languages?: + | 'same_as_start_url' + | Array< + | 'am' + | 'ar' + | 'az' + | 'be' + | 'bg' + | 'bn' + | 'ca' + | 'ceb' + | 'cs' + | 'cy' + | 'da' + | 'de' + | 'el' + | 'en' + | 'es' + | 'et' + | 'eu' + | 'fa' + | 'fi' + | 'fr' + | 'gu' + | 'ha' + | 'haw' + | 'he' + | 'hi' + | 'hr' + | 'hu' + | 'hy' + | 'id' + | 'is' + | 'it' + | 'ja' + | 'ka' + | 'kk' + | 'kn' + | 'ko' + | 'ku' + | 'ky' + | 'lo' + | 'lt' + | 'lv' + | 'mk' + | 'ml' + | 'mn' + | 'mr' + | 'ms' + | 'ne' + | 'nl' + | 'no' + | 'or' + | 'pa' + | 'pl' + | 'ps' + | 'pt' + | 'ro' + | 'ru' + | 'sk' + | 'sl' + | 'so' + | 'sq' + | 'sr' + | 'sv' + | 'sw' + | 'ta' + | 'te' + | 'th' + | 'tl' + | 'tr' + | 'uk' + | 'ur' + | 'uz' + | 'vi' + | 'yo' + | 'zh' + >; + + /** + * Maximum link depth. Source pages are depth 0. No limit when omitted. + */ + maxDepth?: number; + + /** + * Maximum pages to fetch. Unused reserved credits are refunded. Maximum 100000. + */ + maxUrls?: number; + + /** + * Regex pattern for URLs to include. The `start_url` itself is always included. + */ + regex?: string; + } + } + + /** + * Scrape the pages listed in a domain's sitemap. Links on those pages are not + * followed. + */ + export interface Sitemap { + /** + * Domain whose sitemap lists the pages to scrape. A full URL is reduced to its + * domain. + */ + domain: string; + + /** + * Scrape the URLs in the domain's sitemap. + */ + type: 'sitemap'; + + /** + * Limits and filters for the sitemap URLs. A sitemap batch scrapes exactly those + * URLs and never follows links off them, so there is no crawl depth here. + */ + controls?: Sitemap.Controls; + } + + export namespace Sitemap { + /** + * Limits and filters for the sitemap URLs. A sitemap batch scrapes exactly those + * URLs and never follows links off them, so there is no crawl depth here. + */ + export interface Controls { + /** + * Regex pattern; sitemap URLs matching it are not scraped, even when they match + * `regex`. + */ + excludeRegex?: string; + + /** + * Maximum pages to fetch. Unused reserved credits are refunded. Maximum 100000. + */ + maxUrls?: number; + + /** + * Regex pattern; only sitemap URLs matching it are scraped. + */ + regex?: string; + } + } + + /** + * Options for HTML output. + */ + export interface Options { + /** + * Fetch from this country (ISO 3166-1 alpha-2). + */ + country?: + | 'ad' + | 'ae' + | 'af' + | 'ag' + | 'ai' + | 'al' + | 'am' + | 'ao' + | 'ar' + | 'at' + | 'au' + | 'aw' + | 'az' + | 'ba' + | 'bb' + | 'bd' + | 'be' + | 'bf' + | 'bg' + | 'bh' + | 'bi' + | 'bj' + | 'bm' + | 'bn' + | 'bo' + | 'bq' + | 'br' + | 'bs' + | 'bw' + | 'by' + | 'bz' + | 'ca' + | 'cd' + | 'cf' + | 'cg' + | 'ch' + | 'ci' + | 'cl' + | 'cm' + | 'cn' + | 'co' + | 'cr' + | 'cv' + | 'cw' + | 'cy' + | 'cz' + | 'de' + | 'dj' + | 'dk' + | 'dm' + | 'do' + | 'dz' + | 'ec' + | 'ee' + | 'eg' + | 'es' + | 'et' + | 'fi' + | 'fj' + | 'fr' + | 'ga' + | 'gb' + | 'gd' + | 'ge' + | 'gf' + | 'gg' + | 'gh' + | 'gm' + | 'gn' + | 'gp' + | 'gq' + | 'gr' + | 'gt' + | 'gu' + | 'gw' + | 'gy' + | 'hk' + | 'hn' + | 'hr' + | 'ht' + | 'hu' + | 'id' + | 'ie' + | 'il' + | 'im' + | 'in' + | 'iq' + | 'ir' + | 'is' + | 'it' + | 'je' + | 'jm' + | 'jo' + | 'jp' + | 'ke' + | 'kg' + | 'kh' + | 'kn' + | 'kr' + | 'kw' + | 'ky' + | 'kz' + | 'la' + | 'lb' + | 'lc' + | 'lk' + | 'lr' + | 'ls' + | 'lt' + | 'lu' + | 'lv' + | 'ly' + | 'ma' + | 'mc' + | 'md' + | 'me' + | 'mf' + | 'mg' + | 'mk' + | 'ml' + | 'mm' + | 'mn' + | 'mo' + | 'mq' + | 'mr' + | 'mt' + | 'mu' + | 'mv' + | 'mw' + | 'mx' + | 'my' + | 'mz' + | 'na' + | 'nc' + | 'ne' + | 'ng' + | 'ni' + | 'nl' + | 'no' + | 'np' + | 'nz' + | 'om' + | 'pa' + | 'pe' + | 'pf' + | 'pg' + | 'ph' + | 'pk' + | 'pl' + | 'pr' + | 'ps' + | 'pt' + | 'py' + | 'qa' + | 're' + | 'ro' + | 'rs' + | 'ru' + | 'rw' + | 'sa' + | 'sc' + | 'sd' + | 'se' + | 'sg' + | 'si' + | 'sk' + | 'sl' + | 'sm' + | 'sn' + | 'so' + | 'sr' + | 'ss' + | 'st' + | 'sv' + | 'sx' + | 'sy' + | 'sz' + | 'tc' + | 'td' + | 'tg' + | 'th' + | 'tj' + | 'tl' + | 'tm' + | 'tn' + | 'tr' + | 'tt' + | 'tw' + | 'tz' + | 'ua' + | 'ug' + | 'us' + | 'uy' + | 'uz' + | 'vc' + | 've' + | 'vg' + | 'vi' + | 'vn' + | 'ye' + | 'yt' + | 'za' + | 'zm' + | 'zw'; + + /** + * Remove elements matching these CSS selectors. Applied after `includeSelectors`, + * so an element matching both is removed. + */ + excludeSelectors?: Array | null; + + /** + * Keep only elements matching these CSS selectors. Filtered pages ignore + * `maxAgeMs`. + */ + includeSelectors?: Array | null; + + /** + * Maximum cache age in milliseconds. Defaults to 3 days (259200000 ms). Maximum: 1 + * year (31536000000 ms). `0` fetches fresh. + */ + maxAgeMs?: number | null; + + /** + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. + */ + pdf?: Options.Pdf; + + /** + * Wait for CSS animations to finish before extracting, on browser-rendered pages. + */ + settleAnimations?: boolean; + + /** + * Return the main content without navigation or footers. + */ + useMainContentOnly?: boolean; + + /** + * How long to wait after initial page load, in milliseconds. `0` waits 500 ms. + */ + waitForMs?: number; + } + + export namespace Options { + /** + * PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. + */ + export interface Pdf { + /** + * Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must + * be >= start. + */ + end?: number; + + /** + * Read scanned PDF pages with OCR; preserve pages that already have text. + */ + ocr?: boolean; + + /** + * Parse PDF URLs. When false, PDFs fail with `PDF_SKIPPED`. + */ + shouldParse?: boolean; + + /** + * First 1-based PDF page to parse. + */ + start?: number; + } + } + } + /** * Use the same formats and parameters as POST /web/scrape, replacing url with * source. Options apply to every page. */ - export interface Data { + export interface BatchUnifiedCrawlData { /** * Outputs to return. Set at least one to `true`. */ - formats: Data.Formats; + formats: BatchUnifiedCrawlData.Formats; /** * How to find pages to crawl. */ - source: Data.StartURL | Data.Sitemap; + source: BatchUnifiedCrawlData.StartURL | BatchUnifiedCrawlData.Sitemap; /** * Requires `formats.highlights: true`; required when it is set. */ - highlightsParams?: Data.HighlightsParams; + highlightsParams?: BatchUnifiedCrawlData.HighlightsParams; /** * Image options. Requires formats.images: true. */ - imageParams?: Data.ImageParams; + imageParams?: BatchUnifiedCrawlData.ImageParams; /** * Requires `formats.json: true`; required when it is set. */ - jsonParams?: Data.JsonParams; + jsonParams?: BatchUnifiedCrawlData.JsonParams; /** * Markdown options. Requires `formats.markdown`. */ - markdownParams?: Data.MarkdownParams; + markdownParams?: BatchUnifiedCrawlData.MarkdownParams; /** * Maximum age of a cached output, in milliseconds. `0` fetches fresh. Defaults to @@ -3693,22 +5359,22 @@ export namespace BatchSubmitParams { /** * Requires `formats.parse: true`; required when it is set. */ - parseParams?: Data.CustomParser | Data.PrebuiltParser; + parseParams?: BatchUnifiedCrawlData.CustomParser | BatchUnifiedCrawlData.PrebuiltParser; /** * Product options. Requires formats.product: true. */ - productParams?: Data.ProductParams; + productParams?: BatchUnifiedCrawlData.ProductParams; /** * Screenshot options. Requires formats.screenshot: true. */ - screenshotParams?: Data.ScreenshotParams; + screenshotParams?: BatchUnifiedCrawlData.ScreenshotParams; /** * Browser and content settings shared by all outputs. */ - sharedParams?: Data.SharedParams; + sharedParams?: BatchUnifiedCrawlData.SharedParams; /** * Labels for tracking request usage. Not retained when zdr is enabled. @@ -3719,7 +5385,7 @@ export namespace BatchSubmitParams { * Deadline for each page, using the same behavior and defaults as POST * /web/scrape. */ - timeoutOpts?: Data.TimeoutOpts; + timeoutOpts?: BatchUnifiedCrawlData.TimeoutOpts; /** * Batches persist their results. Only disabled is supported; enabled returns @@ -3728,7 +5394,7 @@ export namespace BatchSubmitParams { zdr?: 'disabled'; } - export namespace Data { + export namespace BatchUnifiedCrawlData { /** * Outputs to return. Set at least one to `true`. */ From e96b8e6833971894877b28e03e04486cedfa8a7c Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 28 Oct 2026 14:22:41 +0000 Subject: [PATCH 195/232] fix(openapi): keep legacy batch inputs in the spec as deprecated (#2225) feat(access-policies): limit which websites API requests can reach (#2213) Stainless-Generated-From: 2a102d3f6f67433c44b631a16ecde5ffb5c01b53 --- src/resources/batch.ts | 16 +++++++++++++ src/resources/brand.ts | 30 ++++++++++++++++++++++++ src/resources/monitors.ts | 35 ++++++++++++++++++++++++++++ src/resources/news.ts | 5 ++++ src/resources/utility.ts | 5 ++++ src/resources/web.ts | 30 ++++++++++++++++++++++++ tests/api-resources/batch.test.ts | 1 + tests/api-resources/brand.test.ts | 1 + tests/api-resources/monitors.test.ts | 1 + tests/api-resources/news.test.ts | 1 + tests/api-resources/utility.test.ts | 1 + tests/api-resources/web.test.ts | 6 +++++ 12 files changed, 132 insertions(+) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 7171e66e..8d9eaca9 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -421,6 +421,11 @@ export interface BatchRetrieveResponse { */ key_metadata?: BatchRetrieveResponse.KeyMetadata; + /** + * Access policy IDs applied to every page. + */ + policies?: Array; + /** * Batch completion delivery ID, when available. */ @@ -701,6 +706,11 @@ export namespace BatchListResponse { tags: Array; timing: Data.Timing; + + /** + * Access policy IDs applied to every page. + */ + policies?: Array; } export namespace Data { @@ -2904,6 +2914,12 @@ export interface BatchSubmitParams { */ input: BatchSubmitParams.Scrape | BatchSubmitParams.Crawl; + /** + * Body param: Access policy IDs to apply to every page. A URL must pass every + * policy. + */ + policies?: Array; + /** * Body param: Tags stored on the batch. Filter the batch list by them later. */ diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 9cc71291..0dd7946b 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -1477,6 +1477,11 @@ export declare namespace BrandRetrieveParams { */ maxSpeed?: boolean; + /** + * Access policy IDs to apply. A URL must pass every policy. + */ + policies?: Array; + /** * Labels for filtering usage in the dashboard. */ @@ -1898,6 +1903,11 @@ export declare namespace BrandRetrieveParams { */ maxSpeed?: boolean; + /** + * Access policy IDs to apply. A URL must pass every policy. + */ + policies?: Array; + /** * Labels for filtering usage in the dashboard. */ @@ -2074,6 +2084,11 @@ export declare namespace BrandRetrieveParams { */ maxSpeed?: boolean; + /** + * Access policy IDs to apply. A URL must pass every policy. + */ + policies?: Array; + /** * Labels for filtering usage in the dashboard. */ @@ -2250,6 +2265,11 @@ export declare namespace BrandRetrieveParams { */ maxSpeed?: boolean; + /** + * Access policy IDs to apply. A URL must pass every policy. + */ + policies?: Array; + /** * Labels for filtering usage in the dashboard. */ @@ -2369,6 +2389,11 @@ export declare namespace BrandRetrieveParams { */ type: 'by_direct_url'; + /** + * Access policy IDs to apply. A URL must pass every policy. + */ + policies?: Array; + /** * Labels for filtering usage in the dashboard. */ @@ -2806,6 +2831,11 @@ export declare namespace BrandRetrieveParams { */ phone?: string | number; + /** + * Access policy IDs to apply. A URL must pass every policy. + */ + policies?: Array; + /** * Labels for filtering usage in the dashboard. */ diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index 454a7a40..06df3085 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -375,6 +375,11 @@ export interface MonitorCreateResponse { */ next_run_at?: string | null; + /** + * Access policy IDs applied to every run. + */ + policies?: Array; + /** * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. * every 6 hours or every 2 days. The total interval (frequency × unit) must be @@ -847,6 +852,11 @@ export interface MonitorRetrieveResponse { */ next_run_at?: string | null; + /** + * Access policy IDs applied to every run. + */ + policies?: Array; + /** * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. * every 6 hours or every 2 days. The total interval (frequency × unit) must be @@ -1319,6 +1329,11 @@ export interface MonitorUpdateResponse { */ next_run_at?: string | null; + /** + * Access policy IDs applied to every run. + */ + policies?: Array; + /** * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. * every 6 hours or every 2 days. The total interval (frequency × unit) must be @@ -1802,6 +1817,11 @@ export namespace MonitorListResponse { */ next_run_at?: string | null; + /** + * Access policy IDs applied to every run. + */ + policies?: Array; + /** * Labels for filtering monitors, their changes, and their usage. */ @@ -3086,6 +3106,11 @@ export interface MonitorRotateWebhookSecretResponse { */ next_run_at?: string | null; + /** + * Access policy IDs applied to every run. + */ + policies?: Array; + /** * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. * every 6 hours or every 2 days. The total interval (frequency × unit) must be @@ -3553,6 +3578,11 @@ export interface MonitorCreateParams { */ mode?: 'web'; + /** + * Access policy IDs to apply to every run. + */ + policies?: Array; + /** * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. * every 6 hours or every 2 days. The total interval (frequency × unit) must be @@ -3847,6 +3877,11 @@ export interface MonitorUpdateParams { */ name?: string; + /** + * Access policy IDs to apply to every run. Send an empty list to remove them. + */ + policies?: Array; + /** * Run the monitor on a fixed interval defined by a frequency and a unit, e.g. * every 6 hours or every 2 days. The total interval (frequency × unit) must be diff --git a/src/resources/news.ts b/src/resources/news.ts index 1682b22c..a23226f1 100644 --- a/src/resources/news.ts +++ b/src/resources/news.ts @@ -221,6 +221,11 @@ export interface NewsSearchParams { */ limit?: number; + /** + * Access policy IDs to apply. A URL must pass every policy. + */ + policies?: Array; + /** * Result ordering. Defaults to newest for entity searches. Natural-language * searches are always ordered by relevance. diff --git a/src/resources/utility.ts b/src/resources/utility.ts index 566199d9..7a7fa097 100644 --- a/src/resources/utility.ts +++ b/src/resources/utility.ts @@ -84,6 +84,11 @@ export interface UtilityPrefetchParams { */ type: 'brand' | 'styleguide'; + /** + * Access policy IDs to apply. A URL must pass every policy. + */ + policies?: Array; + /** * Labels for filtering usage in the dashboard. */ diff --git a/src/resources/web.ts b/src/resources/web.ts index 781f3829..f0a29d26 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2152,6 +2152,11 @@ export interface WebAnswersParams { */ mode?: 'fast' | 'ultra'; + /** + * Access policy IDs to apply. A URL must pass every policy. + */ + policies?: Array; + /** * Labels for filtering usage in the dashboard. */ @@ -2259,6 +2264,11 @@ export interface WebExtractStyleguideParams { */ maxAgeMs?: number | null; + /** + * Comma-separated access policy IDs to apply. A URL must pass every policy. + */ + policies?: Array; + /** * Comma-separated labels for filtering usage, e.g. `production,team-alpha`. */ @@ -2321,6 +2331,11 @@ export interface WebMapURLsParams { */ maxLinks?: number; + /** + * Comma-separated access policy IDs to apply. A URL must pass every policy. + */ + policies?: Array; + /** * Filter URLs by a topic or phrase, most relevant first. */ @@ -2415,6 +2430,11 @@ export interface WebScrapeParams { */ parseParams?: WebScrapeParams.CustomParser | WebScrapeParams.PrebuiltParser; + /** + * Access policy IDs to apply. A URL must pass every policy. + */ + policies?: Array; + /** * Product options. Requires formats.product: true. */ @@ -3757,6 +3777,11 @@ export interface WebSearchParams { */ numResults?: number; + /** + * Access policy IDs to apply. A URL must pass every policy. + */ + policies?: Array; + /** * Currently has no effect. */ @@ -4185,6 +4210,11 @@ export interface WebWebCrawlMdParams { */ pdf?: WebWebCrawlMdParams.Pdf; + /** + * Access policy IDs to apply. A URL must pass every policy. + */ + policies?: Array; + /** * Wait briefly for CSS animations and transitions to settle before reading each * page. diff --git a/tests/api-resources/batch.test.ts b/tests/api-resources/batch.test.ts index d3f02f97..9aa799a5 100644 --- a/tests/api-resources/batch.test.ts +++ b/tests/api-resources/batch.test.ts @@ -211,6 +211,7 @@ describe('resource batch', () => { }, mode: 'scrape', }, + policies: ['pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e'], tags: ['docs', 'competitor'], webhook: { url: 'https://example.com', diff --git a/tests/api-resources/brand.test.ts b/tests/api-resources/brand.test.ts index c7e9de92..a872dbbc 100644 --- a/tests/api-resources/brand.test.ts +++ b/tests/api-resources/brand.test.ts @@ -28,6 +28,7 @@ describe('resource brand', () => { force_language: 'afrikaans', maxAgeMs: 0, maxSpeed: true, + policies: ['pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e'], tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); diff --git a/tests/api-resources/monitors.test.ts b/tests/api-resources/monitors.test.ts index 720bf284..0e7feee7 100644 --- a/tests/api-resources/monitors.test.ts +++ b/tests/api-resources/monitors.test.ts @@ -39,6 +39,7 @@ describe('resource monitors', () => { }, change_detection: { type: 'exact' }, mode: 'web', + policies: ['pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e'], schedule: { frequency: 6, type: 'interval', diff --git a/tests/api-resources/news.test.ts b/tests/api-resources/news.test.ts index c6c423f5..c16a3e78 100644 --- a/tests/api-resources/news.test.ts +++ b/tests/api-resources/news.test.ts @@ -41,6 +41,7 @@ describe('resource news', () => { sourceDomain: ['x'], }, limit: 1, + policies: ['pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e'], sortBy: { type: 'relevance' }, tags: ['production', 'team-alpha'], }); diff --git a/tests/api-resources/utility.test.ts b/tests/api-resources/utility.test.ts index 28ff7a74..078c75e1 100644 --- a/tests/api-resources/utility.test.ts +++ b/tests/api-resources/utility.test.ts @@ -28,6 +28,7 @@ describe('resource utility', () => { const response = await client.utility.prefetch({ identifier: { domain: 'stripe.com' }, type: 'brand', + policies: ['pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e'], tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, }); diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index d934566e..26006e70 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -28,6 +28,7 @@ describe('resource web', () => { task: 'Find the pricing page URL and plan names for context.dev.', json_format: { pricing_page_url: 'bar', plans: 'bar' }, mode: 'fast', + policies: ['pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e'], tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, zdr: 'enabled', @@ -79,6 +80,7 @@ describe('resource web', () => { directUrl: 'https://example.com', domain: 'xxx', maxAgeMs: 0, + policies: ['string'], tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1, behavior: 'fail' }, zdr: 'enabled', @@ -108,6 +110,7 @@ describe('resource web', () => { headers: { foo: 'J!' }, includeSubdomains: true, maxLinks: 1, + policies: ['string'], search: 'help center and troubleshooting articles', sitemapUrl: 'https://example.com', tags: ['production', 'team-alpha'], @@ -176,6 +179,7 @@ describe('resource web', () => { }, type: 'custom', }, + policies: ['pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e'], productParams: { dedupeImages: true }, screenshotParams: { area: 'viewport', format: 'png' }, sharedParams: { @@ -288,6 +292,7 @@ describe('resource web', () => { waitForMs: 0, }, numResults: 10, + policies: ['pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e'], queryFanout: true, tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, @@ -328,6 +333,7 @@ describe('resource web', () => { shouldParse: true, start: 1, }, + policies: ['pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e'], settleAnimations: true, shortenBase64Images: true, sourcePreference: ['html-conversion'], From 93ccc892b4758e3ac4b2ad0954738f075d362655 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 28 Oct 2026 15:14:06 +0000 Subject: [PATCH 196/232] fix(openapi): keep legacy batch inputs in the spec as deprecated (#2225) feat(access-policies): limit which websites API requests can reach (#2213) feat(brand): support log-free brand and styleguide requests (#2231) Stainless-Generated-From: b6bd49e0bce21d28110a579c57e8e15d60449133 --- src/resources/brand.ts | 42 +++++++++++++++++++++++++++++++ src/resources/web.ts | 5 ++-- tests/api-resources/brand.test.ts | 1 + 3 files changed, 46 insertions(+), 2 deletions(-) diff --git a/src/resources/brand.ts b/src/resources/brand.ts index 0dd7946b..a567756b 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -1491,6 +1491,13 @@ export declare namespace BrandRetrieveParams { * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveByDomainRequest.TimeoutOpts; + + /** + * `enabled` disables request logs, usage logs, and traces. Brand data and hosted + * assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your + * organization has ZDR. + */ + zdr?: 'enabled' | 'disabled'; } export namespace BrandRetrieveByDomainRequest { @@ -1917,6 +1924,13 @@ export declare namespace BrandRetrieveParams { * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveByNameRequest.TimeoutOpts; + + /** + * `enabled` disables request logs, usage logs, and traces. Brand data and hosted + * assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your + * organization has ZDR. + */ + zdr?: 'enabled' | 'disabled'; } export namespace BrandRetrieveByNameRequest { @@ -2098,6 +2112,13 @@ export declare namespace BrandRetrieveParams { * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveByEmailRequest.TimeoutOpts; + + /** + * `enabled` disables request logs, usage logs, and traces. Brand data and hosted + * assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your + * organization has ZDR. + */ + zdr?: 'enabled' | 'disabled'; } export namespace BrandRetrieveByEmailRequest { @@ -2356,6 +2377,13 @@ export declare namespace BrandRetrieveParams { * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveByTickerRequest.TimeoutOpts; + + /** + * `enabled` disables request logs, usage logs, and traces. Brand data and hosted + * assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your + * organization has ZDR. + */ + zdr?: 'enabled' | 'disabled'; } export namespace BrandRetrieveByTickerRequest { @@ -2403,6 +2431,13 @@ export declare namespace BrandRetrieveParams { * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveByDirectURLRequest.TimeoutOpts; + + /** + * `enabled` disables request logs, usage logs, and traces. Brand data and hosted + * assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your + * organization has ZDR. + */ + zdr?: 'enabled' | 'disabled'; } export namespace BrandRetrieveByDirectURLRequest { @@ -2845,6 +2880,13 @@ export declare namespace BrandRetrieveParams { * Request deadline and what to return when it passes. */ timeoutOpts?: BrandRetrieveFromTransactionRequest.TimeoutOpts; + + /** + * `enabled` disables request logs, usage logs, and traces. Brand data and hosted + * assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your + * organization has ZDR. + */ + zdr?: 'enabled' | 'disabled'; } export namespace BrandRetrieveFromTransactionRequest { diff --git a/src/resources/web.ts b/src/resources/web.ts index f0a29d26..57c713e1 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2280,8 +2280,9 @@ export interface WebExtractStyleguideParams { timeoutOpts?: WebExtractStyleguideParams.TimeoutOpts; /** - * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless - * your organization has ZDR. + * `enabled` disables request logs, usage logs, and traces. Brand data and hosted + * assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your + * organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } diff --git a/tests/api-resources/brand.test.ts b/tests/api-resources/brand.test.ts index a872dbbc..434fd0fb 100644 --- a/tests/api-resources/brand.test.ts +++ b/tests/api-resources/brand.test.ts @@ -31,6 +31,7 @@ describe('resource brand', () => { policies: ['pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e'], tags: ['production', 'team-alpha'], timeoutOpts: { milliseconds: 1000, behavior: 'fail' }, + zdr: 'enabled', }); }); From 4a96b45d64fbd0b9278205772e170ef81b49fb51 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 28 Oct 2026 16:59:44 +0000 Subject: [PATCH 197/232] fix(openapi): keep legacy batch inputs in the spec as deprecated (#2225) feat(access-policies): limit which websites API requests can reach (#2213) feat(brand): support log-free brand and styleguide requests (#2231) fix(brand): keep metadata-only usage logs for ZDR brand requests (#2234) Stainless-Generated-From: 136823494220cf63e54013502552677cca3bf2f5 --- src/resources/brand.ts | 36 ++++++++++++++++++------------------ src/resources/web.ts | 6 +++--- 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/src/resources/brand.ts b/src/resources/brand.ts index a567756b..e8b2844b 100644 --- a/src/resources/brand.ts +++ b/src/resources/brand.ts @@ -1493,9 +1493,9 @@ export declare namespace BrandRetrieveParams { timeoutOpts?: BrandRetrieveByDomainRequest.TimeoutOpts; /** - * `enabled` disables request logs, usage logs, and traces. Brand data and hosted - * assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your - * organization has ZDR. + * `enabled` disables request logs and traces and omits request and response + * content from usage logs. Brand data and hosted assets may still be stored. + * Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } @@ -1926,9 +1926,9 @@ export declare namespace BrandRetrieveParams { timeoutOpts?: BrandRetrieveByNameRequest.TimeoutOpts; /** - * `enabled` disables request logs, usage logs, and traces. Brand data and hosted - * assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your - * organization has ZDR. + * `enabled` disables request logs and traces and omits request and response + * content from usage logs. Brand data and hosted assets may still be stored. + * Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } @@ -2114,9 +2114,9 @@ export declare namespace BrandRetrieveParams { timeoutOpts?: BrandRetrieveByEmailRequest.TimeoutOpts; /** - * `enabled` disables request logs, usage logs, and traces. Brand data and hosted - * assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your - * organization has ZDR. + * `enabled` disables request logs and traces and omits request and response + * content from usage logs. Brand data and hosted assets may still be stored. + * Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } @@ -2379,9 +2379,9 @@ export declare namespace BrandRetrieveParams { timeoutOpts?: BrandRetrieveByTickerRequest.TimeoutOpts; /** - * `enabled` disables request logs, usage logs, and traces. Brand data and hosted - * assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your - * organization has ZDR. + * `enabled` disables request logs and traces and omits request and response + * content from usage logs. Brand data and hosted assets may still be stored. + * Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } @@ -2433,9 +2433,9 @@ export declare namespace BrandRetrieveParams { timeoutOpts?: BrandRetrieveByDirectURLRequest.TimeoutOpts; /** - * `enabled` disables request logs, usage logs, and traces. Brand data and hosted - * assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your - * organization has ZDR. + * `enabled` disables request logs and traces and omits request and response + * content from usage logs. Brand data and hosted assets may still be stored. + * Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } @@ -2882,9 +2882,9 @@ export declare namespace BrandRetrieveParams { timeoutOpts?: BrandRetrieveFromTransactionRequest.TimeoutOpts; /** - * `enabled` disables request logs, usage logs, and traces. Brand data and hosted - * assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your - * organization has ZDR. + * `enabled` disables request logs and traces and omits request and response + * content from usage logs. Brand data and hosted assets may still be stored. + * Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } diff --git a/src/resources/web.ts b/src/resources/web.ts index 57c713e1..bdb6f4a4 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2280,9 +2280,9 @@ export interface WebExtractStyleguideParams { timeoutOpts?: WebExtractStyleguideParams.TimeoutOpts; /** - * `enabled` disables request logs, usage logs, and traces. Brand data and hosted - * assets may still be stored. Returns 403 `ZDR_NOT_ENABLED` unless your - * organization has ZDR. + * `enabled` disables request logs and traces and omits request and response + * content from usage logs. Brand data and hosted assets may still be stored. + * Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR. */ zdr?: 'enabled' | 'disabled'; } From ff77d900714bdbbfc8f4db32f07bc81421b25ac7 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 28 Oct 2026 17:23:19 +0000 Subject: [PATCH 198/232] fix(openapi): keep legacy batch inputs in the spec as deprecated (#2225) feat(access-policies): limit which websites API requests can reach (#2213) feat(brand): support log-free brand and styleguide requests (#2231) fix(brand): keep metadata-only usage logs for ZDR brand requests (#2234) feat(monitors): add search target to watch the web for new developments (#2215) Stainless-Generated-From: eceb540c1c8adf854d49b72d6a940467d6b8bbea --- src/resources/monitors.ts | 483 +++++++++++++++++++++++++++++++++----- 1 file changed, 429 insertions(+), 54 deletions(-) diff --git a/src/resources/monitors.ts b/src/resources/monitors.ts index 06df3085..0f234acb 100644 --- a/src/resources/monitors.ts +++ b/src/resources/monitors.ts @@ -302,8 +302,8 @@ export interface MonitorCreateResponse { id: string; /** - * How changes are judged. Defaults to `semantic` for extract targets and page - * targets with `instructions`, otherwise `exact`. + * How changes are judged. Defaults to `semantic` for extract and search targets + * and page targets with `instructions`, otherwise `exact`. */ change_detection: | MonitorCreateResponse.MonitorsExactChangeDetection @@ -337,12 +337,14 @@ export interface MonitorCreateResponse { status: 'active' | 'paused' | 'failed'; /** - * What to watch: a page, a sitemap, or data extracted from a site. + * What to watch: a page, a sitemap, data extracted from a site, or web search + * results. */ target: | MonitorCreateResponse.MonitorsPageTarget | MonitorCreateResponse.MonitorsSitemapTarget - | MonitorCreateResponse.MonitorsExtractTarget; + | MonitorCreateResponse.MonitorsExtractTarget + | MonitorCreateResponse.MonitorsSearchTarget; updated_at: string; @@ -354,6 +356,7 @@ export interface MonitorCreateResponse { | MonitorCreateResponse.MonitorsPageBaseline | MonitorCreateResponse.MonitorsSitemapBaseline | MonitorCreateResponse.MonitorsExtractBaseline + | MonitorCreateResponse.MonitorsSearchBaseline | null; /** @@ -408,11 +411,12 @@ export interface MonitorCreateResponse { export namespace MonitorCreateResponse { /** * Detect exact changes. For page targets, this means visible text diffs. For - * sitemap targets, this means URL additions and removals. + * sitemap targets, this means URL additions and removals. For search targets, this + * means every new result. */ export interface MonitorsExactChangeDetection { /** - * Use `exact` to compare visible text or sitemap URLs. + * Use `exact` to compare visible text, sitemap URLs, or search results. */ type: 'exact'; } @@ -620,6 +624,30 @@ export namespace MonitorCreateResponse { schema?: { [key: string]: unknown }; } + /** + * Search the web on every run and report results not seen before, listed in the + * change’s `matched_urls` and `evidence`. Semantic detection reports only results + * describing a new development that matches `instructions`; exact detection + * reports every new result. + */ + export interface MonitorsSearchTarget { + /** + * Web search query to run on every check. Supports operators such as `site:`, + * `-site:`, and quoted phrases. + */ + query: string; + + /** + * Use `search` to watch the whole web for new results about a topic. + */ + type: 'search'; + + /** + * Plain-language description of which new results matter. Defaults to the query. + */ + instructions?: string; + } + /** * Current baseline of a `page` monitor: the visible page text as last observed. */ @@ -678,6 +706,39 @@ export namespace MonitorCreateResponse { urls_analyzed: Array; } + /** + * Current baseline of a `search` monitor: the search results as last observed. + */ + export interface MonitorsSearchBaseline { + /** + * When this baseline was last captured or replaced. + */ + captured_at: string; + + /** + * Search results as last observed. + */ + results: Array; + } + + export namespace MonitorsSearchBaseline { + export interface Result { + /** + * Result snippet. + */ + description: string; + + /** + * When the result was published, when known. + */ + published_at: string | null; + + title: string; + + url: string; + } + } + /** * Credits this request used and your remaining balance. */ @@ -785,8 +846,8 @@ export interface MonitorRetrieveResponse { id: string; /** - * How changes are judged. Defaults to `semantic` for extract targets and page - * targets with `instructions`, otherwise `exact`. + * How changes are judged. Defaults to `semantic` for extract and search targets + * and page targets with `instructions`, otherwise `exact`. */ change_detection: | MonitorRetrieveResponse.MonitorsExactChangeDetection @@ -814,12 +875,14 @@ export interface MonitorRetrieveResponse { status: 'active' | 'paused' | 'failed'; /** - * What to watch: a page, a sitemap, or data extracted from a site. + * What to watch: a page, a sitemap, data extracted from a site, or web search + * results. */ target: | MonitorRetrieveResponse.MonitorsPageTarget | MonitorRetrieveResponse.MonitorsSitemapTarget - | MonitorRetrieveResponse.MonitorsExtractTarget; + | MonitorRetrieveResponse.MonitorsExtractTarget + | MonitorRetrieveResponse.MonitorsSearchTarget; updated_at: string; @@ -831,6 +894,7 @@ export interface MonitorRetrieveResponse { | MonitorRetrieveResponse.MonitorsPageBaseline | MonitorRetrieveResponse.MonitorsSitemapBaseline | MonitorRetrieveResponse.MonitorsExtractBaseline + | MonitorRetrieveResponse.MonitorsSearchBaseline | null; /** @@ -885,11 +949,12 @@ export interface MonitorRetrieveResponse { export namespace MonitorRetrieveResponse { /** * Detect exact changes. For page targets, this means visible text diffs. For - * sitemap targets, this means URL additions and removals. + * sitemap targets, this means URL additions and removals. For search targets, this + * means every new result. */ export interface MonitorsExactChangeDetection { /** - * Use `exact` to compare visible text or sitemap URLs. + * Use `exact` to compare visible text, sitemap URLs, or search results. */ type: 'exact'; } @@ -1097,6 +1162,30 @@ export namespace MonitorRetrieveResponse { schema?: { [key: string]: unknown }; } + /** + * Search the web on every run and report results not seen before, listed in the + * change’s `matched_urls` and `evidence`. Semantic detection reports only results + * describing a new development that matches `instructions`; exact detection + * reports every new result. + */ + export interface MonitorsSearchTarget { + /** + * Web search query to run on every check. Supports operators such as `site:`, + * `-site:`, and quoted phrases. + */ + query: string; + + /** + * Use `search` to watch the whole web for new results about a topic. + */ + type: 'search'; + + /** + * Plain-language description of which new results matter. Defaults to the query. + */ + instructions?: string; + } + /** * Current baseline of a `page` monitor: the visible page text as last observed. */ @@ -1155,6 +1244,39 @@ export namespace MonitorRetrieveResponse { urls_analyzed: Array; } + /** + * Current baseline of a `search` monitor: the search results as last observed. + */ + export interface MonitorsSearchBaseline { + /** + * When this baseline was last captured or replaced. + */ + captured_at: string; + + /** + * Search results as last observed. + */ + results: Array; + } + + export namespace MonitorsSearchBaseline { + export interface Result { + /** + * Result snippet. + */ + description: string; + + /** + * When the result was published, when known. + */ + published_at: string | null; + + title: string; + + url: string; + } + } + /** * Credits this request used and your remaining balance. */ @@ -1262,8 +1384,8 @@ export interface MonitorUpdateResponse { id: string; /** - * How changes are judged. Defaults to `semantic` for extract targets and page - * targets with `instructions`, otherwise `exact`. + * How changes are judged. Defaults to `semantic` for extract and search targets + * and page targets with `instructions`, otherwise `exact`. */ change_detection: | MonitorUpdateResponse.MonitorsExactChangeDetection @@ -1291,12 +1413,14 @@ export interface MonitorUpdateResponse { status: 'active' | 'paused' | 'failed'; /** - * What to watch: a page, a sitemap, or data extracted from a site. + * What to watch: a page, a sitemap, data extracted from a site, or web search + * results. */ target: | MonitorUpdateResponse.MonitorsPageTarget | MonitorUpdateResponse.MonitorsSitemapTarget - | MonitorUpdateResponse.MonitorsExtractTarget; + | MonitorUpdateResponse.MonitorsExtractTarget + | MonitorUpdateResponse.MonitorsSearchTarget; updated_at: string; @@ -1308,6 +1432,7 @@ export interface MonitorUpdateResponse { | MonitorUpdateResponse.MonitorsPageBaseline | MonitorUpdateResponse.MonitorsSitemapBaseline | MonitorUpdateResponse.MonitorsExtractBaseline + | MonitorUpdateResponse.MonitorsSearchBaseline | null; /** @@ -1362,11 +1487,12 @@ export interface MonitorUpdateResponse { export namespace MonitorUpdateResponse { /** * Detect exact changes. For page targets, this means visible text diffs. For - * sitemap targets, this means URL additions and removals. + * sitemap targets, this means URL additions and removals. For search targets, this + * means every new result. */ export interface MonitorsExactChangeDetection { /** - * Use `exact` to compare visible text or sitemap URLs. + * Use `exact` to compare visible text, sitemap URLs, or search results. */ type: 'exact'; } @@ -1574,6 +1700,30 @@ export namespace MonitorUpdateResponse { schema?: { [key: string]: unknown }; } + /** + * Search the web on every run and report results not seen before, listed in the + * change’s `matched_urls` and `evidence`. Semantic detection reports only results + * describing a new development that matches `instructions`; exact detection + * reports every new result. + */ + export interface MonitorsSearchTarget { + /** + * Web search query to run on every check. Supports operators such as `site:`, + * `-site:`, and quoted phrases. + */ + query: string; + + /** + * Use `search` to watch the whole web for new results about a topic. + */ + type: 'search'; + + /** + * Plain-language description of which new results matter. Defaults to the query. + */ + instructions?: string; + } + /** * Current baseline of a `page` monitor: the visible page text as last observed. */ @@ -1632,6 +1782,39 @@ export namespace MonitorUpdateResponse { urls_analyzed: Array; } + /** + * Current baseline of a `search` monitor: the search results as last observed. + */ + export interface MonitorsSearchBaseline { + /** + * When this baseline was last captured or replaced. + */ + captured_at: string; + + /** + * Search results as last observed. + */ + results: Array; + } + + export namespace MonitorsSearchBaseline { + export interface Result { + /** + * Result snippet. + */ + description: string; + + /** + * When the result was published, when known. + */ + published_at: string | null; + + title: string; + + url: string; + } + } + /** * Credits this request used and your remaining balance. */ @@ -1757,14 +1940,14 @@ export interface MonitorListResponse { export namespace MonitorListResponse { /** * A web monitor. `mode` is the constant `web`; behavior is described by `target` - * (page/sitemap/extract) and `change_detection` (exact/semantic). + * (page/sitemap/extract/search) and `change_detection` (exact/semantic). */ export interface Data { id: string; /** - * How changes are judged. Defaults to `semantic` for extract targets and page - * targets with `instructions`, otherwise `exact`. + * How changes are judged. Defaults to `semantic` for extract and search targets + * and page targets with `instructions`, otherwise `exact`. */ change_detection: Data.MonitorsExactChangeDetection | Data.MonitorsSemanticChangeDetection; @@ -1791,9 +1974,14 @@ export namespace MonitorListResponse { status: 'active' | 'paused' | 'failed'; /** - * What to watch: a page, a sitemap, or data extracted from a site. + * What to watch: a page, a sitemap, data extracted from a site, or web search + * results. */ - target: Data.MonitorsPageTarget | Data.MonitorsSitemapTarget | Data.MonitorsExtractTarget; + target: + | Data.MonitorsPageTarget + | Data.MonitorsSitemapTarget + | Data.MonitorsExtractTarget + | Data.MonitorsSearchTarget; updated_at: string; @@ -1801,7 +1989,12 @@ export namespace MonitorListResponse { * Comparison baseline, included on Retrieve. Null until capture completes or after * target changes. */ - baseline?: Data.MonitorsPageBaseline | Data.MonitorsSitemapBaseline | Data.MonitorsExtractBaseline | null; + baseline?: + | Data.MonitorsPageBaseline + | Data.MonitorsSitemapBaseline + | Data.MonitorsExtractBaseline + | Data.MonitorsSearchBaseline + | null; last_change_at?: string | null; @@ -1843,11 +2036,12 @@ export namespace MonitorListResponse { export namespace Data { /** * Detect exact changes. For page targets, this means visible text diffs. For - * sitemap targets, this means URL additions and removals. + * sitemap targets, this means URL additions and removals. For search targets, this + * means every new result. */ export interface MonitorsExactChangeDetection { /** - * Use `exact` to compare visible text or sitemap URLs. + * Use `exact` to compare visible text, sitemap URLs, or search results. */ type: 'exact'; } @@ -2079,6 +2273,30 @@ export namespace MonitorListResponse { schema?: { [key: string]: unknown }; } + /** + * Search the web on every run and report results not seen before, listed in the + * change’s `matched_urls` and `evidence`. Semantic detection reports only results + * describing a new development that matches `instructions`; exact detection + * reports every new result. + */ + export interface MonitorsSearchTarget { + /** + * Web search query to run on every check. Supports operators such as `site:`, + * `-site:`, and quoted phrases. + */ + query: string; + + /** + * Use `search` to watch the whole web for new results about a topic. + */ + type: 'search'; + + /** + * Plain-language description of which new results matter. Defaults to the query. + */ + instructions?: string; + } + /** * Current baseline of a `page` monitor: the visible page text as last observed. */ @@ -2137,6 +2355,39 @@ export namespace MonitorListResponse { urls_analyzed: Array; } + /** + * Current baseline of a `search` monitor: the search results as last observed. + */ + export interface MonitorsSearchBaseline { + /** + * When this baseline was last captured or replaced. + */ + captured_at: string; + + /** + * Search results as last observed. + */ + results: Array; + } + + export namespace MonitorsSearchBaseline { + export interface Result { + /** + * Result snippet. + */ + description: string; + + /** + * When the result was published, when known. + */ + published_at: string | null; + + title: string; + + url: string; + } + } + /** * Error from the most recent failed run; null when the last run succeeded. */ @@ -2402,10 +2653,13 @@ export namespace MonitorListAccountChangesResponse { */ tags: Array; - target_type: 'page' | 'sitemap' | 'extract'; + target_type: 'page' | 'sitemap' | 'extract' | 'search'; title: string; + /** + * The monitored URL. For search targets, the first newly reported result. + */ url: string; added_url_count?: number; @@ -2531,7 +2785,7 @@ export namespace MonitorListAccountRunsResponse { */ status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; - target_type: 'page' | 'sitemap' | 'extract'; + target_type: 'page' | 'sitemap' | 'extract' | 'search'; change_id?: string | null; @@ -2637,10 +2891,13 @@ export namespace MonitorListChangesResponse { */ tags: Array; - target_type: 'page' | 'sitemap' | 'extract'; + target_type: 'page' | 'sitemap' | 'extract' | 'search'; title: string; + /** + * The monitored URL. For search targets, the first newly reported result. + */ url: string; added_url_count?: number; @@ -2766,7 +3023,7 @@ export namespace MonitorListRunsResponse { */ status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; - target_type: 'page' | 'sitemap' | 'extract'; + target_type: 'page' | 'sitemap' | 'extract' | 'search'; change_id?: string | null; @@ -2855,10 +3112,13 @@ export interface MonitorRetrieveChangeResponse { */ tags: Array; - target_type: 'page' | 'sitemap' | 'extract'; + target_type: 'page' | 'sitemap' | 'extract' | 'search'; title: string; + /** + * The monitored URL. For search targets, the first newly reported result. + */ url: string; added_url_count?: number; @@ -2974,7 +3234,7 @@ export interface MonitorRetrieveRunResponse { */ status: 'queued' | 'running' | 'completed' | 'failed' | 'skipped'; - target_type: 'page' | 'sitemap' | 'extract'; + target_type: 'page' | 'sitemap' | 'extract' | 'search'; change_id?: string | null; @@ -3039,8 +3299,8 @@ export interface MonitorRotateWebhookSecretResponse { id: string; /** - * How changes are judged. Defaults to `semantic` for extract targets and page - * targets with `instructions`, otherwise `exact`. + * How changes are judged. Defaults to `semantic` for extract and search targets + * and page targets with `instructions`, otherwise `exact`. */ change_detection: | MonitorRotateWebhookSecretResponse.MonitorsExactChangeDetection @@ -3068,12 +3328,14 @@ export interface MonitorRotateWebhookSecretResponse { status: 'active' | 'paused' | 'failed'; /** - * What to watch: a page, a sitemap, or data extracted from a site. + * What to watch: a page, a sitemap, data extracted from a site, or web search + * results. */ target: | MonitorRotateWebhookSecretResponse.MonitorsPageTarget | MonitorRotateWebhookSecretResponse.MonitorsSitemapTarget - | MonitorRotateWebhookSecretResponse.MonitorsExtractTarget; + | MonitorRotateWebhookSecretResponse.MonitorsExtractTarget + | MonitorRotateWebhookSecretResponse.MonitorsSearchTarget; updated_at: string; @@ -3085,6 +3347,7 @@ export interface MonitorRotateWebhookSecretResponse { | MonitorRotateWebhookSecretResponse.MonitorsPageBaseline | MonitorRotateWebhookSecretResponse.MonitorsSitemapBaseline | MonitorRotateWebhookSecretResponse.MonitorsExtractBaseline + | MonitorRotateWebhookSecretResponse.MonitorsSearchBaseline | null; /** @@ -3139,11 +3402,12 @@ export interface MonitorRotateWebhookSecretResponse { export namespace MonitorRotateWebhookSecretResponse { /** * Detect exact changes. For page targets, this means visible text diffs. For - * sitemap targets, this means URL additions and removals. + * sitemap targets, this means URL additions and removals. For search targets, this + * means every new result. */ export interface MonitorsExactChangeDetection { /** - * Use `exact` to compare visible text or sitemap URLs. + * Use `exact` to compare visible text, sitemap URLs, or search results. */ type: 'exact'; } @@ -3351,6 +3615,30 @@ export namespace MonitorRotateWebhookSecretResponse { schema?: { [key: string]: unknown }; } + /** + * Search the web on every run and report results not seen before, listed in the + * change’s `matched_urls` and `evidence`. Semantic detection reports only results + * describing a new development that matches `instructions`; exact detection + * reports every new result. + */ + export interface MonitorsSearchTarget { + /** + * Web search query to run on every check. Supports operators such as `site:`, + * `-site:`, and quoted phrases. + */ + query: string; + + /** + * Use `search` to watch the whole web for new results about a topic. + */ + type: 'search'; + + /** + * Plain-language description of which new results matter. Defaults to the query. + */ + instructions?: string; + } + /** * Current baseline of a `page` monitor: the visible page text as last observed. */ @@ -3409,6 +3697,39 @@ export namespace MonitorRotateWebhookSecretResponse { urls_analyzed: Array; } + /** + * Current baseline of a `search` monitor: the search results as last observed. + */ + export interface MonitorsSearchBaseline { + /** + * When this baseline was last captured or replaced. + */ + captured_at: string; + + /** + * Search results as last observed. + */ + results: Array; + } + + export namespace MonitorsSearchBaseline { + export interface Result { + /** + * Result snippet. + */ + description: string; + + /** + * When the result was published, when known. + */ + published_at: string | null; + + title: string; + + url: string; + } + } + /** * Credits this request used and your remaining balance. */ @@ -3558,16 +3879,18 @@ export interface MonitorCreateParams { name: string; /** - * What to watch: a page, a sitemap, or data extracted from a site. + * What to watch: a page, a sitemap, data extracted from a site, or web search + * results. */ target: | MonitorCreateParams.MonitorsPageTarget | MonitorCreateParams.MonitorsSitemapTarget - | MonitorCreateParams.MonitorsExtractTarget; + | MonitorCreateParams.MonitorsExtractTarget + | MonitorCreateParams.MonitorsSearchTarget; /** - * How changes are judged. Defaults to `semantic` for extract targets and page - * targets with `instructions`, otherwise `exact`. + * How changes are judged. Defaults to `semantic` for extract and search targets + * and page targets with `instructions`, otherwise `exact`. */ change_detection?: | MonitorCreateParams.MonitorsExactChangeDetection @@ -3789,13 +4112,38 @@ export namespace MonitorCreateParams { schema?: { [key: string]: unknown }; } + /** + * Search the web on every run and report results not seen before, listed in the + * change’s `matched_urls` and `evidence`. Semantic detection reports only results + * describing a new development that matches `instructions`; exact detection + * reports every new result. + */ + export interface MonitorsSearchTarget { + /** + * Web search query to run on every check. Supports operators such as `site:`, + * `-site:`, and quoted phrases. + */ + query: string; + + /** + * Use `search` to watch the whole web for new results about a topic. + */ + type: 'search'; + + /** + * Plain-language description of which new results matter. Defaults to the query. + */ + instructions?: string; + } + /** * Detect exact changes. For page targets, this means visible text diffs. For - * sitemap targets, this means URL additions and removals. + * sitemap targets, this means URL additions and removals. For search targets, this + * means every new result. */ export interface MonitorsExactChangeDetection { /** - * Use `exact` to compare visible text or sitemap URLs. + * Use `exact` to compare visible text, sitemap URLs, or search results. */ type: 'exact'; } @@ -3865,8 +4213,8 @@ export namespace MonitorCreateParams { export interface MonitorUpdateParams { /** - * How changes are judged. Defaults to `semantic` for extract targets and page - * targets with `instructions`, otherwise `exact`. + * How changes are judged. Defaults to `semantic` for extract and search targets + * and page targets with `instructions`, otherwise `exact`. */ change_detection?: | MonitorUpdateParams.MonitorsExactChangeDetection @@ -3900,12 +4248,14 @@ export interface MonitorUpdateParams { tags?: Array; /** - * What to watch: a page, a sitemap, or data extracted from a site. + * What to watch: a page, a sitemap, data extracted from a site, or web search + * results. */ target?: | MonitorUpdateParams.MonitorsPageTarget | MonitorUpdateParams.MonitorsSitemapTarget - | MonitorUpdateParams.MonitorsExtractTarget; + | MonitorUpdateParams.MonitorsExtractTarget + | MonitorUpdateParams.MonitorsSearchTarget; /** * Set to null to remove the webhook. Changing `url` issues a new secret. @@ -3916,11 +4266,12 @@ export interface MonitorUpdateParams { export namespace MonitorUpdateParams { /** * Detect exact changes. For page targets, this means visible text diffs. For - * sitemap targets, this means URL additions and removals. + * sitemap targets, this means URL additions and removals. For search targets, this + * means every new result. */ export interface MonitorsExactChangeDetection { /** - * Use `exact` to compare visible text or sitemap URLs. + * Use `exact` to compare visible text, sitemap URLs, or search results. */ type: 'exact'; } @@ -4152,6 +4503,30 @@ export namespace MonitorUpdateParams { schema?: { [key: string]: unknown }; } + /** + * Search the web on every run and report results not seen before, listed in the + * change’s `matched_urls` and `evidence`. Semantic detection reports only results + * describing a new development that matches `instructions`; exact detection + * reports every new result. + */ + export interface MonitorsSearchTarget { + /** + * Web search query to run on every check. Supports operators such as `site:`, + * `-site:`, and quoted phrases. + */ + query: string; + + /** + * Use `search` to watch the whole web for new results about a topic. + */ + type: 'search'; + + /** + * Plain-language description of which new results matter. Defaults to the query. + */ + instructions?: string; + } + /** * Set to null to remove the webhook. Changing `url` issues a new secret. */ @@ -4197,8 +4572,8 @@ export interface MonitorListParams { q?: string; /** - * Fields to search with `q`. Defaults to all fields; page and extract targets can - * have instructions. + * Fields to search with `q`. Defaults to all fields; page, extract, and search + * targets can have instructions, and `url` matches a search target’s query. */ search_by?: Array<'name' | 'url' | 'instructions' | 'tags'> | null; @@ -4226,7 +4601,7 @@ export interface MonitorListParams { /** * Filter by target type. */ - target_type?: 'page' | 'sitemap' | 'extract'; + target_type?: 'page' | 'sitemap' | 'extract' | 'search'; } export interface MonitorGetCreditUsageParams { @@ -4275,7 +4650,7 @@ export interface MonitorListAccountChangesParams { /** * Filter by target type. */ - target_type?: 'page' | 'sitemap' | 'extract'; + target_type?: 'page' | 'sitemap' | 'extract' | 'search'; /** * Only include items before this ISO 8601 timestamp. From 2e7cbf721079a86aaf706bca719f74ae26191ac4 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 28 Oct 2026 17:37:18 +0000 Subject: [PATCH 199/232] fix(openapi): keep legacy batch inputs in the spec as deprecated (#2225) feat(access-policies): limit which websites API requests can reach (#2213) feat(brand): support log-free brand and styleguide requests (#2231) fix(brand): keep metadata-only usage logs for ZDR brand requests (#2234) feat(monitors): add search target to watch the web for new developments (#2215) fix(scrape): restore Instagram profile posts from public pages (#2233) Stainless-Generated-From: 222486c30b5adc12915f1253c4304ed1f04a5025 --- src/resources/batch.ts | 60 ++++++++++++++++++++++++------------------ src/resources/web.ts | 30 ++++++++++++--------- 2 files changed, 51 insertions(+), 39 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 8d9eaca9..0c3c0043 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -3918,19 +3918,23 @@ export namespace BatchSubmitParams { * (filters[nps_score][]=1 to 5); other filters, sort orders, and pages are * ignored. instagram-profile parses a public profile (instagram.com/{username}) * into data: bio, links, follower and post counts, category, business address, - * similar_accounts, and latest_posts (the 12 newest). instagram-post parses a post - * or reel (/p/…, /reel/…) into data: caption, hashtags, mentions, like, comment, - * and view counts, media URLs, tagged users, collaborators, location, and the top - * ~14 comments in data.comments. instagram-feed returns the top posts for a - * hashtag or keyword (/explore/tags/…, /popular/…) or the recent posts at a - * location (/explore/locations/{id}/…) in data.posts; keyword posts carry only the - * shortcode, owner, thumbnail, and views, plus the caption when Instagram shows - * it. All three Instagram parsers read public data without logging in, so private - * accounts return no posts and follower lists are unavailable. tiktok-profile - * parses a public profile (tiktok.com/@{username}) into data: nickname, bio, bio - * link, follower, following, like, and video counts, verified, private, and - * business flags, and business category; it does not list videos. tiktok-video - * parses a video or photo post (/@{username}/video/{id} or + * similar_accounts, and latest_posts (up to the 12 posts at the top of the + * profile, newest first). Instagram lists pinned posts there ahead of newer ones, + * so posts with is_pinned true can be older; when Instagram shows only a rounded + * post count (32K), post_count is that rounded number and is_post_count_rounded is + * true. instagram-post parses a post or reel (/p/…, /reel/…) into data: caption, + * hashtags, mentions, like, comment, and view counts (like_count and view_count + * are null when the owner hides them), media URLs, tagged users, collaborators, + * location, and the top ~14 comments in data.comments. instagram-feed returns the + * top posts for a hashtag or keyword (/explore/tags/…, /popular/…) or the recent + * posts at a location (/explore/locations/{id}/…) in data.posts; keyword posts + * carry only the shortcode, owner, thumbnail, and views, plus the caption when + * Instagram shows it. All three Instagram parsers read public data without logging + * in, so private accounts return no posts and follower lists are unavailable. + * tiktok-profile parses a public profile (tiktok.com/@{username}) into data: + * nickname, bio, bio link, follower, following, like, and video counts, verified, + * private, and business flags, and business category; it does not list videos. + * tiktok-video parses a video or photo post (/@{username}/video/{id} or * /@{username}/photo/{id}) into data: caption, hashtags, mentions, author, view, * like, comment, share, save, and repost counts, duration, thumbnail, a video_url * that downloads without cookies, image_urls for photo posts, music, location, and @@ -5778,19 +5782,23 @@ export namespace BatchSubmitParams { * (filters[nps_score][]=1 to 5); other filters, sort orders, and pages are * ignored. instagram-profile parses a public profile (instagram.com/{username}) * into data: bio, links, follower and post counts, category, business address, - * similar_accounts, and latest_posts (the 12 newest). instagram-post parses a post - * or reel (/p/…, /reel/…) into data: caption, hashtags, mentions, like, comment, - * and view counts, media URLs, tagged users, collaborators, location, and the top - * ~14 comments in data.comments. instagram-feed returns the top posts for a - * hashtag or keyword (/explore/tags/…, /popular/…) or the recent posts at a - * location (/explore/locations/{id}/…) in data.posts; keyword posts carry only the - * shortcode, owner, thumbnail, and views, plus the caption when Instagram shows - * it. All three Instagram parsers read public data without logging in, so private - * accounts return no posts and follower lists are unavailable. tiktok-profile - * parses a public profile (tiktok.com/@{username}) into data: nickname, bio, bio - * link, follower, following, like, and video counts, verified, private, and - * business flags, and business category; it does not list videos. tiktok-video - * parses a video or photo post (/@{username}/video/{id} or + * similar_accounts, and latest_posts (up to the 12 posts at the top of the + * profile, newest first). Instagram lists pinned posts there ahead of newer ones, + * so posts with is_pinned true can be older; when Instagram shows only a rounded + * post count (32K), post_count is that rounded number and is_post_count_rounded is + * true. instagram-post parses a post or reel (/p/…, /reel/…) into data: caption, + * hashtags, mentions, like, comment, and view counts (like_count and view_count + * are null when the owner hides them), media URLs, tagged users, collaborators, + * location, and the top ~14 comments in data.comments. instagram-feed returns the + * top posts for a hashtag or keyword (/explore/tags/…, /popular/…) or the recent + * posts at a location (/explore/locations/{id}/…) in data.posts; keyword posts + * carry only the shortcode, owner, thumbnail, and views, plus the caption when + * Instagram shows it. All three Instagram parsers read public data without logging + * in, so private accounts return no posts and follower lists are unavailable. + * tiktok-profile parses a public profile (tiktok.com/@{username}) into data: + * nickname, bio, bio link, follower, following, like, and video counts, verified, + * private, and business flags, and business category; it does not list videos. + * tiktok-video parses a video or photo post (/@{username}/video/{id} or * /@{username}/photo/{id}) into data: caption, hashtags, mentions, author, view, * like, comment, share, save, and repost counts, duration, thumbnail, a video_url * that downloads without cookies, image_urls for photo posts, music, location, and diff --git a/src/resources/web.ts b/src/resources/web.ts index bdb6f4a4..2fded2c0 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2653,19 +2653,23 @@ export namespace WebScrapeParams { * (filters[nps_score][]=1 to 5); other filters, sort orders, and pages are * ignored. instagram-profile parses a public profile (instagram.com/{username}) * into data: bio, links, follower and post counts, category, business address, - * similar_accounts, and latest_posts (the 12 newest). instagram-post parses a post - * or reel (/p/…, /reel/…) into data: caption, hashtags, mentions, like, comment, - * and view counts, media URLs, tagged users, collaborators, location, and the top - * ~14 comments in data.comments. instagram-feed returns the top posts for a - * hashtag or keyword (/explore/tags/…, /popular/…) or the recent posts at a - * location (/explore/locations/{id}/…) in data.posts; keyword posts carry only the - * shortcode, owner, thumbnail, and views, plus the caption when Instagram shows - * it. All three Instagram parsers read public data without logging in, so private - * accounts return no posts and follower lists are unavailable. tiktok-profile - * parses a public profile (tiktok.com/@{username}) into data: nickname, bio, bio - * link, follower, following, like, and video counts, verified, private, and - * business flags, and business category; it does not list videos. tiktok-video - * parses a video or photo post (/@{username}/video/{id} or + * similar_accounts, and latest_posts (up to the 12 posts at the top of the + * profile, newest first). Instagram lists pinned posts there ahead of newer ones, + * so posts with is_pinned true can be older; when Instagram shows only a rounded + * post count (32K), post_count is that rounded number and is_post_count_rounded is + * true. instagram-post parses a post or reel (/p/…, /reel/…) into data: caption, + * hashtags, mentions, like, comment, and view counts (like_count and view_count + * are null when the owner hides them), media URLs, tagged users, collaborators, + * location, and the top ~14 comments in data.comments. instagram-feed returns the + * top posts for a hashtag or keyword (/explore/tags/…, /popular/…) or the recent + * posts at a location (/explore/locations/{id}/…) in data.posts; keyword posts + * carry only the shortcode, owner, thumbnail, and views, plus the caption when + * Instagram shows it. All three Instagram parsers read public data without logging + * in, so private accounts return no posts and follower lists are unavailable. + * tiktok-profile parses a public profile (tiktok.com/@{username}) into data: + * nickname, bio, bio link, follower, following, like, and video counts, verified, + * private, and business flags, and business category; it does not list videos. + * tiktok-video parses a video or photo post (/@{username}/video/{id} or * /@{username}/photo/{id}) into data: caption, hashtags, mentions, author, view, * like, comment, share, save, and repost counts, duration, thumbnail, a video_url * that downloads without cookies, image_urls for photo posts, music, location, and From a3cf068c3c42c535a6284f12fa6fa65e8b07bdef Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Wed, 28 Oct 2026 20:17:34 +0100 Subject: [PATCH 200/232] release: 3.19.0 (#105) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 31 +++++++++++++++++++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 34 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index da0b97f9..60a50ee6 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.18.0" + ".": "3.19.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index e37e7875..fca680ff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,36 @@ # Changelog +## [3.19.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.18.0...v3.19.0) (2026-10-28) + + +### Features + +* **access-policies:** limit which websites API requests can reach ([#2213](https://github.com/context-dot-dev/context-typescript-sdk/issues/2213)) ([2e7cbf7](https://github.com/context-dot-dev/context-typescript-sdk/commit/2e7cbf721079a86aaf706bca719f74ae26191ac4)) +* **access-policies:** limit which websites API requests can reach ([#2213](https://github.com/context-dot-dev/context-typescript-sdk/issues/2213)) ([ff77d90](https://github.com/context-dot-dev/context-typescript-sdk/commit/ff77d900714bdbbfc8f4db32f07bc81421b25ac7)) +* **access-policies:** limit which websites API requests can reach ([#2213](https://github.com/context-dot-dev/context-typescript-sdk/issues/2213)) ([4a96b45](https://github.com/context-dot-dev/context-typescript-sdk/commit/4a96b45d64fbd0b9278205772e170ef81b49fb51)) +* **access-policies:** limit which websites API requests can reach ([#2213](https://github.com/context-dot-dev/context-typescript-sdk/issues/2213)) ([93ccc89](https://github.com/context-dot-dev/context-typescript-sdk/commit/93ccc892b4758e3ac4b2ad0954738f075d362655)) +* **access-policies:** limit which websites API requests can reach ([#2213](https://github.com/context-dot-dev/context-typescript-sdk/issues/2213)) ([e96b8e6](https://github.com/context-dot-dev/context-typescript-sdk/commit/e96b8e6833971894877b28e03e04486cedfa8a7c)) +* **brand:** support log-free brand and styleguide requests ([#2231](https://github.com/context-dot-dev/context-typescript-sdk/issues/2231)) ([2e7cbf7](https://github.com/context-dot-dev/context-typescript-sdk/commit/2e7cbf721079a86aaf706bca719f74ae26191ac4)) +* **brand:** support log-free brand and styleguide requests ([#2231](https://github.com/context-dot-dev/context-typescript-sdk/issues/2231)) ([ff77d90](https://github.com/context-dot-dev/context-typescript-sdk/commit/ff77d900714bdbbfc8f4db32f07bc81421b25ac7)) +* **brand:** support log-free brand and styleguide requests ([#2231](https://github.com/context-dot-dev/context-typescript-sdk/issues/2231)) ([4a96b45](https://github.com/context-dot-dev/context-typescript-sdk/commit/4a96b45d64fbd0b9278205772e170ef81b49fb51)) +* **brand:** support log-free brand and styleguide requests ([#2231](https://github.com/context-dot-dev/context-typescript-sdk/issues/2231)) ([93ccc89](https://github.com/context-dot-dev/context-typescript-sdk/commit/93ccc892b4758e3ac4b2ad0954738f075d362655)) +* **monitors:** add search target to watch the web for new developments ([#2215](https://github.com/context-dot-dev/context-typescript-sdk/issues/2215)) ([2e7cbf7](https://github.com/context-dot-dev/context-typescript-sdk/commit/2e7cbf721079a86aaf706bca719f74ae26191ac4)) +* **monitors:** add search target to watch the web for new developments ([#2215](https://github.com/context-dot-dev/context-typescript-sdk/issues/2215)) ([ff77d90](https://github.com/context-dot-dev/context-typescript-sdk/commit/ff77d900714bdbbfc8f4db32f07bc81421b25ac7)) + + +### Bug Fixes + +* **brand:** keep metadata-only usage logs for ZDR brand requests ([#2234](https://github.com/context-dot-dev/context-typescript-sdk/issues/2234)) ([2e7cbf7](https://github.com/context-dot-dev/context-typescript-sdk/commit/2e7cbf721079a86aaf706bca719f74ae26191ac4)) +* **brand:** keep metadata-only usage logs for ZDR brand requests ([#2234](https://github.com/context-dot-dev/context-typescript-sdk/issues/2234)) ([ff77d90](https://github.com/context-dot-dev/context-typescript-sdk/commit/ff77d900714bdbbfc8f4db32f07bc81421b25ac7)) +* **brand:** keep metadata-only usage logs for ZDR brand requests ([#2234](https://github.com/context-dot-dev/context-typescript-sdk/issues/2234)) ([4a96b45](https://github.com/context-dot-dev/context-typescript-sdk/commit/4a96b45d64fbd0b9278205772e170ef81b49fb51)) +* **openapi:** keep legacy batch inputs in the spec as deprecated ([#2225](https://github.com/context-dot-dev/context-typescript-sdk/issues/2225)) ([2e7cbf7](https://github.com/context-dot-dev/context-typescript-sdk/commit/2e7cbf721079a86aaf706bca719f74ae26191ac4)) +* **openapi:** keep legacy batch inputs in the spec as deprecated ([#2225](https://github.com/context-dot-dev/context-typescript-sdk/issues/2225)) ([ff77d90](https://github.com/context-dot-dev/context-typescript-sdk/commit/ff77d900714bdbbfc8f4db32f07bc81421b25ac7)) +* **openapi:** keep legacy batch inputs in the spec as deprecated ([#2225](https://github.com/context-dot-dev/context-typescript-sdk/issues/2225)) ([4a96b45](https://github.com/context-dot-dev/context-typescript-sdk/commit/4a96b45d64fbd0b9278205772e170ef81b49fb51)) +* **openapi:** keep legacy batch inputs in the spec as deprecated ([#2225](https://github.com/context-dot-dev/context-typescript-sdk/issues/2225)) ([93ccc89](https://github.com/context-dot-dev/context-typescript-sdk/commit/93ccc892b4758e3ac4b2ad0954738f075d362655)) +* **openapi:** keep legacy batch inputs in the spec as deprecated ([#2225](https://github.com/context-dot-dev/context-typescript-sdk/issues/2225)) ([e96b8e6](https://github.com/context-dot-dev/context-typescript-sdk/commit/e96b8e6833971894877b28e03e04486cedfa8a7c)) +* **openapi:** keep legacy batch inputs in the spec as deprecated ([#2225](https://github.com/context-dot-dev/context-typescript-sdk/issues/2225)) ([1bd3e5c](https://github.com/context-dot-dev/context-typescript-sdk/commit/1bd3e5ca3bebc1a079701c5b8c322a62b6361127)) +* **scrape:** restore Instagram profile posts from public pages ([#2233](https://github.com/context-dot-dev/context-typescript-sdk/issues/2233)) ([2e7cbf7](https://github.com/context-dot-dev/context-typescript-sdk/commit/2e7cbf721079a86aaf706bca719f74ae26191ac4)) + ## [3.18.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.17.1...v3.18.0) (2026-10-27) diff --git a/package.json b/package.json index 5a6b13b8..b8d6fd0c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.18.0", + "version": "3.19.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index ccc7dec5..1a2f3272 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.18.0'; // x-release-please-version +export const VERSION = '3.19.0'; // x-release-please-version From 211f581508298cc4a21299f565c490aabeeed532 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 29 Oct 2026 17:06:05 +0000 Subject: [PATCH 201/232] fix(scrape): derive the /web/scrape request spec from its zod schema (#2044) Stainless-Generated-From: e89724d110ed37964384e49dd624f309ba559e95 --- src/resources/batch.ts | 14 ++++++++++++-- src/resources/web.ts | 13 ++++++++----- tests/api-resources/batch.test.ts | 2 +- tests/api-resources/web.test.ts | 2 +- 4 files changed, 22 insertions(+), 9 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 0c3c0043..4350a791 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -3695,7 +3695,7 @@ export namespace BatchSubmitParams { sharedParams?: BatchUnifiedScrapeData.SharedParams; /** - * Labels for tracking request usage. Not retained when zdr is enabled. + * Labels for filtering usage in the dashboard. */ tags?: Array; @@ -4010,6 +4010,11 @@ export namespace BatchSubmitParams { * Drop visually duplicate product images, keeping the largest copy. */ dedupeImages?: boolean; + + /** + * @deprecated Ignored. The AI fallback runs automatically. + */ + useAIFallback?: boolean; } /** @@ -5397,7 +5402,7 @@ export namespace BatchSubmitParams { sharedParams?: BatchUnifiedCrawlData.SharedParams; /** - * Labels for tracking request usage. Not retained when zdr is enabled. + * Labels for filtering usage in the dashboard. */ tags?: Array; @@ -5874,6 +5879,11 @@ export namespace BatchSubmitParams { * Drop visually duplicate product images, keeping the largest copy. */ dedupeImages?: boolean; + + /** + * @deprecated Ignored. The AI fallback runs automatically. + */ + useAIFallback?: boolean; } /** diff --git a/src/resources/web.ts b/src/resources/web.ts index 2fded2c0..85cf63b0 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2452,13 +2452,12 @@ export interface WebScrapeParams { sharedParams?: WebScrapeParams.SharedParams; /** - * Labels for tracking request usage. Not retained when zdr is enabled. + * Labels for filtering usage in the dashboard. */ tags?: Array; /** - * Deadline for the whole request. Defaults to 90000 ms with `fail`. Fixed waits - * must end before it. + * Request deadline and what to return when it passes. */ timeoutOpts?: WebScrapeParams.TimeoutOpts; @@ -2745,6 +2744,11 @@ export namespace WebScrapeParams { * Drop visually duplicate product images, keeping the largest copy. */ dedupeImages?: boolean; + + /** + * @deprecated Ignored. The AI fallback runs automatically. + */ + useAIFallback?: boolean; } /** @@ -3038,8 +3042,7 @@ export namespace WebScrapeParams { } /** - * Deadline for the whole request. Defaults to 90000 ms with `fail`. Fixed waits - * must end before it. + * Request deadline and what to return when it passes. */ export interface TimeoutOpts { /** diff --git a/tests/api-resources/batch.test.ts b/tests/api-resources/batch.test.ts index 9aa799a5..8c362e4b 100644 --- a/tests/api-resources/batch.test.ts +++ b/tests/api-resources/batch.test.ts @@ -179,7 +179,7 @@ describe('resource batch', () => { }, type: 'custom', }, - productParams: { dedupeImages: true }, + productParams: { dedupeImages: true, useAIFallback: true }, screenshotParams: { area: 'viewport', format: 'png' }, sharedParams: { actions: [{ action: 'Click the product details tab', type: 'perform' }], diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 26006e70..d8d47a4a 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -180,7 +180,7 @@ describe('resource web', () => { type: 'custom', }, policies: ['pol_3f9c2a7e5b8d4c1f9a6e0b2d7c4f8a1e'], - productParams: { dedupeImages: true }, + productParams: { dedupeImages: true, useAIFallback: true }, screenshotParams: { area: 'viewport', format: 'png' }, sharedParams: { actions: [{ action: 'Click the product details tab', type: 'perform' }], From 36d8df9e735bb2b04aad9c255d56570cb70c5bfb Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Thu, 29 Oct 2026 18:18:24 +0100 Subject: [PATCH 202/232] release: 3.19.1 (#106) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 60a50ee6..cce622a6 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.19.0" + ".": "3.19.1" } diff --git a/CHANGELOG.md b/CHANGELOG.md index fca680ff..ae02c7f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.19.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.19.0...v3.19.1) (2026-10-29) + + +### Bug Fixes + +* **scrape:** derive the /web/scrape request spec from its zod schema ([#2044](https://github.com/context-dot-dev/context-typescript-sdk/issues/2044)) ([211f581](https://github.com/context-dot-dev/context-typescript-sdk/commit/211f581508298cc4a21299f565c490aabeeed532)) + ## [3.19.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.18.0...v3.19.0) (2026-10-28) diff --git a/package.json b/package.json index b8d6fd0c..844e3c4f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.19.0", + "version": "3.19.1", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 1a2f3272..631c6a1b 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.19.0'; // x-release-please-version +export const VERSION = '3.19.1'; // x-release-please-version From 186069c8b338250ace47c8106bda051f02df73b6 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 30 Oct 2026 18:19:37 +0000 Subject: [PATCH 203/232] feat(scrape): add Yelp search parser Merge pull request #2306 from context-dot-dev/feat/yelp-search-parser Stainless-Generated-From: 1a825f274e1aaf7e0eb4ceddb059ffcacb8e2512 --- src/resources/batch.ts | 88 ++++++++++++++++++++++++------------------ src/resources/web.ts | 44 ++++++++++++--------- 2 files changed, 75 insertions(+), 57 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 4350a791..d1d8d328 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -1226,10 +1226,11 @@ export namespace BatchGetResultsResponse { * data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return * one record as data, tiktok-feed returns data.videos, tiktok-comments returns * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return - * data.users, emails, phone-numbers, and links return data.emails, - * data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, - * Instagram, and TikTok parsers read their data directly, independently of DOM - * filters and other outputs. + * data.users, yelp-search returns up to 20 ranked organic businesses in + * data.businesses, plus total and pagination, from a Yelp search URL; emails, + * phone-numbers, and links return data.emails, data.phone_numbers, and data.links + * from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read + * their data directly, independently of DOM filters and other outputs. */ parsed: Result.Parsed; @@ -1626,10 +1627,11 @@ export namespace BatchGetResultsResponse { * data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return * one record as data, tiktok-feed returns data.videos, tiktok-comments returns * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return - * data.users, emails, phone-numbers, and links return data.emails, - * data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, - * Instagram, and TikTok parsers read their data directly, independently of DOM - * filters and other outputs. + * data.users, yelp-search returns up to 20 ranked organic businesses in + * data.businesses, plus total and pagination, from a Yelp search URL; emails, + * phone-numbers, and links return data.emails, data.phone_numbers, and data.links + * from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read + * their data directly, independently of DOM filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1664,6 +1666,7 @@ export namespace BatchGetResultsResponse { | 'tiktok-followers' | 'tiktok-following' | 'tiktok-user-search' + | 'yelp-search' | 'emails' | 'phone-numbers' | 'links'; @@ -1998,10 +2001,11 @@ export namespace BatchGetResultsResponse { * data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return * one record as data, tiktok-feed returns data.videos, tiktok-comments returns * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return - * data.users, emails, phone-numbers, and links return data.emails, - * data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, - * Instagram, and TikTok parsers read their data directly, independently of DOM - * filters and other outputs. + * data.users, yelp-search returns up to 20 ranked organic businesses in + * data.businesses, plus total and pagination, from a Yelp search URL; emails, + * phone-numbers, and links return data.emails, data.phone_numbers, and data.links + * from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read + * their data directly, independently of DOM filters and other outputs. */ parsed: Result.Parsed; @@ -2398,10 +2402,11 @@ export namespace BatchGetResultsResponse { * data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return * one record as data, tiktok-feed returns data.videos, tiktok-comments returns * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return - * data.users, emails, phone-numbers, and links return data.emails, - * data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, - * Instagram, and TikTok parsers read their data directly, independently of DOM - * filters and other outputs. + * data.users, yelp-search returns up to 20 ranked organic businesses in + * data.businesses, plus total and pagination, from a Yelp search URL; emails, + * phone-numbers, and links return data.emails, data.phone_numbers, and data.links + * from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read + * their data directly, independently of DOM filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -2436,6 +2441,7 @@ export namespace BatchGetResultsResponse { | 'tiktok-followers' | 'tiktok-following' | 'tiktok-user-search' + | 'yelp-search' | 'emails' | 'phone-numbers' | 'links'; @@ -3949,17 +3955,19 @@ export namespace BatchSubmitParams { * (/search/user?q={query}) as data.users: id, username, nickname, biography, * avatar_url, sec_uid, follower_count, like_count, and is_verified. The TikTok * parsers accept tiktok.com, www.tiktok.com, and m.tiktok.com URLs but not short - * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). emails accepts any page - * and returns its email addresses as data.emails ([{ email }]), read from mailto - * links, Cloudflare-protected addresses, and visible text. phone-numbers accepts - * any page and returns its valid phone numbers in E.164 as data.phone_numbers ([{ - * phone }]), read from tel links and visible text; numbers without a country code - * are read for the country of the site TLD, defaulting to US. links accepts any - * page and returns its unique http(s) links as data.links ([{ url, text }]), with - * absolute URLs; text falls back to aria-label or image alt and is null when a - * link has none. The emails parser reads the rendered page and respects content - * filters; the other prebuilt parsers read their data independently of DOM - * filters. + * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). yelp-search accepts Yelp + * search URLs with find_desc and find_loc, reads start as the result offset, and + * returns up to 20 ranked organic businesses in data.businesses with total and + * pagination. emails accepts any page and returns its email addresses as + * data.emails ([{ email }]), read from mailto links, Cloudflare-protected + * addresses, and visible text. phone-numbers accepts any page and returns its + * valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel + * links and visible text; numbers without a country code are read for the country + * of the site TLD, defaulting to US. links accepts any page and returns its unique + * http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls + * back to aria-label or image alt and is null when a link has none. The emails + * parser reads the rendered page and respects content filters; the other prebuilt + * parsers read their data independently of DOM filters. */ parser: | 'google-maps' @@ -3979,6 +3987,7 @@ export namespace BatchSubmitParams { | 'tiktok-followers' | 'tiktok-following' | 'tiktok-user-search' + | 'yelp-search' | 'emails' | 'phone-numbers' | 'links'; @@ -5818,17 +5827,19 @@ export namespace BatchSubmitParams { * (/search/user?q={query}) as data.users: id, username, nickname, biography, * avatar_url, sec_uid, follower_count, like_count, and is_verified. The TikTok * parsers accept tiktok.com, www.tiktok.com, and m.tiktok.com URLs but not short - * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). emails accepts any page - * and returns its email addresses as data.emails ([{ email }]), read from mailto - * links, Cloudflare-protected addresses, and visible text. phone-numbers accepts - * any page and returns its valid phone numbers in E.164 as data.phone_numbers ([{ - * phone }]), read from tel links and visible text; numbers without a country code - * are read for the country of the site TLD, defaulting to US. links accepts any - * page and returns its unique http(s) links as data.links ([{ url, text }]), with - * absolute URLs; text falls back to aria-label or image alt and is null when a - * link has none. The emails parser reads the rendered page and respects content - * filters; the other prebuilt parsers read their data independently of DOM - * filters. + * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). yelp-search accepts Yelp + * search URLs with find_desc and find_loc, reads start as the result offset, and + * returns up to 20 ranked organic businesses in data.businesses with total and + * pagination. emails accepts any page and returns its email addresses as + * data.emails ([{ email }]), read from mailto links, Cloudflare-protected + * addresses, and visible text. phone-numbers accepts any page and returns its + * valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel + * links and visible text; numbers without a country code are read for the country + * of the site TLD, defaulting to US. links accepts any page and returns its unique + * http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls + * back to aria-label or image alt and is null when a link has none. The emails + * parser reads the rendered page and respects content filters; the other prebuilt + * parsers read their data independently of DOM filters. */ parser: | 'google-maps' @@ -5848,6 +5859,7 @@ export namespace BatchSubmitParams { | 'tiktok-followers' | 'tiktok-following' | 'tiktok-user-search' + | 'yelp-search' | 'emails' | 'phone-numbers' | 'links'; diff --git a/src/resources/web.ts b/src/resources/web.ts index 85cf63b0..ea59a667 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -965,10 +965,11 @@ export interface WebScrapeResponse { * data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return * one record as data, tiktok-feed returns data.videos, tiktok-comments returns * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return - * data.users, emails, phone-numbers, and links return data.emails, - * data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, - * Instagram, and TikTok parsers read their data directly, independently of DOM - * filters and other outputs. + * data.users, yelp-search returns up to 20 ranked organic businesses in + * data.businesses, plus total and pagination, from a Yelp search URL; emails, + * phone-numbers, and links return data.emails, data.phone_numbers, and data.links + * from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read + * their data directly, independently of DOM filters and other outputs. */ parsed: WebScrapeResponse.Parsed; @@ -1365,10 +1366,11 @@ export namespace WebScrapeResponse { * data, instagram-feed returns data.posts, tiktok-profile and tiktok-video return * one record as data, tiktok-feed returns data.videos, tiktok-comments returns * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return - * data.users, emails, phone-numbers, and links return data.emails, - * data.phone_numbers, and data.links from the rendered page; the store, Maps, G2, - * Instagram, and TikTok parsers read their data directly, independently of DOM - * filters and other outputs. + * data.users, yelp-search returns up to 20 ranked organic businesses in + * data.businesses, plus total and pagination, from a Yelp search URL; emails, + * phone-numbers, and links return data.emails, data.phone_numbers, and data.links + * from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read + * their data directly, independently of DOM filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1403,6 +1405,7 @@ export namespace WebScrapeResponse { | 'tiktok-followers' | 'tiktok-following' | 'tiktok-user-search' + | 'yelp-search' | 'emails' | 'phone-numbers' | 'links'; @@ -2683,17 +2686,19 @@ export namespace WebScrapeParams { * (/search/user?q={query}) as data.users: id, username, nickname, biography, * avatar_url, sec_uid, follower_count, like_count, and is_verified. The TikTok * parsers accept tiktok.com, www.tiktok.com, and m.tiktok.com URLs but not short - * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). emails accepts any page - * and returns its email addresses as data.emails ([{ email }]), read from mailto - * links, Cloudflare-protected addresses, and visible text. phone-numbers accepts - * any page and returns its valid phone numbers in E.164 as data.phone_numbers ([{ - * phone }]), read from tel links and visible text; numbers without a country code - * are read for the country of the site TLD, defaulting to US. links accepts any - * page and returns its unique http(s) links as data.links ([{ url, text }]), with - * absolute URLs; text falls back to aria-label or image alt and is null when a - * link has none. The emails parser reads the rendered page and respects content - * filters; the other prebuilt parsers read their data independently of DOM - * filters. + * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). yelp-search accepts Yelp + * search URLs with find_desc and find_loc, reads start as the result offset, and + * returns up to 20 ranked organic businesses in data.businesses with total and + * pagination. emails accepts any page and returns its email addresses as + * data.emails ([{ email }]), read from mailto links, Cloudflare-protected + * addresses, and visible text. phone-numbers accepts any page and returns its + * valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel + * links and visible text; numbers without a country code are read for the country + * of the site TLD, defaulting to US. links accepts any page and returns its unique + * http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls + * back to aria-label or image alt and is null when a link has none. The emails + * parser reads the rendered page and respects content filters; the other prebuilt + * parsers read their data independently of DOM filters. */ parser: | 'google-maps' @@ -2713,6 +2718,7 @@ export namespace WebScrapeParams { | 'tiktok-followers' | 'tiktok-following' | 'tiktok-user-search' + | 'yelp-search' | 'emails' | 'phone-numbers' | 'links'; From 2ab837017c196f99d336715e33a4acfc2a40cd24 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Fri, 30 Oct 2026 18:39:51 +0000 Subject: [PATCH 204/232] feat(scrape): add Yelp reviews parser Merge pull request #2307 from context-dot-dev/feat/yelp-reviews-parser Stainless-Generated-From: 26d292b00607f375274d5fd90d41877fb804217c --- src/resources/batch.ts | 96 ++++++++++++++++++++++++++---------------- src/resources/web.ts | 48 +++++++++++++-------- 2 files changed, 90 insertions(+), 54 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index d1d8d328..b9172458 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -1227,10 +1227,12 @@ export namespace BatchGetResultsResponse { * one record as data, tiktok-feed returns data.videos, tiktok-comments returns * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return * data.users, yelp-search returns up to 20 ranked organic businesses in - * data.businesses, plus total and pagination, from a Yelp search URL; emails, - * phone-numbers, and links return data.emails, data.phone_numbers, and data.links - * from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read - * their data directly, independently of DOM filters and other outputs. + * data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews + * returns up to 20 latest public reviews in data.reviews, with business details + * and next_offset, from a Yelp business URL; emails, phone-numbers, and links + * return data.emails, data.phone_numbers, and data.links from the rendered page; + * the store, Maps, G2, Instagram, and TikTok parsers read their data directly, + * independently of DOM filters and other outputs. */ parsed: Result.Parsed; @@ -1628,10 +1630,12 @@ export namespace BatchGetResultsResponse { * one record as data, tiktok-feed returns data.videos, tiktok-comments returns * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return * data.users, yelp-search returns up to 20 ranked organic businesses in - * data.businesses, plus total and pagination, from a Yelp search URL; emails, - * phone-numbers, and links return data.emails, data.phone_numbers, and data.links - * from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read - * their data directly, independently of DOM filters and other outputs. + * data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews + * returns up to 20 latest public reviews in data.reviews, with business details + * and next_offset, from a Yelp business URL; emails, phone-numbers, and links + * return data.emails, data.phone_numbers, and data.links from the rendered page; + * the store, Maps, G2, Instagram, and TikTok parsers read their data directly, + * independently of DOM filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1667,6 +1671,7 @@ export namespace BatchGetResultsResponse { | 'tiktok-following' | 'tiktok-user-search' | 'yelp-search' + | 'yelp-reviews' | 'emails' | 'phone-numbers' | 'links'; @@ -2002,10 +2007,12 @@ export namespace BatchGetResultsResponse { * one record as data, tiktok-feed returns data.videos, tiktok-comments returns * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return * data.users, yelp-search returns up to 20 ranked organic businesses in - * data.businesses, plus total and pagination, from a Yelp search URL; emails, - * phone-numbers, and links return data.emails, data.phone_numbers, and data.links - * from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read - * their data directly, independently of DOM filters and other outputs. + * data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews + * returns up to 20 latest public reviews in data.reviews, with business details + * and next_offset, from a Yelp business URL; emails, phone-numbers, and links + * return data.emails, data.phone_numbers, and data.links from the rendered page; + * the store, Maps, G2, Instagram, and TikTok parsers read their data directly, + * independently of DOM filters and other outputs. */ parsed: Result.Parsed; @@ -2403,10 +2410,12 @@ export namespace BatchGetResultsResponse { * one record as data, tiktok-feed returns data.videos, tiktok-comments returns * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return * data.users, yelp-search returns up to 20 ranked organic businesses in - * data.businesses, plus total and pagination, from a Yelp search URL; emails, - * phone-numbers, and links return data.emails, data.phone_numbers, and data.links - * from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read - * their data directly, independently of DOM filters and other outputs. + * data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews + * returns up to 20 latest public reviews in data.reviews, with business details + * and next_offset, from a Yelp business URL; emails, phone-numbers, and links + * return data.emails, data.phone_numbers, and data.links from the rendered page; + * the store, Maps, G2, Instagram, and TikTok parsers read their data directly, + * independently of DOM filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -2442,6 +2451,7 @@ export namespace BatchGetResultsResponse { | 'tiktok-following' | 'tiktok-user-search' | 'yelp-search' + | 'yelp-reviews' | 'emails' | 'phone-numbers' | 'links'; @@ -3958,16 +3968,22 @@ export namespace BatchSubmitParams { * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). yelp-search accepts Yelp * search URLs with find_desc and find_loc, reads start as the result offset, and * returns up to 20 ranked organic businesses in data.businesses with total and - * pagination. emails accepts any page and returns its email addresses as - * data.emails ([{ email }]), read from mailto links, Cloudflare-protected - * addresses, and visible text. phone-numbers accepts any page and returns its - * valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel - * links and visible text; numbers without a country code are read for the country - * of the site TLD, defaulting to US. links accepts any page and returns its unique - * http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls - * back to aria-label or image alt and is null when a link has none. The emails - * parser reads the rendered page and respects content filters; the other prebuilt - * parsers read their data independently of DOM filters. + * pagination. yelp-reviews accepts a Yelp business URL (yelp.com/biz/{alias}), + * uses optional start for the offset, and always sorts newest first; unsupported + * sort and review filters are rejected, while tracking params are ignored. It + * returns up to 20 latest public reviews in data.reviews with business details and + * pagination.next_offset. Each review has rating, full text, updated_at, and + * author; owner replies and photos are not included. emails accepts any page and + * returns its email addresses as data.emails ([{ email }]), read from mailto + * links, Cloudflare-protected addresses, and visible text. phone-numbers accepts + * any page and returns its valid phone numbers in E.164 as data.phone_numbers ([{ + * phone }]), read from tel links and visible text; numbers without a country code + * are read for the country of the site TLD, defaulting to US. links accepts any + * page and returns its unique http(s) links as data.links ([{ url, text }]), with + * absolute URLs; text falls back to aria-label or image alt and is null when a + * link has none. The emails parser reads the rendered page and respects content + * filters; the other prebuilt parsers read their data independently of DOM + * filters. */ parser: | 'google-maps' @@ -3988,6 +4004,7 @@ export namespace BatchSubmitParams { | 'tiktok-following' | 'tiktok-user-search' | 'yelp-search' + | 'yelp-reviews' | 'emails' | 'phone-numbers' | 'links'; @@ -5830,16 +5847,22 @@ export namespace BatchSubmitParams { * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). yelp-search accepts Yelp * search URLs with find_desc and find_loc, reads start as the result offset, and * returns up to 20 ranked organic businesses in data.businesses with total and - * pagination. emails accepts any page and returns its email addresses as - * data.emails ([{ email }]), read from mailto links, Cloudflare-protected - * addresses, and visible text. phone-numbers accepts any page and returns its - * valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel - * links and visible text; numbers without a country code are read for the country - * of the site TLD, defaulting to US. links accepts any page and returns its unique - * http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls - * back to aria-label or image alt and is null when a link has none. The emails - * parser reads the rendered page and respects content filters; the other prebuilt - * parsers read their data independently of DOM filters. + * pagination. yelp-reviews accepts a Yelp business URL (yelp.com/biz/{alias}), + * uses optional start for the offset, and always sorts newest first; unsupported + * sort and review filters are rejected, while tracking params are ignored. It + * returns up to 20 latest public reviews in data.reviews with business details and + * pagination.next_offset. Each review has rating, full text, updated_at, and + * author; owner replies and photos are not included. emails accepts any page and + * returns its email addresses as data.emails ([{ email }]), read from mailto + * links, Cloudflare-protected addresses, and visible text. phone-numbers accepts + * any page and returns its valid phone numbers in E.164 as data.phone_numbers ([{ + * phone }]), read from tel links and visible text; numbers without a country code + * are read for the country of the site TLD, defaulting to US. links accepts any + * page and returns its unique http(s) links as data.links ([{ url, text }]), with + * absolute URLs; text falls back to aria-label or image alt and is null when a + * link has none. The emails parser reads the rendered page and respects content + * filters; the other prebuilt parsers read their data independently of DOM + * filters. */ parser: | 'google-maps' @@ -5860,6 +5883,7 @@ export namespace BatchSubmitParams { | 'tiktok-following' | 'tiktok-user-search' | 'yelp-search' + | 'yelp-reviews' | 'emails' | 'phone-numbers' | 'links'; diff --git a/src/resources/web.ts b/src/resources/web.ts index ea59a667..ee4cb6f4 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -966,10 +966,12 @@ export interface WebScrapeResponse { * one record as data, tiktok-feed returns data.videos, tiktok-comments returns * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return * data.users, yelp-search returns up to 20 ranked organic businesses in - * data.businesses, plus total and pagination, from a Yelp search URL; emails, - * phone-numbers, and links return data.emails, data.phone_numbers, and data.links - * from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read - * their data directly, independently of DOM filters and other outputs. + * data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews + * returns up to 20 latest public reviews in data.reviews, with business details + * and next_offset, from a Yelp business URL; emails, phone-numbers, and links + * return data.emails, data.phone_numbers, and data.links from the rendered page; + * the store, Maps, G2, Instagram, and TikTok parsers read their data directly, + * independently of DOM filters and other outputs. */ parsed: WebScrapeResponse.Parsed; @@ -1367,10 +1369,12 @@ export namespace WebScrapeResponse { * one record as data, tiktok-feed returns data.videos, tiktok-comments returns * data.comments, tiktok-followers, tiktok-following, and tiktok-user-search return * data.users, yelp-search returns up to 20 ranked organic businesses in - * data.businesses, plus total and pagination, from a Yelp search URL; emails, - * phone-numbers, and links return data.emails, data.phone_numbers, and data.links - * from the rendered page; the store, Maps, G2, Instagram, and TikTok parsers read - * their data directly, independently of DOM filters and other outputs. + * data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews + * returns up to 20 latest public reviews in data.reviews, with business details + * and next_offset, from a Yelp business URL; emails, phone-numbers, and links + * return data.emails, data.phone_numbers, and data.links from the rendered page; + * the store, Maps, G2, Instagram, and TikTok parsers read their data directly, + * independently of DOM filters and other outputs. */ export interface Parsed { data: { [key: string]: unknown } | null; @@ -1406,6 +1410,7 @@ export namespace WebScrapeResponse { | 'tiktok-following' | 'tiktok-user-search' | 'yelp-search' + | 'yelp-reviews' | 'emails' | 'phone-numbers' | 'links'; @@ -2689,16 +2694,22 @@ export namespace WebScrapeParams { * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). yelp-search accepts Yelp * search URLs with find_desc and find_loc, reads start as the result offset, and * returns up to 20 ranked organic businesses in data.businesses with total and - * pagination. emails accepts any page and returns its email addresses as - * data.emails ([{ email }]), read from mailto links, Cloudflare-protected - * addresses, and visible text. phone-numbers accepts any page and returns its - * valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel - * links and visible text; numbers without a country code are read for the country - * of the site TLD, defaulting to US. links accepts any page and returns its unique - * http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls - * back to aria-label or image alt and is null when a link has none. The emails - * parser reads the rendered page and respects content filters; the other prebuilt - * parsers read their data independently of DOM filters. + * pagination. yelp-reviews accepts a Yelp business URL (yelp.com/biz/{alias}), + * uses optional start for the offset, and always sorts newest first; unsupported + * sort and review filters are rejected, while tracking params are ignored. It + * returns up to 20 latest public reviews in data.reviews with business details and + * pagination.next_offset. Each review has rating, full text, updated_at, and + * author; owner replies and photos are not included. emails accepts any page and + * returns its email addresses as data.emails ([{ email }]), read from mailto + * links, Cloudflare-protected addresses, and visible text. phone-numbers accepts + * any page and returns its valid phone numbers in E.164 as data.phone_numbers ([{ + * phone }]), read from tel links and visible text; numbers without a country code + * are read for the country of the site TLD, defaulting to US. links accepts any + * page and returns its unique http(s) links as data.links ([{ url, text }]), with + * absolute URLs; text falls back to aria-label or image alt and is null when a + * link has none. The emails parser reads the rendered page and respects content + * filters; the other prebuilt parsers read their data independently of DOM + * filters. */ parser: | 'google-maps' @@ -2719,6 +2730,7 @@ export namespace WebScrapeParams { | 'tiktok-following' | 'tiktok-user-search' | 'yelp-search' + | 'yelp-reviews' | 'emails' | 'phone-numbers' | 'links'; From 46059e5f9c793e4200f555ba743e754df98985c9 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Fri, 30 Oct 2026 19:47:21 +0100 Subject: [PATCH 205/232] release: 3.20.0 (#107) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 8 ++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 11 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index cce622a6..f80372ae 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.19.1" + ".": "3.20.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index ae02c7f3..3bf40324 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## [3.20.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.19.1...v3.20.0) (2026-10-30) + + +### Features + +* **scrape:** add Yelp reviews parser ([2ab8370](https://github.com/context-dot-dev/context-typescript-sdk/commit/2ab837017c196f99d336715e33a4acfc2a40cd24)) +* **scrape:** add Yelp search parser ([186069c](https://github.com/context-dot-dev/context-typescript-sdk/commit/186069c8b338250ace47c8106bda051f02df73b6)) + ## [3.19.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.19.0...v3.19.1) (2026-10-29) diff --git a/package.json b/package.json index 844e3c4f..a9f274ce 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.19.1", + "version": "3.20.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 631c6a1b..b33ee76a 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.19.1'; // x-release-please-version +export const VERSION = '3.20.0'; // x-release-please-version From 733e0c9a361a1dc19838bc8ed5f89f2e6e298416 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 31 Oct 2026 19:51:36 +0000 Subject: [PATCH 206/232] feat(scrape): add reddit-post prebuilt parser with full comment trees (#2217) Stainless-Generated-From: 99ee522f249251c5be90ecc3d59642f35341cb01 --- src/resources/batch.ts | 154 ++++++++++++++++++++++++++++++++++++----- src/resources/web.ts | 77 ++++++++++++++++++--- 2 files changed, 204 insertions(+), 27 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index b9172458..6b9e798d 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -1670,6 +1670,10 @@ export namespace BatchGetResultsResponse { | 'tiktok-followers' | 'tiktok-following' | 'tiktok-user-search' + | 'reddit-post' + | 'reddit-search' + | 'reddit-subreddit' + | 'reddit-user' | 'yelp-search' | 'yelp-reviews' | 'emails' @@ -2450,6 +2454,10 @@ export namespace BatchGetResultsResponse { | 'tiktok-followers' | 'tiktok-following' | 'tiktok-user-search' + | 'reddit-post' + | 'reddit-search' + | 'reddit-subreddit' + | 'reddit-user' | 'yelp-search' | 'yelp-reviews' | 'emails' @@ -3965,13 +3973,62 @@ export namespace BatchSubmitParams { * (/search/user?q={query}) as data.users: id, username, nickname, biography, * avatar_url, sec_uid, follower_count, like_count, and is_verified. The TikTok * parsers accept tiktok.com, www.tiktok.com, and m.tiktok.com URLs but not short - * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). yelp-search accepts Yelp - * search URLs with find_desc and find_loc, reads start as the result offset, and - * returns up to 20 ranked organic businesses in data.businesses with total and - * pagination. yelp-reviews accepts a Yelp business URL (yelp.com/biz/{alias}), - * uses optional start for the offset, and always sorts newest first; unsupported - * sort and review filters are rejected, while tracking params are ignored. It - * returns up to 20 latest public reviews in data.reviews with business details and + * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). reddit-post parses a post + * (reddit.com/r/{subreddit}/comments/{id}, reddit.com/comments/{id}, or + * redd.it/{id}) into data.post: title, body as Markdown, type (text, link, image, + * gallery, or video), link_url, subreddit, author, flairs, score, upvote_ratio, + * comment and crosspost counts, NSFW, spoiler, locked, stickied, and archived + * flags, images (every gallery image in order), and video (an MP4 url plus an + * hls_url that carries the audio). data.comments holds the comment tree, each + * comment with id, author, body as Markdown, score, posted_at, depth, parent_id, + * url, is_submitter, is_deleted, and its replies; limit caps the total number of + * comments (default 100), filled shallowest first so whole conversations are kept, + * and data.has_more_comments says whether the thread has more. The sort query of + * the URL (best, top, new, controversial, old, qa) orders the comments. + * reddit-search returns search results for a search URL + * (reddit.com/search?q={query}, or reddit.com/r/{subreddit}/search?q={query} to + * search one subreddit). With type=link or no type it returns posts in the + * reddit-post shape as data.posts, ordered by the sort (relevance, hot, top, new, + * comments) and limited to the t time range (hour, day, week, month, year, all) of + * the URL; type=sr returns communities as data.communities (name, title, + * description, sidebar, subscriber_count, created_at, type, NSFW and quarantine + * flags, language, category, icon and banner URLs, and allowed post types); + * type=user returns accounts as data.users (username, display_name, bio, + * created_at, post and comment karma, avatar and banner URLs, and verified, + * employee, moderator, premium, and NSFW flags). limit caps the number of results + * (default 100), in the order Reddit returns them, and data.has_more says whether + * Reddit has more. reddit-subreddit reads a subreddit URL + * (reddit.com/r/{subreddit}, optionally followed by /hot, /new, /top, /rising, or + * /controversial, with t setting the time range of top and controversial, default + * day) into data.subreddit in the community shape of reddit-search, data.rules + * (name, description, applies_to, violation_reason, created_at), and data.posts in + * the reddit-post shape, ordered like the tab (default hot) and with stickied + * posts flagged; r/all and r/popular return posts with a null subreddit and rules. + * limit caps the posts (default 100) and data.has_more says whether Reddit has + * more. Private and quarantined subreddits return WEBSITE_ACCESS_ERROR. + * reddit-user reads a profile URL (reddit.com/user/{username} or + * reddit.com/u/{username}, optionally followed by /overview, /submitted, or + * /comments, with sort set to new, hot, top, or controversial and t setting the + * time range of top and controversial, default all) into data.user (id, username, + * display_name, bio, created_at, total, post, comment, awardee, and awarder karma, + * avatar and banner URLs, and verified, suspended, employee, moderator, premium, + * and NSFW flags), data.trophies (name, description, icon_url, granted_at, url), + * data.moderated_communities (name, title, url, subscriber_count, icon_url, + * is_nsfw), data.posts in the reddit-post shape, and data.comments, each with id, + * author, body as Markdown, score, posted_at, edited_at, url, subreddit, parent_id + * (null for a top-level comment), is_submitter, is_stickied, distinguished, + * award_count, and the post it was left on (id, title, url, author, is_nsfw). The + * overview tab returns both posts and comments; submitted returns null comments + * and comments returns null posts. limit caps the posts and comments together + * (default 100) and data.has_more says whether Reddit has more. Users who hide + * their activity return empty lists, and suspended accounts return their profile + * with null posts and comments. yelp-search accepts Yelp search URLs with + * find_desc and find_loc, reads start as the result offset, and returns up to 20 + * ranked organic businesses in data.businesses with total and pagination. + * yelp-reviews accepts a Yelp business URL (yelp.com/biz/{alias}), uses optional + * start for the offset, and always sorts newest first; unsupported sort and review + * filters are rejected, while tracking params are ignored. It returns up to 20 + * latest public reviews in data.reviews with business details and * pagination.next_offset. Each review has rating, full text, updated_at, and * author; owner replies and photos are not included. emails accepts any page and * returns its email addresses as data.emails ([{ email }]), read from mailto @@ -4003,6 +4060,10 @@ export namespace BatchSubmitParams { | 'tiktok-followers' | 'tiktok-following' | 'tiktok-user-search' + | 'reddit-post' + | 'reddit-search' + | 'reddit-subreddit' + | 'reddit-user' | 'yelp-search' | 'yelp-reviews' | 'emails' @@ -4015,8 +4076,10 @@ export namespace BatchSubmitParams { type: 'prebuilt'; /** - * google-maps-reviews only. Maximum number of reviews to return. Defaults to 100; - * maximum 1000. + * google-maps-reviews and reddit parsers only. Maximum number of reviews + * (google-maps-reviews, default 100), comments (reddit-post, default 100), or + * results (reddit-search, reddit-subreddit, and reddit-user, default 100) to + * return; maximum 1000. */ limit?: number; @@ -5844,13 +5907,62 @@ export namespace BatchSubmitParams { * (/search/user?q={query}) as data.users: id, username, nickname, biography, * avatar_url, sec_uid, follower_count, like_count, and is_verified. The TikTok * parsers accept tiktok.com, www.tiktok.com, and m.tiktok.com URLs but not short - * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). yelp-search accepts Yelp - * search URLs with find_desc and find_loc, reads start as the result offset, and - * returns up to 20 ranked organic businesses in data.businesses with total and - * pagination. yelp-reviews accepts a Yelp business URL (yelp.com/biz/{alias}), - * uses optional start for the offset, and always sorts newest first; unsupported - * sort and review filters are rejected, while tracking params are ignored. It - * returns up to 20 latest public reviews in data.reviews with business details and + * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). reddit-post parses a post + * (reddit.com/r/{subreddit}/comments/{id}, reddit.com/comments/{id}, or + * redd.it/{id}) into data.post: title, body as Markdown, type (text, link, image, + * gallery, or video), link_url, subreddit, author, flairs, score, upvote_ratio, + * comment and crosspost counts, NSFW, spoiler, locked, stickied, and archived + * flags, images (every gallery image in order), and video (an MP4 url plus an + * hls_url that carries the audio). data.comments holds the comment tree, each + * comment with id, author, body as Markdown, score, posted_at, depth, parent_id, + * url, is_submitter, is_deleted, and its replies; limit caps the total number of + * comments (default 100), filled shallowest first so whole conversations are kept, + * and data.has_more_comments says whether the thread has more. The sort query of + * the URL (best, top, new, controversial, old, qa) orders the comments. + * reddit-search returns search results for a search URL + * (reddit.com/search?q={query}, or reddit.com/r/{subreddit}/search?q={query} to + * search one subreddit). With type=link or no type it returns posts in the + * reddit-post shape as data.posts, ordered by the sort (relevance, hot, top, new, + * comments) and limited to the t time range (hour, day, week, month, year, all) of + * the URL; type=sr returns communities as data.communities (name, title, + * description, sidebar, subscriber_count, created_at, type, NSFW and quarantine + * flags, language, category, icon and banner URLs, and allowed post types); + * type=user returns accounts as data.users (username, display_name, bio, + * created_at, post and comment karma, avatar and banner URLs, and verified, + * employee, moderator, premium, and NSFW flags). limit caps the number of results + * (default 100), in the order Reddit returns them, and data.has_more says whether + * Reddit has more. reddit-subreddit reads a subreddit URL + * (reddit.com/r/{subreddit}, optionally followed by /hot, /new, /top, /rising, or + * /controversial, with t setting the time range of top and controversial, default + * day) into data.subreddit in the community shape of reddit-search, data.rules + * (name, description, applies_to, violation_reason, created_at), and data.posts in + * the reddit-post shape, ordered like the tab (default hot) and with stickied + * posts flagged; r/all and r/popular return posts with a null subreddit and rules. + * limit caps the posts (default 100) and data.has_more says whether Reddit has + * more. Private and quarantined subreddits return WEBSITE_ACCESS_ERROR. + * reddit-user reads a profile URL (reddit.com/user/{username} or + * reddit.com/u/{username}, optionally followed by /overview, /submitted, or + * /comments, with sort set to new, hot, top, or controversial and t setting the + * time range of top and controversial, default all) into data.user (id, username, + * display_name, bio, created_at, total, post, comment, awardee, and awarder karma, + * avatar and banner URLs, and verified, suspended, employee, moderator, premium, + * and NSFW flags), data.trophies (name, description, icon_url, granted_at, url), + * data.moderated_communities (name, title, url, subscriber_count, icon_url, + * is_nsfw), data.posts in the reddit-post shape, and data.comments, each with id, + * author, body as Markdown, score, posted_at, edited_at, url, subreddit, parent_id + * (null for a top-level comment), is_submitter, is_stickied, distinguished, + * award_count, and the post it was left on (id, title, url, author, is_nsfw). The + * overview tab returns both posts and comments; submitted returns null comments + * and comments returns null posts. limit caps the posts and comments together + * (default 100) and data.has_more says whether Reddit has more. Users who hide + * their activity return empty lists, and suspended accounts return their profile + * with null posts and comments. yelp-search accepts Yelp search URLs with + * find_desc and find_loc, reads start as the result offset, and returns up to 20 + * ranked organic businesses in data.businesses with total and pagination. + * yelp-reviews accepts a Yelp business URL (yelp.com/biz/{alias}), uses optional + * start for the offset, and always sorts newest first; unsupported sort and review + * filters are rejected, while tracking params are ignored. It returns up to 20 + * latest public reviews in data.reviews with business details and * pagination.next_offset. Each review has rating, full text, updated_at, and * author; owner replies and photos are not included. emails accepts any page and * returns its email addresses as data.emails ([{ email }]), read from mailto @@ -5882,6 +5994,10 @@ export namespace BatchSubmitParams { | 'tiktok-followers' | 'tiktok-following' | 'tiktok-user-search' + | 'reddit-post' + | 'reddit-search' + | 'reddit-subreddit' + | 'reddit-user' | 'yelp-search' | 'yelp-reviews' | 'emails' @@ -5894,8 +6010,10 @@ export namespace BatchSubmitParams { type: 'prebuilt'; /** - * google-maps-reviews only. Maximum number of reviews to return. Defaults to 100; - * maximum 1000. + * google-maps-reviews and reddit parsers only. Maximum number of reviews + * (google-maps-reviews, default 100), comments (reddit-post, default 100), or + * results (reddit-search, reddit-subreddit, and reddit-user, default 100) to + * return; maximum 1000. */ limit?: number; diff --git a/src/resources/web.ts b/src/resources/web.ts index ee4cb6f4..5df9b4f1 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1409,6 +1409,10 @@ export namespace WebScrapeResponse { | 'tiktok-followers' | 'tiktok-following' | 'tiktok-user-search' + | 'reddit-post' + | 'reddit-search' + | 'reddit-subreddit' + | 'reddit-user' | 'yelp-search' | 'yelp-reviews' | 'emails' @@ -2691,13 +2695,62 @@ export namespace WebScrapeParams { * (/search/user?q={query}) as data.users: id, username, nickname, biography, * avatar_url, sec_uid, follower_count, like_count, and is_verified. The TikTok * parsers accept tiktok.com, www.tiktok.com, and m.tiktok.com URLs but not short - * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). yelp-search accepts Yelp - * search URLs with find_desc and find_loc, reads start as the result offset, and - * returns up to 20 ranked organic businesses in data.businesses with total and - * pagination. yelp-reviews accepts a Yelp business URL (yelp.com/biz/{alias}), - * uses optional start for the offset, and always sorts newest first; unsupported - * sort and review filters are rejected, while tracking params are ignored. It - * returns up to 20 latest public reviews in data.reviews with business details and + * links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…). reddit-post parses a post + * (reddit.com/r/{subreddit}/comments/{id}, reddit.com/comments/{id}, or + * redd.it/{id}) into data.post: title, body as Markdown, type (text, link, image, + * gallery, or video), link_url, subreddit, author, flairs, score, upvote_ratio, + * comment and crosspost counts, NSFW, spoiler, locked, stickied, and archived + * flags, images (every gallery image in order), and video (an MP4 url plus an + * hls_url that carries the audio). data.comments holds the comment tree, each + * comment with id, author, body as Markdown, score, posted_at, depth, parent_id, + * url, is_submitter, is_deleted, and its replies; limit caps the total number of + * comments (default 100), filled shallowest first so whole conversations are kept, + * and data.has_more_comments says whether the thread has more. The sort query of + * the URL (best, top, new, controversial, old, qa) orders the comments. + * reddit-search returns search results for a search URL + * (reddit.com/search?q={query}, or reddit.com/r/{subreddit}/search?q={query} to + * search one subreddit). With type=link or no type it returns posts in the + * reddit-post shape as data.posts, ordered by the sort (relevance, hot, top, new, + * comments) and limited to the t time range (hour, day, week, month, year, all) of + * the URL; type=sr returns communities as data.communities (name, title, + * description, sidebar, subscriber_count, created_at, type, NSFW and quarantine + * flags, language, category, icon and banner URLs, and allowed post types); + * type=user returns accounts as data.users (username, display_name, bio, + * created_at, post and comment karma, avatar and banner URLs, and verified, + * employee, moderator, premium, and NSFW flags). limit caps the number of results + * (default 100), in the order Reddit returns them, and data.has_more says whether + * Reddit has more. reddit-subreddit reads a subreddit URL + * (reddit.com/r/{subreddit}, optionally followed by /hot, /new, /top, /rising, or + * /controversial, with t setting the time range of top and controversial, default + * day) into data.subreddit in the community shape of reddit-search, data.rules + * (name, description, applies_to, violation_reason, created_at), and data.posts in + * the reddit-post shape, ordered like the tab (default hot) and with stickied + * posts flagged; r/all and r/popular return posts with a null subreddit and rules. + * limit caps the posts (default 100) and data.has_more says whether Reddit has + * more. Private and quarantined subreddits return WEBSITE_ACCESS_ERROR. + * reddit-user reads a profile URL (reddit.com/user/{username} or + * reddit.com/u/{username}, optionally followed by /overview, /submitted, or + * /comments, with sort set to new, hot, top, or controversial and t setting the + * time range of top and controversial, default all) into data.user (id, username, + * display_name, bio, created_at, total, post, comment, awardee, and awarder karma, + * avatar and banner URLs, and verified, suspended, employee, moderator, premium, + * and NSFW flags), data.trophies (name, description, icon_url, granted_at, url), + * data.moderated_communities (name, title, url, subscriber_count, icon_url, + * is_nsfw), data.posts in the reddit-post shape, and data.comments, each with id, + * author, body as Markdown, score, posted_at, edited_at, url, subreddit, parent_id + * (null for a top-level comment), is_submitter, is_stickied, distinguished, + * award_count, and the post it was left on (id, title, url, author, is_nsfw). The + * overview tab returns both posts and comments; submitted returns null comments + * and comments returns null posts. limit caps the posts and comments together + * (default 100) and data.has_more says whether Reddit has more. Users who hide + * their activity return empty lists, and suspended accounts return their profile + * with null posts and comments. yelp-search accepts Yelp search URLs with + * find_desc and find_loc, reads start as the result offset, and returns up to 20 + * ranked organic businesses in data.businesses with total and pagination. + * yelp-reviews accepts a Yelp business URL (yelp.com/biz/{alias}), uses optional + * start for the offset, and always sorts newest first; unsupported sort and review + * filters are rejected, while tracking params are ignored. It returns up to 20 + * latest public reviews in data.reviews with business details and * pagination.next_offset. Each review has rating, full text, updated_at, and * author; owner replies and photos are not included. emails accepts any page and * returns its email addresses as data.emails ([{ email }]), read from mailto @@ -2729,6 +2782,10 @@ export namespace WebScrapeParams { | 'tiktok-followers' | 'tiktok-following' | 'tiktok-user-search' + | 'reddit-post' + | 'reddit-search' + | 'reddit-subreddit' + | 'reddit-user' | 'yelp-search' | 'yelp-reviews' | 'emails' @@ -2741,8 +2798,10 @@ export namespace WebScrapeParams { type: 'prebuilt'; /** - * google-maps-reviews only. Maximum number of reviews to return. Defaults to 100; - * maximum 1000. + * google-maps-reviews and reddit parsers only. Maximum number of reviews + * (google-maps-reviews, default 100), comments (reddit-post, default 100), or + * results (reddit-search, reddit-subreddit, and reddit-user, default 100) to + * return; maximum 1000. */ limit?: number; From b6276a1d1f5a323866b8ae6051ce3153ee83ce34 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Sat, 31 Oct 2026 21:03:32 +0100 Subject: [PATCH 207/232] release: 3.21.0 (#108) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index f80372ae..a397c094 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.20.0" + ".": "3.21.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 3bf40324..526d8e28 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.21.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.20.0...v3.21.0) (2026-10-31) + + +### Features + +* **scrape:** add reddit-post prebuilt parser with full comment trees ([#2217](https://github.com/context-dot-dev/context-typescript-sdk/issues/2217)) ([733e0c9](https://github.com/context-dot-dev/context-typescript-sdk/commit/733e0c9a361a1dc19838bc8ed5f89f2e6e298416)) + ## [3.20.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.19.1...v3.20.0) (2026-10-30) diff --git a/package.json b/package.json index a9f274ce..544d0b6f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.20.0", + "version": "3.21.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index b33ee76a..623537eb 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.20.0'; // x-release-please-version +export const VERSION = '3.21.0'; // x-release-please-version From 3f07f7e8b2f6be34d5f45dddf75e067e77f131ec Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 1 Nov 2026 22:41:13 +0000 Subject: [PATCH 208/232] feat(scrape): return Yelp reviewer id and profile url in yelp-reviews (#2402) Stainless-Generated-From: c489d0e2165a08de4a135387acee8968b12fdba8 --- src/resources/batch.ts | 46 ++++++++++++++++++++++-------------------- src/resources/web.ts | 23 +++++++++++---------- 2 files changed, 36 insertions(+), 33 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 6b9e798d..9c58d5a1 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -4030,17 +4030,18 @@ export namespace BatchSubmitParams { * filters are rejected, while tracking params are ignored. It returns up to 20 * latest public reviews in data.reviews with business details and * pagination.next_offset. Each review has rating, full text, updated_at, and - * author; owner replies and photos are not included. emails accepts any page and - * returns its email addresses as data.emails ([{ email }]), read from mailto - * links, Cloudflare-protected addresses, and visible text. phone-numbers accepts - * any page and returns its valid phone numbers in E.164 as data.phone_numbers ([{ - * phone }]), read from tel links and visible text; numbers without a country code - * are read for the country of the site TLD, defaulting to US. links accepts any - * page and returns its unique http(s) links as data.links ([{ url, text }]), with - * absolute URLs; text falls back to aria-label or image alt and is null when a - * link has none. The emails parser reads the rendered page and respects content - * filters; the other prebuilt parsers read their data independently of DOM - * filters. + * author (id is the Yelp user id from the reviewer profile URL, url links to that + * profile, plus name, location, and review_count); owner replies and photos are + * not included. emails accepts any page and returns its email addresses as + * data.emails ([{ email }]), read from mailto links, Cloudflare-protected + * addresses, and visible text. phone-numbers accepts any page and returns its + * valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel + * links and visible text; numbers without a country code are read for the country + * of the site TLD, defaulting to US. links accepts any page and returns its unique + * http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls + * back to aria-label or image alt and is null when a link has none. The emails + * parser reads the rendered page and respects content filters; the other prebuilt + * parsers read their data independently of DOM filters. */ parser: | 'google-maps' @@ -5964,17 +5965,18 @@ export namespace BatchSubmitParams { * filters are rejected, while tracking params are ignored. It returns up to 20 * latest public reviews in data.reviews with business details and * pagination.next_offset. Each review has rating, full text, updated_at, and - * author; owner replies and photos are not included. emails accepts any page and - * returns its email addresses as data.emails ([{ email }]), read from mailto - * links, Cloudflare-protected addresses, and visible text. phone-numbers accepts - * any page and returns its valid phone numbers in E.164 as data.phone_numbers ([{ - * phone }]), read from tel links and visible text; numbers without a country code - * are read for the country of the site TLD, defaulting to US. links accepts any - * page and returns its unique http(s) links as data.links ([{ url, text }]), with - * absolute URLs; text falls back to aria-label or image alt and is null when a - * link has none. The emails parser reads the rendered page and respects content - * filters; the other prebuilt parsers read their data independently of DOM - * filters. + * author (id is the Yelp user id from the reviewer profile URL, url links to that + * profile, plus name, location, and review_count); owner replies and photos are + * not included. emails accepts any page and returns its email addresses as + * data.emails ([{ email }]), read from mailto links, Cloudflare-protected + * addresses, and visible text. phone-numbers accepts any page and returns its + * valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel + * links and visible text; numbers without a country code are read for the country + * of the site TLD, defaulting to US. links accepts any page and returns its unique + * http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls + * back to aria-label or image alt and is null when a link has none. The emails + * parser reads the rendered page and respects content filters; the other prebuilt + * parsers read their data independently of DOM filters. */ parser: | 'google-maps' diff --git a/src/resources/web.ts b/src/resources/web.ts index 5df9b4f1..cc079926 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2752,17 +2752,18 @@ export namespace WebScrapeParams { * filters are rejected, while tracking params are ignored. It returns up to 20 * latest public reviews in data.reviews with business details and * pagination.next_offset. Each review has rating, full text, updated_at, and - * author; owner replies and photos are not included. emails accepts any page and - * returns its email addresses as data.emails ([{ email }]), read from mailto - * links, Cloudflare-protected addresses, and visible text. phone-numbers accepts - * any page and returns its valid phone numbers in E.164 as data.phone_numbers ([{ - * phone }]), read from tel links and visible text; numbers without a country code - * are read for the country of the site TLD, defaulting to US. links accepts any - * page and returns its unique http(s) links as data.links ([{ url, text }]), with - * absolute URLs; text falls back to aria-label or image alt and is null when a - * link has none. The emails parser reads the rendered page and respects content - * filters; the other prebuilt parsers read their data independently of DOM - * filters. + * author (id is the Yelp user id from the reviewer profile URL, url links to that + * profile, plus name, location, and review_count); owner replies and photos are + * not included. emails accepts any page and returns its email addresses as + * data.emails ([{ email }]), read from mailto links, Cloudflare-protected + * addresses, and visible text. phone-numbers accepts any page and returns its + * valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel + * links and visible text; numbers without a country code are read for the country + * of the site TLD, defaulting to US. links accepts any page and returns its unique + * http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls + * back to aria-label or image alt and is null when a link has none. The emails + * parser reads the rendered page and respects content filters; the other prebuilt + * parsers read their data independently of DOM filters. */ parser: | 'google-maps' From b6039e6d56b1e06588a8dba5c6b116a66281da14 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Sun, 1 Nov 2026 23:46:58 +0100 Subject: [PATCH 209/232] release: 3.22.0 (#109) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index a397c094..544a78b3 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.21.0" + ".": "3.22.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 526d8e28..13c8e6bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.22.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.21.0...v3.22.0) (2026-11-01) + + +### Features + +* **scrape:** return Yelp reviewer id and profile url in yelp-reviews ([#2402](https://github.com/context-dot-dev/context-typescript-sdk/issues/2402)) ([3f07f7e](https://github.com/context-dot-dev/context-typescript-sdk/commit/3f07f7e8b2f6be34d5f45dddf75e067e77f131ec)) + ## [3.21.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.20.0...v3.21.0) (2026-10-31) diff --git a/package.json b/package.json index 544d0b6f..97f96ecd 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.21.0", + "version": "3.22.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 623537eb..688b9afd 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.21.0'; // x-release-please-version +export const VERSION = '3.22.0'; // x-release-please-version From d1c58dc46af12cc8a3926620a935a2531e4df031 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 2 Nov 2026 02:23:06 +0000 Subject: [PATCH 210/232] feat(scrape): read framework-embedded page data in the json format (#2405) Stainless-Generated-From: 31f5839c8fe8c020ef83df9ae033e03532083c40 --- src/resources/batch.ts | 18 ++++++++++++------ src/resources/web.ts | 3 ++- 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 9c58d5a1..d103f8a2 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -483,7 +483,8 @@ export namespace BatchRetrieveResponse { images?: boolean; /** - * An object matching `jsonParams.schema`, extracted from the page. + * An object matching `jsonParams.schema`, extracted from the page text and its + * embedded data (JSON-LD, meta tags, framework state). */ json?: boolean; @@ -764,7 +765,8 @@ export namespace BatchListResponse { images?: boolean; /** - * An object matching `jsonParams.schema`, extracted from the page. + * An object matching `jsonParams.schema`, extracted from the page text and its + * embedded data (JSON-LD, meta tags, framework state). */ json?: boolean; @@ -1024,7 +1026,8 @@ export namespace BatchCancelResponse { images?: boolean; /** - * An object matching `jsonParams.schema`, extracted from the page. + * An object matching `jsonParams.schema`, extracted from the page text and its + * embedded data (JSON-LD, meta tags, framework state). */ json?: boolean; @@ -2826,7 +2829,8 @@ export namespace BatchSubmitResponse { images?: boolean; /** - * An object matching `jsonParams.schema`, extracted from the page. + * An object matching `jsonParams.schema`, extracted from the page text and its + * embedded data (JSON-LD, meta tags, framework state). */ json?: boolean; @@ -3762,7 +3766,8 @@ export namespace BatchSubmitParams { images?: boolean; /** - * An object matching `jsonParams.schema`, extracted from the page. + * An object matching `jsonParams.schema`, extracted from the page text and its + * embedded data (JSON-LD, meta tags, framework state). */ json?: boolean; @@ -5535,7 +5540,8 @@ export namespace BatchSubmitParams { images?: boolean; /** - * An object matching `jsonParams.schema`, extracted from the page. + * An object matching `jsonParams.schema`, extracted from the page text and its + * embedded data (JSON-LD, meta tags, framework state). */ json?: boolean; diff --git a/src/resources/web.ts b/src/resources/web.ts index cc079926..c4acd10a 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2505,7 +2505,8 @@ export namespace WebScrapeParams { images?: boolean; /** - * An object matching `jsonParams.schema`, extracted from the page. + * An object matching `jsonParams.schema`, extracted from the page text and its + * embedded data (JSON-LD, meta tags, framework state). */ json?: boolean; From 1c5f6bded7547829a72ea1c55e611870bb25c25e Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Mon, 2 Nov 2026 03:32:38 +0100 Subject: [PATCH 211/232] release: 3.23.0 (#110) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 544a78b3..9a723e88 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.22.0" + ".": "3.23.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 13c8e6bb..5bb99294 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.23.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.22.0...v3.23.0) (2026-11-02) + + +### Features + +* **scrape:** read framework-embedded page data in the json format ([#2405](https://github.com/context-dot-dev/context-typescript-sdk/issues/2405)) ([d1c58dc](https://github.com/context-dot-dev/context-typescript-sdk/commit/d1c58dc46af12cc8a3926620a935a2531e4df031)) + ## [3.22.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.21.0...v3.22.0) (2026-11-01) diff --git a/package.json b/package.json index 97f96ecd..6a5b9101 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.22.0", + "version": "3.23.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 688b9afd..7a09bf84 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.22.0'; // x-release-please-version +export const VERSION = '3.23.0'; // x-release-please-version From d1525f393fd8370fce4c1b820bf52c1609920650 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 4 Nov 2026 21:58:16 +0000 Subject: [PATCH 212/232] refactor(fonts): share font link schemas and inferred types Merge pull request #1838 from context-dot-dev/codex/font-faces-api Stainless-Generated-From: 1b46c62c0576ecb9f6327557d910151e773f4d30 --- src/resources/web.ts | 58 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 47 insertions(+), 11 deletions(-) diff --git a/src/resources/web.ts b/src/resources/web.ts index c4acd10a..18edc20e 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -394,8 +394,8 @@ export namespace WebExtractStyleguideResponse { /** * Font assets keyed by family name as it appears in fontFamily/fontFallbacks - * (non-generic names only). Clients match typography.fontFamily / fontWeight or - * button styles to pick a file URL from files. + * (non-generic names only). Match font style and weight against faces to select a + * file URL. */ fontLinks: { [key: string]: Styleguide.FontLinks }; @@ -695,12 +695,6 @@ export namespace WebExtractStyleguideResponse { } export interface FontLinks { - /** - * Upright font files keyed by weight string (e.g. "400" for regular, "500", - * "700"). Values are absolute URLs. - */ - files: { [key: string]: string }; - type: 'google' | 'custom'; /** @@ -710,11 +704,53 @@ export namespace WebExtractStyleguideResponse { category?: string; /** - * Present when type is custom: human-readable name derived from the fontLinks key - * (strip build/hash suffixes, split camelCase / PascalCase, normalize separators). - * Google entries omit this. + * Human-readable family name. For custom fonts, derived from the fontLinks key; + * for Google fonts, the canonical Google Fonts family name. */ displayName?: string; + + /** + * Discovered font faces, including style, weight, and distinct Unicode subsets. + */ + faces?: Array; + + /** + * @deprecated Deprecated upright font lookup keyed by weight string. A variable + * font can map several standard weight keys to the same URL; faces retains its + * actual weight range. + */ + files?: { [key: string]: string }; + } + + export namespace FontLinks { + export interface Face { + /** + * CSS font-style descriptor: normal, italic, or oblique, including an optional + * oblique angle or angle range (e.g. oblique 10deg 20deg). + */ + style: string; + + /** + * Preferred font file URL or inline font data URL. + */ + url: string; + + /** + * CSS font-weight descriptor. A variable font file can have a range such as "300 + * 500", covering intermediate weights without separate files. + */ + weight: string; + + /** + * CSS unicode-range descriptor. + */ + unicodeRange?: string; + + /** + * CSS font-width or font-stretch descriptor. + */ + width?: string; + } } /** From b9406061f6b1984f83ad365e69e7621d6e621e49 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Wed, 4 Nov 2026 23:03:49 +0100 Subject: [PATCH 213/232] release: 3.23.1 (#113) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 9a723e88..20a7901c 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.23.0" + ".": "3.23.1" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 5bb99294..7e9f296a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.23.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.23.0...v3.23.1) (2026-11-04) + + +### Refactors + +* **fonts:** share font link schemas and inferred types ([d1525f3](https://github.com/context-dot-dev/context-typescript-sdk/commit/d1525f393fd8370fce4c1b820bf52c1609920650)) + ## [3.23.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.22.0...v3.23.0) (2026-11-02) diff --git a/package.json b/package.json index 6a5b9101..c112e009 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.23.0", + "version": "3.23.1", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 7a09bf84..54ab056f 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.23.0'; // x-release-please-version +export const VERSION = '3.23.1'; // x-release-please-version From 191a060897c65270acf9b9421ef3b6516c54ddcc Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 5 Nov 2026 02:45:19 +0000 Subject: [PATCH 214/232] feat(scrape): add Tripadvisor reviews parser (#2508) Stainless-Generated-From: 5617a28138be4025d6385ea97d4bffd23b94f42c --- src/resources/batch.ts | 78 +++++++++++++++++++++++++++++------------- src/resources/web.ts | 39 ++++++++++++++------- 2 files changed, 81 insertions(+), 36 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index d103f8a2..830a117c 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -1232,7 +1232,9 @@ export namespace BatchGetResultsResponse { * data.users, yelp-search returns up to 20 ranked organic businesses in * data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews * returns up to 20 latest public reviews in data.reviews, with business details - * and next_offset, from a Yelp business URL; emails, phone-numbers, and links + * and next_offset, from a Yelp business URL; tripadvisor-reviews returns 20 + * reviews in data.reviews, with data.location and next_offset, from a Tripadvisor + * hotel, restaurant, or attraction review URL; emails, phone-numbers, and links * return data.emails, data.phone_numbers, and data.links from the rendered page; * the store, Maps, G2, Instagram, and TikTok parsers read their data directly, * independently of DOM filters and other outputs. @@ -1635,7 +1637,9 @@ export namespace BatchGetResultsResponse { * data.users, yelp-search returns up to 20 ranked organic businesses in * data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews * returns up to 20 latest public reviews in data.reviews, with business details - * and next_offset, from a Yelp business URL; emails, phone-numbers, and links + * and next_offset, from a Yelp business URL; tripadvisor-reviews returns 20 + * reviews in data.reviews, with data.location and next_offset, from a Tripadvisor + * hotel, restaurant, or attraction review URL; emails, phone-numbers, and links * return data.emails, data.phone_numbers, and data.links from the rendered page; * the store, Maps, G2, Instagram, and TikTok parsers read their data directly, * independently of DOM filters and other outputs. @@ -1679,6 +1683,7 @@ export namespace BatchGetResultsResponse { | 'reddit-user' | 'yelp-search' | 'yelp-reviews' + | 'tripadvisor-reviews' | 'emails' | 'phone-numbers' | 'links'; @@ -2016,7 +2021,9 @@ export namespace BatchGetResultsResponse { * data.users, yelp-search returns up to 20 ranked organic businesses in * data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews * returns up to 20 latest public reviews in data.reviews, with business details - * and next_offset, from a Yelp business URL; emails, phone-numbers, and links + * and next_offset, from a Yelp business URL; tripadvisor-reviews returns 20 + * reviews in data.reviews, with data.location and next_offset, from a Tripadvisor + * hotel, restaurant, or attraction review URL; emails, phone-numbers, and links * return data.emails, data.phone_numbers, and data.links from the rendered page; * the store, Maps, G2, Instagram, and TikTok parsers read their data directly, * independently of DOM filters and other outputs. @@ -2419,7 +2426,9 @@ export namespace BatchGetResultsResponse { * data.users, yelp-search returns up to 20 ranked organic businesses in * data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews * returns up to 20 latest public reviews in data.reviews, with business details - * and next_offset, from a Yelp business URL; emails, phone-numbers, and links + * and next_offset, from a Yelp business URL; tripadvisor-reviews returns 20 + * reviews in data.reviews, with data.location and next_offset, from a Tripadvisor + * hotel, restaurant, or attraction review URL; emails, phone-numbers, and links * return data.emails, data.phone_numbers, and data.links from the rendered page; * the store, Maps, G2, Instagram, and TikTok parsers read their data directly, * independently of DOM filters and other outputs. @@ -2463,6 +2472,7 @@ export namespace BatchGetResultsResponse { | 'reddit-user' | 'yelp-search' | 'yelp-reviews' + | 'tripadvisor-reviews' | 'emails' | 'phone-numbers' | 'links'; @@ -4037,16 +4047,25 @@ export namespace BatchSubmitParams { * pagination.next_offset. Each review has rating, full text, updated_at, and * author (id is the Yelp user id from the reviewer profile URL, url links to that * profile, plus name, location, and review_count); owner replies and photos are - * not included. emails accepts any page and returns its email addresses as - * data.emails ([{ email }]), read from mailto links, Cloudflare-protected - * addresses, and visible text. phone-numbers accepts any page and returns its - * valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel - * links and visible text; numbers without a country code are read for the country - * of the site TLD, defaulting to US. links accepts any page and returns its unique - * http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls - * back to aria-label or image alt and is null when a link has none. The emails - * parser reads the rendered page and respects content filters; the other prebuilt - * parsers read their data independently of DOM filters. + * not included. tripadvisor-reviews accepts a Tripadvisor hotel, restaurant, or + * attraction review URL (tripadvisor.com/Hotel_Review-g{geo}-d{id}-Reviews-….html, + * on any Tripadvisor country domain), reads -or{N}- in the path as the offset, and + * returns 20 reviews in data.reviews in the order Tripadvisor shows them, with + * data.location (id, name, type, url, review_count) and pagination.next_offset. + * Each review has id, url, title, full text, rating, language, published_at, + * visit_month, helpful_votes, subratings, photo_urls, owner_response (text, + * published_at, author_name), and author (id, username, name, url, + * contribution_count); an unknown location returns no reviews. emails accepts any + * page and returns its email addresses as data.emails ([{ email }]), read from + * mailto links, Cloudflare-protected addresses, and visible text. phone-numbers + * accepts any page and returns its valid phone numbers in E.164 as + * data.phone_numbers ([{ phone }]), read from tel links and visible text; numbers + * without a country code are read for the country of the site TLD, defaulting to + * US. links accepts any page and returns its unique http(s) links as data.links + * ([{ url, text }]), with absolute URLs; text falls back to aria-label or image + * alt and is null when a link has none. The emails parser reads the rendered page + * and respects content filters; the other prebuilt parsers read their data + * independently of DOM filters. */ parser: | 'google-maps' @@ -4072,6 +4091,7 @@ export namespace BatchSubmitParams { | 'reddit-user' | 'yelp-search' | 'yelp-reviews' + | 'tripadvisor-reviews' | 'emails' | 'phone-numbers' | 'links'; @@ -5973,16 +5993,25 @@ export namespace BatchSubmitParams { * pagination.next_offset. Each review has rating, full text, updated_at, and * author (id is the Yelp user id from the reviewer profile URL, url links to that * profile, plus name, location, and review_count); owner replies and photos are - * not included. emails accepts any page and returns its email addresses as - * data.emails ([{ email }]), read from mailto links, Cloudflare-protected - * addresses, and visible text. phone-numbers accepts any page and returns its - * valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel - * links and visible text; numbers without a country code are read for the country - * of the site TLD, defaulting to US. links accepts any page and returns its unique - * http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls - * back to aria-label or image alt and is null when a link has none. The emails - * parser reads the rendered page and respects content filters; the other prebuilt - * parsers read their data independently of DOM filters. + * not included. tripadvisor-reviews accepts a Tripadvisor hotel, restaurant, or + * attraction review URL (tripadvisor.com/Hotel_Review-g{geo}-d{id}-Reviews-….html, + * on any Tripadvisor country domain), reads -or{N}- in the path as the offset, and + * returns 20 reviews in data.reviews in the order Tripadvisor shows them, with + * data.location (id, name, type, url, review_count) and pagination.next_offset. + * Each review has id, url, title, full text, rating, language, published_at, + * visit_month, helpful_votes, subratings, photo_urls, owner_response (text, + * published_at, author_name), and author (id, username, name, url, + * contribution_count); an unknown location returns no reviews. emails accepts any + * page and returns its email addresses as data.emails ([{ email }]), read from + * mailto links, Cloudflare-protected addresses, and visible text. phone-numbers + * accepts any page and returns its valid phone numbers in E.164 as + * data.phone_numbers ([{ phone }]), read from tel links and visible text; numbers + * without a country code are read for the country of the site TLD, defaulting to + * US. links accepts any page and returns its unique http(s) links as data.links + * ([{ url, text }]), with absolute URLs; text falls back to aria-label or image + * alt and is null when a link has none. The emails parser reads the rendered page + * and respects content filters; the other prebuilt parsers read their data + * independently of DOM filters. */ parser: | 'google-maps' @@ -6008,6 +6037,7 @@ export namespace BatchSubmitParams { | 'reddit-user' | 'yelp-search' | 'yelp-reviews' + | 'tripadvisor-reviews' | 'emails' | 'phone-numbers' | 'links'; diff --git a/src/resources/web.ts b/src/resources/web.ts index 18edc20e..be17b890 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1004,7 +1004,9 @@ export interface WebScrapeResponse { * data.users, yelp-search returns up to 20 ranked organic businesses in * data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews * returns up to 20 latest public reviews in data.reviews, with business details - * and next_offset, from a Yelp business URL; emails, phone-numbers, and links + * and next_offset, from a Yelp business URL; tripadvisor-reviews returns 20 + * reviews in data.reviews, with data.location and next_offset, from a Tripadvisor + * hotel, restaurant, or attraction review URL; emails, phone-numbers, and links * return data.emails, data.phone_numbers, and data.links from the rendered page; * the store, Maps, G2, Instagram, and TikTok parsers read their data directly, * independently of DOM filters and other outputs. @@ -1407,7 +1409,9 @@ export namespace WebScrapeResponse { * data.users, yelp-search returns up to 20 ranked organic businesses in * data.businesses, plus total and pagination, from a Yelp search URL; yelp-reviews * returns up to 20 latest public reviews in data.reviews, with business details - * and next_offset, from a Yelp business URL; emails, phone-numbers, and links + * and next_offset, from a Yelp business URL; tripadvisor-reviews returns 20 + * reviews in data.reviews, with data.location and next_offset, from a Tripadvisor + * hotel, restaurant, or attraction review URL; emails, phone-numbers, and links * return data.emails, data.phone_numbers, and data.links from the rendered page; * the store, Maps, G2, Instagram, and TikTok parsers read their data directly, * independently of DOM filters and other outputs. @@ -1451,6 +1455,7 @@ export namespace WebScrapeResponse { | 'reddit-user' | 'yelp-search' | 'yelp-reviews' + | 'tripadvisor-reviews' | 'emails' | 'phone-numbers' | 'links'; @@ -2791,16 +2796,25 @@ export namespace WebScrapeParams { * pagination.next_offset. Each review has rating, full text, updated_at, and * author (id is the Yelp user id from the reviewer profile URL, url links to that * profile, plus name, location, and review_count); owner replies and photos are - * not included. emails accepts any page and returns its email addresses as - * data.emails ([{ email }]), read from mailto links, Cloudflare-protected - * addresses, and visible text. phone-numbers accepts any page and returns its - * valid phone numbers in E.164 as data.phone_numbers ([{ phone }]), read from tel - * links and visible text; numbers without a country code are read for the country - * of the site TLD, defaulting to US. links accepts any page and returns its unique - * http(s) links as data.links ([{ url, text }]), with absolute URLs; text falls - * back to aria-label or image alt and is null when a link has none. The emails - * parser reads the rendered page and respects content filters; the other prebuilt - * parsers read their data independently of DOM filters. + * not included. tripadvisor-reviews accepts a Tripadvisor hotel, restaurant, or + * attraction review URL (tripadvisor.com/Hotel_Review-g{geo}-d{id}-Reviews-….html, + * on any Tripadvisor country domain), reads -or{N}- in the path as the offset, and + * returns 20 reviews in data.reviews in the order Tripadvisor shows them, with + * data.location (id, name, type, url, review_count) and pagination.next_offset. + * Each review has id, url, title, full text, rating, language, published_at, + * visit_month, helpful_votes, subratings, photo_urls, owner_response (text, + * published_at, author_name), and author (id, username, name, url, + * contribution_count); an unknown location returns no reviews. emails accepts any + * page and returns its email addresses as data.emails ([{ email }]), read from + * mailto links, Cloudflare-protected addresses, and visible text. phone-numbers + * accepts any page and returns its valid phone numbers in E.164 as + * data.phone_numbers ([{ phone }]), read from tel links and visible text; numbers + * without a country code are read for the country of the site TLD, defaulting to + * US. links accepts any page and returns its unique http(s) links as data.links + * ([{ url, text }]), with absolute URLs; text falls back to aria-label or image + * alt and is null when a link has none. The emails parser reads the rendered page + * and respects content filters; the other prebuilt parsers read their data + * independently of DOM filters. */ parser: | 'google-maps' @@ -2826,6 +2840,7 @@ export namespace WebScrapeParams { | 'reddit-user' | 'yelp-search' | 'yelp-reviews' + | 'tripadvisor-reviews' | 'emails' | 'phone-numbers' | 'links'; From 7f230efabea350d814ffa8d7bb3dcb2c5e1e8690 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Thu, 5 Nov 2026 04:04:27 +0100 Subject: [PATCH 215/232] release: 3.24.0 (#114) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 20a7901c..6973dab8 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.23.1" + ".": "3.24.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e9f296a..70e95435 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.24.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.23.1...v3.24.0) (2026-11-05) + + +### Features + +* **scrape:** add Tripadvisor reviews parser ([#2508](https://github.com/context-dot-dev/context-typescript-sdk/issues/2508)) ([191a060](https://github.com/context-dot-dev/context-typescript-sdk/commit/191a060897c65270acf9b9421ef3b6516c54ddcc)) + ## [3.23.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.23.0...v3.23.1) (2026-11-04) diff --git a/package.json b/package.json index c112e009..df7ffb32 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.23.1", + "version": "3.24.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 54ab056f..2ae21c90 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.23.1'; // x-release-please-version +export const VERSION = '3.24.0'; // x-release-please-version From d28f0e97c76160ff12608ab796dc716e26c96dcf Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 5 Nov 2026 15:27:28 +0000 Subject: [PATCH 216/232] docs(logs): say that a request log appears a few seconds after the request (#2564) Stainless-Generated-From: 67880b0c97f3405d90a2489b5f0a85350d4e119e --- src/resources/logs.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/resources/logs.ts b/src/resources/logs.ts index 08c45928..67195830 100644 --- a/src/resources/logs.ts +++ b/src/resources/logs.ts @@ -10,7 +10,10 @@ import { path } from '../internal/utils/path'; */ export class Logs extends APIResource { /** - * Retrieve a request’s metadata, retained input, and response. + * Retrieve a request’s metadata, retained input, and response. An entry becomes + * retrievable a few seconds after its request completes, so a 404 NOT_FOUND for a + * request that just finished means ingestion has not caught up yet; retry after a + * few seconds. */ retrieve(requestID: string, options?: RequestOptions): APIPromise { return this._client.get(path`/org/logs/${requestID}`, options); From f64aa30868451e07b823b5bdfbafcac6062c58fa Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Thu, 5 Nov 2026 16:32:30 +0100 Subject: [PATCH 217/232] release: 3.24.1 (#115) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 6973dab8..6d298faa 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.24.0" + ".": "3.24.1" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 70e95435..f61b8c67 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.24.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.24.0...v3.24.1) (2026-11-05) + + +### Documentation + +* **logs:** say that a request log appears a few seconds after the request ([#2564](https://github.com/context-dot-dev/context-typescript-sdk/issues/2564)) ([d28f0e9](https://github.com/context-dot-dev/context-typescript-sdk/commit/d28f0e97c76160ff12608ab796dc716e26c96dcf)) + ## [3.24.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.23.1...v3.24.0) (2026-11-05) diff --git a/package.json b/package.json index df7ffb32..22cb7da5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.24.0", + "version": "3.24.1", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 2ae21c90..d31450be 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.24.0'; // x-release-please-version +export const VERSION = '3.24.1'; // x-release-please-version From 14f386b89dff3f0ed647c2a0a912c66434b68111 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sat, 7 Nov 2026 03:13:03 +0000 Subject: [PATCH 218/232] feat(batch): accept lightweight submissions and queue pending work (#2683) Stainless-Generated-From: 94422f67bfbb2a2ab9f03105dd17a426d6462c1c --- src/resources/batch.ts | 43 +++++++++++++++++++++---------- tests/api-resources/batch.test.ts | 2 +- 2 files changed, 30 insertions(+), 15 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 830a117c..4adf9b1a 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -89,8 +89,15 @@ export class Batch extends APIResource { /** * 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. + * 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. * * @example * ```ts @@ -405,9 +412,11 @@ export interface BatchRetrieveResponse { results: BatchRetrieveResponse.Results | null; /** - * 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. */ - status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; + status: 'pending' | 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; /** * Tags stored on the batch at submission. @@ -453,7 +462,8 @@ export namespace BatchRetrieveResponse { refunded: number; /** - * Credits held when the batch was accepted. + * Credits held by background preparation before scraping starts. Zero while + * pending. */ reserved: number; } @@ -697,9 +707,11 @@ export namespace BatchListResponse { results: Data.Results | null; /** - * 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. */ - status: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; + status: 'pending' | 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; /** * Tags stored on the batch at submission. @@ -735,7 +747,8 @@ export namespace BatchListResponse { refunded: number; /** - * Credits held when the batch was accepted. + * Credits held by background preparation before scraping starts. Zero while + * pending. */ reserved: number; } @@ -2736,7 +2749,7 @@ export interface BatchSubmitResponse { created_at: string; /** - * What accepting this batch cost. + * Credits are reserved after background validation, before scraping starts. */ credits: BatchSubmitResponse.Credits; @@ -2767,9 +2780,11 @@ export interface BatchSubmitResponse { request_id: string; /** - * 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. */ - status: 'queued'; + status: 'pending' | 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; /** * Tags stored on the batch. @@ -2805,11 +2820,11 @@ export namespace BatchSubmitResponse { } /** - * What accepting this batch cost. + * Credits are reserved after background validation, before scraping starts. */ export interface Credits { /** - * Credits held at submission. + * Credits reserved by background preparation. Zero while pending. */ reserved: number; } @@ -2924,7 +2939,7 @@ export interface BatchListParams { /** * Filter by status. */ - status?: 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; + status?: 'pending' | 'queued' | 'running' | 'cancelling' | 'completed' | 'cancelled' | 'failed'; /** * Tags to filter by (matches batches having any of them). Pass repeated `tags` diff --git a/tests/api-resources/batch.test.ts b/tests/api-resources/batch.test.ts index 8c362e4b..36e4c04c 100644 --- a/tests/api-resources/batch.test.ts +++ b/tests/api-resources/batch.test.ts @@ -43,7 +43,7 @@ describe('resource batch', () => { q: 'batch_1a2b', search_type: 'exact', shouldIncludeUnified: true, - status: 'queued', + status: 'pending', tags: 'docs,competitor', }, { path: '/_stainless_unknown_path' }, From 70f4167ec231f0ff80db8c89685c1188edfff677 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Sat, 7 Nov 2026 04:17:27 +0100 Subject: [PATCH 219/232] release: 3.25.0 (#116) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 6d298faa..c3511605 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.24.1" + ".": "3.25.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index f61b8c67..940f2e48 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.25.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.24.1...v3.25.0) (2026-11-07) + + +### Features + +* **batch:** accept lightweight submissions and queue pending work ([#2683](https://github.com/context-dot-dev/context-typescript-sdk/issues/2683)) ([14f386b](https://github.com/context-dot-dev/context-typescript-sdk/commit/14f386b89dff3f0ed647c2a0a912c66434b68111)) + ## [3.24.1](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.24.0...v3.24.1) (2026-11-05) diff --git a/package.json b/package.json index 22cb7da5..fcd8a976 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.24.1", + "version": "3.25.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index d31450be..55ab1ede 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.24.1'; // x-release-please-version +export const VERSION = '3.25.0'; // x-release-please-version From 2bbef8a6784dfd2b7847c20aeba8ecca0e41c1ff Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Sun, 8 Nov 2026 03:20:50 +0000 Subject: [PATCH 220/232] feat(batch): raise batch submissions to 2,500 per minute per organization (#2734) Stainless-Generated-From: 11624fb70c4e37eb1e85990977b5c3dc3d40f34e --- src/resources/batch.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 4adf9b1a..a2262dbe 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -92,7 +92,7 @@ export class Batch extends APIResource { * 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, + * with 402 up front. Each organization can submit up to 2,500 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 From bcf9f7b8304e72d22a519f89d134840f2aed898a Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Sun, 8 Nov 2026 04:32:30 +0100 Subject: [PATCH 221/232] release: 3.26.0 (#117) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index c3511605..f23e8d0e 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.25.0" + ".": "3.26.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 940f2e48..442429b7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.26.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.25.0...v3.26.0) (2026-11-08) + + +### Features + +* **batch:** raise batch submissions to 2,500 per minute per organization ([#2734](https://github.com/context-dot-dev/context-typescript-sdk/issues/2734)) ([2bbef8a](https://github.com/context-dot-dev/context-typescript-sdk/commit/2bbef8a6784dfd2b7847c20aeba8ecca0e41c1ff)) + ## [3.25.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.24.1...v3.25.0) (2026-11-07) diff --git a/package.json b/package.json index fcd8a976..7e539b09 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.25.0", + "version": "3.26.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 55ab1ede..b6b70008 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.25.0'; // x-release-please-version +export const VERSION = '3.26.0'; // x-release-please-version From 5e89196bfdddcddf3e88d646495b7ed0457aa356 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 9 Nov 2026 14:26:39 +0000 Subject: [PATCH 222/232] feat(batches): let sitemap crawls choose which paths count as non-pages (#2796) Stainless-Generated-From: 46407fc9c541f3c27829ad5006e258083de1413e --- src/resources/batch.ts | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index a2262dbe..c7fc5627 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -4660,6 +4660,14 @@ export namespace BatchSubmitParams { * URLs and never follows links off them, so there is no crawl depth here. */ export interface Controls { + /** + * Path fragments that skip a sitemap URL in a crawl. Works separately from any + * regex inclusion or exclusion you define. Defaults to + * ["/feed","/rss","/atom","/api/","/cdn-cgi/","/_next/","/__"]. Pass `[]` to keep + * every listed URL. + */ + excludePaths?: Array; + /** * Regex pattern; sitemap URLs matching it are not scraped, even when they match * `regex`. @@ -5171,6 +5179,14 @@ export namespace BatchSubmitParams { * URLs and never follows links off them, so there is no crawl depth here. */ export interface Controls { + /** + * Path fragments that skip a sitemap URL in a crawl. Works separately from any + * regex inclusion or exclusion you define. Defaults to + * ["/feed","/rss","/atom","/api/","/cdn-cgi/","/_next/","/__"]. Pass `[]` to keep + * every listed URL. + */ + excludePaths?: Array; + /** * Regex pattern; sitemap URLs matching it are not scraped, even when they match * `regex`. @@ -5766,6 +5782,14 @@ export namespace BatchSubmitParams { * URLs and never follows links off them, so there is no crawl depth here. */ export interface Controls { + /** + * Path fragments that skip a sitemap URL in a crawl. Works separately from any + * regex inclusion or exclusion you define. Defaults to + * ["/feed","/rss","/atom","/api/","/cdn-cgi/","/_next/","/__"]. Pass `[]` to keep + * every listed URL. + */ + excludePaths?: Array; + /** * Regex pattern; sitemap URLs matching it are not scraped, even when they match * `regex`. From d71b558b274bb6c2ff7ae15673f7b2f13808a055 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Mon, 9 Nov 2026 15:32:58 +0100 Subject: [PATCH 223/232] release: 3.27.0 (#118) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index f23e8d0e..31cca47c 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.26.0" + ".": "3.27.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 442429b7..1363d739 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.27.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.26.0...v3.27.0) (2026-11-09) + + +### Features + +* **batches:** let sitemap crawls choose which paths count as non-pages ([#2796](https://github.com/context-dot-dev/context-typescript-sdk/issues/2796)) ([5e89196](https://github.com/context-dot-dev/context-typescript-sdk/commit/5e89196bfdddcddf3e88d646495b7ed0457aa356)) + ## [3.26.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.25.0...v3.26.0) (2026-11-08) diff --git a/package.json b/package.json index 7e539b09..c956f878 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.26.0", + "version": "3.27.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index b6b70008..cac0048d 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.26.0'; // x-release-please-version +export const VERSION = '3.27.0'; // x-release-please-version From 0c7797dc97ee6374404f5e60e2cf26b2a39fa98f Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Mon, 9 Nov 2026 17:14:45 +0000 Subject: [PATCH 224/232] feat(parse): support WARC archives in parsing and scraping (#2761) Stainless-Generated-From: 1f3613aca9570731b43207251433017bddfe8dc0 --- src/resources/parse.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/resources/parse.ts b/src/resources/parse.ts index 09ef1142..53b77fa6 100644 --- a/src/resources/parse.ts +++ b/src/resources/parse.ts @@ -8,7 +8,10 @@ import { RequestOptions } from '../internal/request-options'; export class Parse extends APIResource { /** - * Convert uploaded file bytes into Markdown and optional HTML. + * Convert uploaded file bytes into Markdown and optional HTML. WARC and WARC.GZ + * archives combine HTTP response, resource, and conversion records in archive + * order. Revisit and segmented records are skipped. Decoded WARC content is + * limited to 50 MiB. */ handle( body: Uploadable, @@ -70,6 +73,7 @@ export interface ParseHandleResponse { * Detected content type used for parsing */ type: + | 'warc' | 'html' | 'xml' | 'json' @@ -143,9 +147,11 @@ export interface ParseHandleParams { /** * Query param: Optional file extension hint, such as pdf, docx, xlsx, pptx, html, - * json, csv, md, py, rtf, jpg, png, or txt. + * json, csv, md, py, rtf, jpg, png, txt, warc, or warc.gz. */ extension?: + | 'warc' + | 'warc.gz' | 'txt' | 'text' | 'md' From 8882225cb9a32b98e27bf577c0ff4c8646d2d7b7 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Mon, 9 Nov 2026 18:32:36 +0100 Subject: [PATCH 225/232] release: 3.28.0 (#119) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 31cca47c..24f0e248 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.27.0" + ".": "3.28.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 1363d739..3ac72881 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.28.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.27.0...v3.28.0) (2026-11-09) + + +### Features + +* **parse:** support WARC archives in parsing and scraping ([#2761](https://github.com/context-dot-dev/context-typescript-sdk/issues/2761)) ([0c7797d](https://github.com/context-dot-dev/context-typescript-sdk/commit/0c7797dc97ee6374404f5e60e2cf26b2a39fa98f)) + ## [3.27.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.26.0...v3.27.0) (2026-11-09) diff --git a/package.json b/package.json index c956f878..6b52d34d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.27.0", + "version": "3.28.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index cac0048d..91178c39 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.27.0'; // x-release-please-version +export const VERSION = '3.28.0'; // x-release-please-version From 9fe54db4a020ef232b93a440953bfb483ce67ece Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Wed, 11 Nov 2026 18:16:13 +0000 Subject: [PATCH 226/232] Build SDK Stainless-Generated-From: ac7885f4c3e867f574e427c1357b842d19951356 --- yarn.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/yarn.lock b/yarn.lock index a3d6b14e..bac6f2fe 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1228,9 +1228,9 @@ baseline-browser-mapping@^2.9.0: integrity sha512-B0xUquLkiGLgHhpPBqvl7GWegWBUNuujQ6kXd/r1U38ElPT6Ok8KZ8e+FpUGEc2ZoRQUzq/aUnaKFc/svWUGSg== brace-expansion@^2.0.2: - version "2.1.7" - resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.1.7.tgz#14ea3836731823bb24740225ea43b941b436f9d1" - integrity sha512-uZbew1NqdmPDTMJ8ah1y+b+9QEJrfkXFk3RcTQw3X0jW/xRUvFKsg1CfQdSYGdTbXZWExtU3J3ccxtnfw1Fi0g== + version "2.1.8" + resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.1.8.tgz#b4cf1e18069418e97732d5f30b39bb321c41bd9b" + integrity sha512-BnlDzDYQoplTsZSvPi86CNzmbcb07X8ufR8fk1zivaiEJlXJkiq1MQyDCVmlWcsWbj6aWXqHnrwwevbrm/Saig== dependencies: balanced-match "^1.0.0" From 26775ce98bcecbea0824548f6665012dd750a539 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Thu, 12 Nov 2026 06:23:41 +0000 Subject: [PATCH 227/232] feat(zdr): accept zero data retention on people search and company search (#2852) Stainless-Generated-From: 0a6f320653b10c008c57f91599ea0698d7acfede --- src/resources/people.ts | 6 ++++++ tests/api-resources/people.test.ts | 1 + 2 files changed, 7 insertions(+) diff --git a/src/resources/people.ts b/src/resources/people.ts index 416f7785..68b90aa7 100644 --- a/src/resources/people.ts +++ b/src/resources/people.ts @@ -655,6 +655,12 @@ export interface PersonSearchParams { * Labels for filtering usage in the dashboard. */ tags?: Array; + + /** + * `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless + * your organization has ZDR. + */ + zdr?: 'enabled' | 'disabled'; } export namespace PersonSearchParams { diff --git a/tests/api-resources/people.test.ts b/tests/api-resources/people.test.ts index 4f9d2737..10746f53 100644 --- a/tests/api-resources/people.test.ts +++ b/tests/api-resources/people.test.ts @@ -44,6 +44,7 @@ describe('resource people', () => { }, mode: 'fast', tags: ['production', 'team-alpha'], + zdr: 'enabled', }); }); }); From 6d9ab66ed7bc94da97e63c9306d1e65b0bbde9bc Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Thu, 12 Nov 2026 07:38:57 +0100 Subject: [PATCH 228/232] release: 3.29.0 (#120) --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 24f0e248..365bf72e 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.28.0" + ".": "3.29.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ac72881..7cf5c7fb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [3.29.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.28.0...v3.29.0) (2026-11-12) + + +### Features + +* **zdr:** accept zero data retention on people search and company search ([#2852](https://github.com/context-dot-dev/context-typescript-sdk/issues/2852)) ([26775ce](https://github.com/context-dot-dev/context-typescript-sdk/commit/26775ce98bcecbea0824548f6665012dd750a539)) + ## [3.28.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.27.0...v3.28.0) (2026-11-09) diff --git a/package.json b/package.json index 6b52d34d..0612906b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.28.0", + "version": "3.29.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 91178c39..644b8891 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.28.0'; // x-release-please-version +export const VERSION = '3.29.0'; // x-release-please-version From 16a84a80ac73485be395ced4b7c7c5ed585e53a2 Mon Sep 17 00:00:00 2001 From: stlc-bot Date: Tue, 17 Nov 2026 18:10:43 +0000 Subject: [PATCH 229/232] feat(billing): report plan facts in usage and limit errors (#2897) docs(scrape): mention transcripts on the Markdown format (#2903) ci(sdks): replace the SDK and cross-repo PATs with GitHub Apps (#2931) Stainless-Generated-From: ac808852eb554c06212f88fa11b59f39e976ac4b --- src/resources/batch.ts | 12 ++++++------ src/resources/web.ts | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/resources/batch.ts b/src/resources/batch.ts index c7fc5627..f4170f1e 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -499,7 +499,7 @@ export namespace BatchRetrieveResponse { json?: boolean; /** - * Page content as Markdown. + * Page content or video transcript as Markdown. */ markdown?: boolean; @@ -784,7 +784,7 @@ export namespace BatchListResponse { json?: boolean; /** - * Page content as Markdown. + * Page content or video transcript as Markdown. */ markdown?: boolean; @@ -1045,7 +1045,7 @@ export namespace BatchCancelResponse { json?: boolean; /** - * Page content as Markdown. + * Page content or video transcript as Markdown. */ markdown?: boolean; @@ -2860,7 +2860,7 @@ export namespace BatchSubmitResponse { json?: boolean; /** - * Page content as Markdown. + * Page content or video transcript as Markdown. */ markdown?: boolean; @@ -3797,7 +3797,7 @@ export namespace BatchSubmitParams { json?: boolean; /** - * Page content as Markdown. + * Page content or video transcript as Markdown. */ markdown?: boolean; @@ -5597,7 +5597,7 @@ export namespace BatchSubmitParams { json?: boolean; /** - * Page content as Markdown. + * Page content or video transcript as Markdown. */ markdown?: boolean; diff --git a/src/resources/web.ts b/src/resources/web.ts index be17b890..f178d53d 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -2552,7 +2552,7 @@ export namespace WebScrapeParams { json?: boolean; /** - * Page content as Markdown. + * Page content or video transcript as Markdown. */ markdown?: boolean; From 79ed995ce1e37170c302bdd927f27dd4a0793ab5 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Tue, 17 Nov 2026 19:28:15 +0100 Subject: [PATCH 230/232] chore: run release-please centrally from brand-dev-server --- .github/workflows/release-please.yml | 20 -------------------- 1 file changed, 20 deletions(-) delete mode 100644 .github/workflows/release-please.yml diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml deleted file mode 100644 index c0210fa8..00000000 --- a/.github/workflows/release-please.yml +++ /dev/null @@ -1,20 +0,0 @@ -name: Release Please -on: - push: - branches: - - main - -permissions: - contents: write - pull-requests: write - -jobs: - release-please: - if: github.repository == 'context-dot-dev/context-typescript-sdk' - runs-on: ubuntu-latest - - steps: - - uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071 # v4.4.1 - id: release - with: - token: ${{ secrets.RELEASE_PLEASE_TOKEN }} From 7e203326f1044abbdd282f0470d9648ac22216fc Mon Sep 17 00:00:00 2001 From: "context-cross-repo-prod-writer[bot]" <346404843+context-cross-repo-prod-writer[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:47:32 +0000 Subject: [PATCH 231/232] release: 3.30.0 (#121) Co-authored-by: context-cross-repo-prod-writer[bot] <346404843+context-cross-repo-prod-writer[bot]@users.noreply.github.com> --- .release-please-manifest.json | 2 +- CHANGELOG.md | 17 +++++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 20 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 365bf72e..26b4a530 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.29.0" + ".": "3.30.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 7cf5c7fb..7971ef55 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,22 @@ # Changelog +## [3.30.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.29.0...v3.30.0) (2026-11-17) + + +### Features + +* **billing:** report plan facts in usage and limit errors ([#2897](https://github.com/context-dot-dev/context-typescript-sdk/issues/2897)) ([16a84a8](https://github.com/context-dot-dev/context-typescript-sdk/commit/16a84a80ac73485be395ced4b7c7c5ed585e53a2)) + + +### Chores + +* run release-please centrally from brand-dev-server ([79ed995](https://github.com/context-dot-dev/context-typescript-sdk/commit/79ed995ce1e37170c302bdd927f27dd4a0793ab5)) + + +### Documentation + +* **scrape:** mention transcripts on the Markdown format ([#2903](https://github.com/context-dot-dev/context-typescript-sdk/issues/2903)) ([16a84a8](https://github.com/context-dot-dev/context-typescript-sdk/commit/16a84a80ac73485be395ced4b7c7c5ed585e53a2)) + ## [3.29.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v3.28.0...v3.29.0) (2026-11-12) diff --git a/package.json b/package.json index 0612906b..95c6843a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "3.29.0", + "version": "3.30.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index 644b8891..c5853f42 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '3.29.0'; // x-release-please-version +export const VERSION = '3.30.0'; // x-release-please-version From 59030a009ff8ae47b3b6f7a11d7cc9fb42f48586 Mon Sep 17 00:00:00 2001 From: Beer van der Drift Date: Wed, 18 Nov 2026 16:21:48 +0200 Subject: [PATCH 232/232] ci: run the publish job in the production environment (#10) The production environment will be limited to v* tags, so publish credentials only reach runs on a protected release tag. Co-authored-by: Beer van der Drift Co-authored-by: Claude Opus 5.5 --- .github/workflows/publish-npm.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml index 3fb3af8c..b7538a54 100644 --- a/.github/workflows/publish-npm.yml +++ b/.github/workflows/publish-npm.yml @@ -18,6 +18,7 @@ jobs: name: publish if: github.repository == 'context-dot-dev/context-typescript-sdk' runs-on: ubuntu-latest + environment: production permissions: contents: read id-token: write