diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2e524f2..2bcb4cf 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -21,7 +21,7 @@ jobs: permissions: contents: read id-token: write - runs-on: ${{ github.repository == 'stainless-sdks/context.dev-go' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} + runs-on: ${{ startsWith(github.repository, 'stainless-sdks/') && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} if: |- github.repository == 'stainless-sdks/context.dev-go' && (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata') @@ -49,7 +49,7 @@ jobs: lint: timeout-minutes: 10 name: lint - runs-on: ${{ github.repository == 'stainless-sdks/context.dev-go' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} + runs-on: ${{ startsWith(github.repository, 'stainless-sdks/') && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} if: github.event_name == 'push' || github.event.pull_request.head.repo.fork steps: @@ -65,7 +65,7 @@ jobs: test: timeout-minutes: 10 name: test - runs-on: ${{ github.repository == 'stainless-sdks/context.dev-go' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} + runs-on: ${{ startsWith(github.repository, 'stainless-sdks/') && 'depot-ubuntu-24.04' || 'ubuntu-latest' }} if: github.event_name == 'push' || github.event.pull_request.head.repo.fork steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 diff --git a/.release-please-manifest.json b/.release-please-manifest.json index b44b287..4dedeae 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.4.0" + ".": "2.5.0" } \ No newline at end of file diff --git a/.stats.yml b/.stats.yml index 7cfdbba..0ac1eb3 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ -configured_endpoints: 30 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-fb56935a194e69348fecd985f7cf8b249795b46af2fb32f6c5c8ef648cf10c15.yml -openapi_spec_hash: 7260a560474283b7ad6ac5d426058ac9 -config_hash: daabb160675d86b354711da1e77e5129 +configured_endpoints: 32 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-242450ea46eb8c3e843fd6c4bf87e73192b5f62f6da697cd091d13c6aa7a991b.yml +openapi_spec_hash: c1c561976de1abcacede71fd5ab9b3d9 +config_hash: 70e7e80b5e87f94981bee396c6cd41e8 diff --git a/CHANGELOG.md b/CHANGELOG.md index 4fa1d96..6617357 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,21 @@ # Changelog +## 2.5.0 (2026-07-22) + +Full Changelog: [v2.4.0...v2.5.0](https://github.com/context-dot-dev/context-go-sdk/compare/v2.4.0...v2.5.0) + +### Features + +* **api:** api update ([6a11143](https://github.com/context-dot-dev/context-go-sdk/commit/6a1114374f33686faefa43314e5ab5eb9910b684)) +* **api:** api update ([5f8b3b8](https://github.com/context-dot-dev/context-go-sdk/commit/5f8b3b88b5fc7303a9fd2470ef9f1722e4c83350)) +* **api:** api update ([7d5e264](https://github.com/context-dot-dev/context-go-sdk/commit/7d5e26434fa5c61c25197e247e4469fcc8e80d34)) +* **api:** api update ([9440d43](https://github.com/context-dot-dev/context-go-sdk/commit/9440d43b6b1e207d22d7bb97d2eb2306495136ee)) +* **api:** api update ([533ef0c](https://github.com/context-dot-dev/context-go-sdk/commit/533ef0c9994e843f48bc3a73e5aca2247de860b1)) +* **api:** api update ([315e065](https://github.com/context-dot-dev/context-go-sdk/commit/315e06525a23999f3f827eb370df436958ef79a5)) +* **api:** api update ([d58b30f](https://github.com/context-dot-dev/context-go-sdk/commit/d58b30faedbb676b274b8d015be903e9413963d3)) +* **api:** manual updates ([2393444](https://github.com/context-dot-dev/context-go-sdk/commit/239344498e2419e37533abde86f3bdbd71de4cd9)) +* **stlc:** configurable CI runner and private-production-repo support in workflow templates ([d1d221e](https://github.com/context-dot-dev/context-go-sdk/commit/d1d221e22674292de1ba5e39d5ec6f4adf156850)) + ## 2.4.0 (2026-07-12) Full Changelog: [v2.3.0...v2.4.0](https://github.com/context-dot-dev/context-go-sdk/compare/v2.3.0...v2.4.0) diff --git a/README.md b/README.md index 3c45934..27d1523 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Or to pin the version: ```sh -go get -u 'github.com/context-dot-dev/context-go-sdk@v2.4.0' +go get -u 'github.com/context-dot-dev/context-go-sdk@v2.5.0' ``` diff --git a/ai.go b/ai.go index b63260c..fd7bc1b 100644 --- a/ai.go +++ b/ai.go @@ -288,6 +288,8 @@ type AIExtractProductParams struct { // than this value, it will be aborted with a 408 status code. Maximum allowed // value is 300000ms (5 minutes). TimeoutMs param.Opt[int64] `json:"timeoutMS,omitzero"` + // Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + Tags []string `json:"tags,omitzero"` paramObj } @@ -334,6 +336,8 @@ type AIExtractProductsParamsBodyByDomain struct { // than this value, it will be aborted with a 408 status code. Maximum allowed // value is 300000ms (5 minutes). TimeoutMs param.Opt[int64] `json:"timeoutMS,omitzero"` + // Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + Tags []string `json:"tags,omitzero"` paramObj } @@ -360,6 +364,8 @@ type AIExtractProductsParamsBodyByDirectURL struct { // than this value, it will be aborted with a 408 status code. Maximum allowed // value is 300000ms (5 minutes). TimeoutMs param.Opt[int64] `json:"timeoutMS,omitzero"` + // Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + Tags []string `json:"tags,omitzero"` paramObj } diff --git a/ai_test.go b/ai_test.go index 81b1d67..ae34082 100644 --- a/ai_test.go +++ b/ai_test.go @@ -29,6 +29,7 @@ func TestAIExtractProductWithOptionalParams(t *testing.T) { _, err := client.AI.ExtractProduct(context.TODO(), contextdev.AIExtractProductParams{ URL: "https://example.com", MaxAgeMs: contextdev.Int(0), + Tags: []string{"production", "team-alpha"}, TimeoutMs: contextdev.Int(1000), }) if err != nil { @@ -58,6 +59,7 @@ func TestAIExtractProductsWithOptionalParams(t *testing.T) { Domain: "domain", MaxAgeMs: contextdev.Int(0), MaxProducts: contextdev.Int(1), + Tags: []string{"production", "team-alpha"}, TimeoutMs: contextdev.Int(1000), }, }) diff --git a/api.md b/api.md index e3e1ca1..a249d25 100644 --- a/api.md +++ b/api.md @@ -94,6 +94,8 @@ Response Types: - contextdev.MonitorUpdateResponse - contextdev.MonitorListResponse - contextdev.MonitorDeleteResponse +- contextdev.MonitorGetCreditUsageResponse +- contextdev.MonitorGetLimitsResponse - contextdev.MonitorListAccountChangesResponse - contextdev.MonitorListAccountRunsResponse - contextdev.MonitorListChangesResponse @@ -108,6 +110,8 @@ Methods: - client.Monitors.Update(ctx context.Context, monitorID string, body contextdev.MonitorUpdateParams) (\*contextdev.MonitorUpdateResponse, error) - client.Monitors.List(ctx context.Context, query contextdev.MonitorListParams) (\*contextdev.MonitorListResponse, error) - client.Monitors.Delete(ctx context.Context, monitorID string) (\*contextdev.MonitorDeleteResponse, error) +- client.Monitors.GetCreditUsage(ctx context.Context, query contextdev.MonitorGetCreditUsageParams) (\*contextdev.MonitorGetCreditUsageResponse, error) +- client.Monitors.GetLimits(ctx context.Context) (\*contextdev.MonitorGetLimitsResponse, error) - client.Monitors.ListAccountChanges(ctx context.Context, query contextdev.MonitorListAccountChangesParams) (\*contextdev.MonitorListAccountChangesResponse, error) - client.Monitors.ListAccountRuns(ctx context.Context, query contextdev.MonitorListAccountRunsParams) (\*contextdev.MonitorListAccountRunsResponse, error) - client.Monitors.ListChanges(ctx context.Context, monitorID string, query contextdev.MonitorListChangesParams) (\*contextdev.MonitorListChangesResponse, error) diff --git a/brand.go b/brand.go index f57c146..431d9e6 100644 --- a/brand.go +++ b/brand.go @@ -109,8 +109,7 @@ type BrandGetResponseBrand struct { Logos []BrandGetResponseBrandLogo `json:"logos"` // Company phone number Phone string `json:"phone"` - // The primary language of the brand's website content. Detected from the HTML lang - // tag, page content analysis, or social media descriptions. + // Language to force for the retrieved brand data. // // Any of "afrikaans", "albanian", "amharic", "arabic", "armenian", "assamese", // "aymara", "azeri", "basque", "belarusian", "bengali", "bosnian", "bulgarian", @@ -344,37 +343,37 @@ type BrandGetResponseBrandIndustriesEic struct { // & Infrastructure", "Subscription & Membership Commerce", "Social Commerce & // Influencer Platforms", "Fashion & Apparel Retail", "Food, Beverage & Grocery // E-commerce", "Streaming Platforms (Video, Music, Audio)", "Gaming & Interactive - // Entertainment", "Creator Economy & Influencer Platforms", "Advertising, Adtech & - // Media Buying", "Film, TV & Production Studios", "Events, Venues & Live - // Entertainment", "Virtual Worlds & Metaverse Experiences", "K-12 Education - // Platforms & Tools", "Higher Education & University Tech", "Online Learning & - // MOOCs", "Test Prep & Certification", "Corporate Training & Upskilling", - // "Tutoring & Supplemental Learning", "Education Management Systems (LMS/SIS)", - // "Language Learning", "Creator-Led & Cohort-Based Courses", "Special Education & - // Accessibility Tools", "Government Technology & Digital Services", "Civic - // Engagement & Policy Platforms", "International Development & Humanitarian Aid", - // "Philanthropy & Grantmaking", "Nonprofit Operations & Fundraising Tools", - // "Public Health & Social Services", "Education & Youth Development Programs", - // "Environmental & Climate Action Organizations", "Legal Aid & Social Justice - // Advocacy", "Municipal & Infrastructure Services", "Manufacturing & Industrial - // Automation", "Energy Production (Oil, Gas, Nuclear)", "Renewable Energy & - // Cleantech", "Utilities & Grid Infrastructure", "Industrial IoT & Monitoring - // Systems", "Construction & Heavy Equipment", "Mining & Natural Resources", - // "Environmental Engineering & Sustainability", "Energy Storage & Battery - // Technology", "Automotive OEMs & Vehicle Manufacturing", "Electric Vehicles (EVs) - // & Charging Infrastructure", "Mobility-as-a-Service (MaaS)", "Fleet Management", - // "Public Transit & Urban Mobility", "Autonomous Vehicles & ADAS", "Aftermarket - // Parts & Services", "Telematics & Vehicle Connectivity", "Aviation & Aerospace - // Transport", "Maritime Shipping", "Fitness & Wellness", "Beauty & Personal Care", - // "Home & Living", "Dating & Relationships", "Hobbies, Crafts & DIY", "Outdoor & - // Recreational Gear", "Events, Experiences & Ticketing Platforms", "Designer & - // Luxury Apparel", "Accessories, Jewelry & Watches", "Footwear & Leather Goods", - // "Beauty, Fragrance & Skincare", "Fashion Marketplaces & Retail Platforms", - // "Sustainable & Ethical Fashion", "Resale, Vintage & Circular Fashion", "Fashion - // Tech & Virtual Try-Ons", "Streetwear & Emerging Luxury", "Couture & - // Made-to-Measure", "News Publishing & Journalism", "Digital Media & Content - // Platforms", "Broadcasting (TV & Radio)", "Podcasting & Audio Media", "News - // Aggregators & Curation Tools", "Independent & Creator-Led Media", "Newsletters & + // Entertainment", "Creator Economy & Influencer Platforms", "Film, TV & Production + // Studios", "Events, Venues & Live Entertainment", "Virtual Worlds & Metaverse + // Experiences", "K-12 Education Platforms & Tools", "Higher Education & University + // Tech", "Online Learning & MOOCs", "Test Prep & Certification", "Corporate + // Training & Upskilling", "Tutoring & Supplemental Learning", "Education + // Management Systems (LMS/SIS)", "Language Learning", "Creator-Led & Cohort-Based + // Courses", "Special Education & Accessibility Tools", "Government Technology & + // Digital Services", "Civic Engagement & Policy Platforms", "International + // Development & Humanitarian Aid", "Philanthropy & Grantmaking", "Nonprofit + // Operations & Fundraising Tools", "Public Health & Social Services", "Education & + // Youth Development Programs", "Environmental & Climate Action Organizations", + // "Legal Aid & Social Justice Advocacy", "Municipal & Infrastructure Services", + // "Manufacturing & Industrial Automation", "Energy Production (Oil, Gas, + // Nuclear)", "Renewable Energy & Cleantech", "Utilities & Grid Infrastructure", + // "Industrial IoT & Monitoring Systems", "Construction & Heavy Equipment", "Mining + // & Natural Resources", "Environmental Engineering & Sustainability", "Energy + // Storage & Battery Technology", "Automotive OEMs & Vehicle Manufacturing", + // "Electric Vehicles (EVs) & Charging Infrastructure", "Mobility-as-a-Service + // (MaaS)", "Fleet Management", "Public Transit & Urban Mobility", "Autonomous + // Vehicles & ADAS", "Aftermarket Parts & Services", "Telematics & Vehicle + // Connectivity", "Aviation & Aerospace Transport", "Maritime Shipping", "Fitness & + // Wellness", "Beauty & Personal Care", "Home & Living", "Dating & Relationships", + // "Hobbies, Crafts & DIY", "Outdoor & Recreational Gear", "Events, Experiences & + // Ticketing Platforms", "Designer & Luxury Apparel", "Accessories, Jewelry & + // Watches", "Footwear & Leather Goods", "Beauty, Fragrance & Skincare", "Fashion + // Marketplaces & Retail Platforms", "Sustainable & Ethical Fashion", "Resale, + // Vintage & Circular Fashion", "Fashion Tech & Virtual Try-Ons", "Streetwear & + // Emerging Luxury", "Couture & Made-to-Measure", "News Publishing & Journalism", + // "Advertising, Adtech & Media Buying", "Digital Media & Content Platforms", + // "Broadcasting (TV & Radio)", "Podcasting & Audio Media", "News Aggregators & + // Curation Tools", "Independent & Creator-Led Media", "Newsletters & // Substack-Style Platforms", "Political & Investigative Media", "Trade & Niche // Publications", "Media Monitoring & Analytics", "Professional Teams & Leagues", // "Sports Media & Broadcasting", "Sports Betting & Fantasy Sports", "Fitness & @@ -949,6 +948,8 @@ type BrandGetParamsBodyByDomain struct { // "uyghur", "uzbek", "vietnamese", "welsh", "wolof", "xhosa", "yiddish", "yoruba", // "zulu". ForceLanguage string `json:"force_language,omitzero"` + // Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + Tags []string `json:"tags,omitzero"` // Discriminator for domain-based brand retrieval. // // This field can be elided, and will marshal its zero value as "by_domain". @@ -1012,6 +1013,8 @@ type BrandGetParamsBodyByName struct { // "uyghur", "uzbek", "vietnamese", "welsh", "wolof", "xhosa", "yiddish", "yoruba", // "zulu". ForceLanguage string `json:"force_language,omitzero"` + // Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + Tags []string `json:"tags,omitzero"` // Discriminator for name-based brand retrieval. // // This field can be elided, and will marshal its zero value as "by_name". @@ -1073,6 +1076,8 @@ type BrandGetParamsBodyByEmail struct { // "uyghur", "uzbek", "vietnamese", "welsh", "wolof", "xhosa", "yiddish", "yoruba", // "zulu". ForceLanguage string `json:"force_language,omitzero"` + // Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + Tags []string `json:"tags,omitzero"` // Discriminator for email-based brand retrieval. // // This field can be elided, and will marshal its zero value as "by_email". @@ -1135,6 +1140,8 @@ type BrandGetParamsBodyByTicker struct { // "uyghur", "uzbek", "vietnamese", "welsh", "wolof", "xhosa", "yiddish", "yoruba", // "zulu". ForceLanguage string `json:"force_language,omitzero"` + // Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + Tags []string `json:"tags,omitzero"` // Discriminator for ticker-based brand retrieval. // // This field can be elided, and will marshal its zero value as "by_ticker". @@ -1172,6 +1179,8 @@ type BrandGetParamsBodyByDirectURL struct { // than this value, it will be aborted with a 408 status code. Maximum allowed // value is 300000ms (5 minutes). TimeoutMs param.Opt[int64] `json:"timeoutMS,omitzero"` + // Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + Tags []string `json:"tags,omitzero"` // Discriminator for direct-URL-based brand retrieval. // // This field can be elided, and will marshal its zero value as "by_direct_url". @@ -1206,11 +1215,6 @@ type BrandGetParamsBodyByTransaction struct { // the API will skip time-consuming operations for faster response at the cost of // less comprehensive data. MaxSpeed param.Opt[bool] `json:"maxSpeed,omitzero"` - // Optional Merchant Category Code (MCC) to help identify the business category or - // industry. - Mcc param.Opt[int64] `json:"mcc,omitzero"` - // Optional phone number from the transaction to help verify brand match. - Phone param.Opt[float64] `json:"phone,omitzero"` // 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). @@ -1234,6 +1238,13 @@ type BrandGetParamsBodyByTransaction struct { // "uyghur", "uzbek", "vietnamese", "welsh", "wolof", "xhosa", "yiddish", "yoruba", // "zulu". ForceLanguage string `json:"force_language,omitzero"` + // Optional Merchant Category Code (MCC) to help identify the business category or + // industry. + Mcc BrandGetParamsBodyByTransactionMccUnion `json:"mcc,omitzero"` + // Optional phone number from the transaction to help verify brand match. + Phone BrandGetParamsBodyByTransactionPhoneUnion `json:"phone,omitzero"` + // Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + Tags []string `json:"tags,omitzero"` // Discriminator for transaction-based brand retrieval. // // This field can be elided, and will marshal its zero value as "by_transaction". @@ -1255,6 +1266,38 @@ func init() { ) } +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type BrandGetParamsBodyByTransactionMccUnion struct { + OfString param.Opt[string] `json:",omitzero,inline"` + OfFloat param.Opt[float64] `json:",omitzero,inline"` + paramUnion +} + +func (u BrandGetParamsBodyByTransactionMccUnion) MarshalJSON() ([]byte, error) { + return param.MarshalUnion(u, u.OfString, u.OfFloat) +} +func (u *BrandGetParamsBodyByTransactionMccUnion) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, u) +} + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type BrandGetParamsBodyByTransactionPhoneUnion struct { + OfString param.Opt[string] `json:",omitzero,inline"` + OfFloat param.Opt[float64] `json:",omitzero,inline"` + paramUnion +} + +func (u BrandGetParamsBodyByTransactionPhoneUnion) MarshalJSON() ([]byte, error) { + return param.MarshalUnion(u, u.OfString, u.OfFloat) +} +func (u *BrandGetParamsBodyByTransactionPhoneUnion) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, u) +} + type BrandGetSimplifiedParams struct { // Domain name to retrieve simplified brand data for Domain string `query:"domain" api:"required" json:"-"` @@ -1267,6 +1310,14 @@ type BrandGetSimplifiedParams struct { // than this value, it will be aborted with a 408 status code. Maximum allowed // value is 300000ms (5 minutes). TimeoutMs param.Opt[int64] `query:"timeoutMS,omitzero" json:"-"` + // 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 []string `query:"tags,omitzero" json:"-"` + // Optional theme preference used when selecting brand assets. + // + // Any of "light", "dark". + Theme BrandGetSimplifiedParamsTheme `query:"theme,omitzero" json:"-"` paramObj } @@ -1278,3 +1329,11 @@ func (r BrandGetSimplifiedParams) URLQuery() (v url.Values, err error) { NestedFormat: apiquery.NestedQueryFormatBrackets, }) } + +// Optional theme preference used when selecting brand assets. +type BrandGetSimplifiedParamsTheme string + +const ( + BrandGetSimplifiedParamsThemeLight BrandGetSimplifiedParamsTheme = "light" + BrandGetSimplifiedParamsThemeDark BrandGetSimplifiedParamsTheme = "dark" +) diff --git a/brand_test.go b/brand_test.go index c371726..591643e 100644 --- a/brand_test.go +++ b/brand_test.go @@ -32,6 +32,7 @@ func TestBrandGetWithOptionalParams(t *testing.T) { ForceLanguage: "afrikaans", MaxAgeMs: contextdev.Int(0), MaxSpeed: contextdev.Bool(true), + Tags: []string{"production", "team-alpha"}, TimeoutMs: contextdev.Int(1000), }, }) @@ -58,8 +59,10 @@ func TestBrandGetSimplifiedWithOptionalParams(t *testing.T) { option.WithAPIKey("My API Key"), ) _, err := client.Brand.GetSimplified(context.TODO(), contextdev.BrandGetSimplifiedParams{ - Domain: "domain", - MaxAgeMs: contextdev.Int(86400000), + Domain: "xxx", + MaxAgeMs: contextdev.Int(0), + Tags: []string{"production", "team-alpha"}, + Theme: contextdev.BrandGetSimplifiedParamsThemeLight, TimeoutMs: contextdev.Int(1000), }) if err != nil { diff --git a/industry.go b/industry.go index 2c4100c..dd012f0 100644 --- a/industry.go +++ b/industry.go @@ -248,6 +248,10 @@ type IndustryGetNaicsParams struct { // than this value, it will be aborted with a 408 status code. Maximum allowed // value is 300000ms (5 minutes). TimeoutMs param.Opt[int64] `query:"timeoutMS,omitzero" json:"-"` + // 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 []string `query:"tags,omitzero" json:"-"` paramObj } @@ -272,6 +276,10 @@ type IndustryGetSicParams struct { // than this value, it will be aborted with a 408 status code. Maximum allowed // value is 300000ms (5 minutes). TimeoutMs param.Opt[int64] `query:"timeoutMS,omitzero" json:"-"` + // 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 []string `query:"tags,omitzero" json:"-"` // 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`. diff --git a/industry_test.go b/industry_test.go index 129da80..6d326bc 100644 --- a/industry_test.go +++ b/industry_test.go @@ -27,9 +27,10 @@ func TestIndustryGetNaicsWithOptionalParams(t *testing.T) { option.WithAPIKey("My API Key"), ) _, err := client.Industry.GetNaics(context.TODO(), contextdev.IndustryGetNaicsParams{ - Input: "input", + Input: "xxxx", MaxResults: contextdev.Int(1), MinResults: contextdev.Int(1), + Tags: []string{"production", "team-alpha"}, TimeoutMs: contextdev.Int(1000), }) if err != nil { @@ -55,9 +56,10 @@ func TestIndustryGetSicWithOptionalParams(t *testing.T) { option.WithAPIKey("My API Key"), ) _, err := client.Industry.GetSic(context.TODO(), contextdev.IndustryGetSicParams{ - Input: "input", + Input: "xxxx", MaxResults: contextdev.Int(1), MinResults: contextdev.Int(1), + Tags: []string{"production", "team-alpha"}, TimeoutMs: contextdev.Int(1000), Type: contextdev.IndustryGetSicParamsTypeOriginalSic, }) diff --git a/internal/version.go b/internal/version.go index eaba12d..0d6e599 100644 --- a/internal/version.go +++ b/internal/version.go @@ -2,4 +2,4 @@ package internal -const PackageVersion = "2.4.0" // x-release-please-version +const PackageVersion = "2.5.0" // x-release-please-version diff --git a/monitor.go b/monitor.go index 2a06cee..30e4f69 100644 --- a/monitor.go +++ b/monitor.go @@ -103,6 +103,23 @@ func (r *MonitorService) Delete(ctx context.Context, monitorID string, opts ...o return res, err } +// Returns credits charged per monitor over an optional [since, until] window, +// newest spenders first. +func (r *MonitorService) GetCreditUsage(ctx context.Context, query MonitorGetCreditUsageParams, opts ...option.RequestOption) (res *MonitorGetCreditUsageResponse, err error) { + opts = slices.Concat(r.options, opts) + path := "monitors/credit-usage" + err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, query, &res, opts...) + return res, err +} + +// Returns how many monitors the account has and the maximum it allows. +func (r *MonitorService) GetLimits(ctx context.Context, opts ...option.RequestOption) (res *MonitorGetLimitsResponse, err error) { + opts = slices.Concat(r.options, opts) + path := "monitors/limits" + err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, nil, &res, opts...) + return res, err +} + // Returns an account-wide feed of detected changes across monitors. func (r *MonitorService) ListAccountChanges(ctx context.Context, query MonitorListAccountChangesParams, opts ...option.RequestOption) (res *MonitorListAccountChangesResponse, err error) { opts = slices.Concat(r.options, opts) @@ -285,6 +302,7 @@ type MonitorNewResponse struct { // When the next scheduled run is due. NextRunAt time.Time `json:"next_run_at" api:"nullable" format:"date-time"` // User-defined tags for grouping and filtering monitors and their changes. + // Duplicates are removed. Tags []string `json:"tags"` Webhook MonitorNewResponseWebhook `json:"webhook" api:"nullable"` // Present while webhook deliveries are failing consecutively; null when deliveries @@ -604,9 +622,9 @@ type MonitorNewResponseTargetSitemap struct { Type constant.Sitemap `json:"type" default:"sitemap"` // Sitemap URL to monitor. URL string `json:"url" api:"required" format:"uri"` - // URL path patterns to exclude. + // URL path patterns to exclude (max 50). Exclude []string `json:"exclude"` - // URL path patterns to include. + // URL path patterns to include (max 50). Include []string `json:"include"` // Maximum number of sitemap URLs to track (capped at 10,000). MaxURLs int64 `json:"max_urls"` @@ -922,6 +940,7 @@ type MonitorGetResponse struct { // When the next scheduled run is due. NextRunAt time.Time `json:"next_run_at" api:"nullable" format:"date-time"` // User-defined tags for grouping and filtering monitors and their changes. + // Duplicates are removed. Tags []string `json:"tags"` Webhook MonitorGetResponseWebhook `json:"webhook" api:"nullable"` // Present while webhook deliveries are failing consecutively; null when deliveries @@ -1241,9 +1260,9 @@ type MonitorGetResponseTargetSitemap struct { Type constant.Sitemap `json:"type" default:"sitemap"` // Sitemap URL to monitor. URL string `json:"url" api:"required" format:"uri"` - // URL path patterns to exclude. + // URL path patterns to exclude (max 50). Exclude []string `json:"exclude"` - // URL path patterns to include. + // URL path patterns to include (max 50). Include []string `json:"include"` // Maximum number of sitemap URLs to track (capped at 10,000). MaxURLs int64 `json:"max_urls"` @@ -1559,6 +1578,7 @@ type MonitorUpdateResponse struct { // When the next scheduled run is due. NextRunAt time.Time `json:"next_run_at" api:"nullable" format:"date-time"` // User-defined tags for grouping and filtering monitors and their changes. + // Duplicates are removed. Tags []string `json:"tags"` Webhook MonitorUpdateResponseWebhook `json:"webhook" api:"nullable"` // Present while webhook deliveries are failing consecutively; null when deliveries @@ -1879,9 +1899,9 @@ type MonitorUpdateResponseTargetSitemap struct { Type constant.Sitemap `json:"type" default:"sitemap"` // Sitemap URL to monitor. URL string `json:"url" api:"required" format:"uri"` - // URL path patterns to exclude. + // URL path patterns to exclude (max 50). Exclude []string `json:"exclude"` - // URL path patterns to include. + // URL path patterns to include (max 50). Include []string `json:"include"` // Maximum number of sitemap URLs to track (capped at 10,000). MaxURLs int64 `json:"max_urls"` @@ -2217,6 +2237,7 @@ type MonitorListResponseData struct { // When the next scheduled run is due. NextRunAt time.Time `json:"next_run_at" api:"nullable" format:"date-time"` // User-defined tags for grouping and filtering monitors and their changes. + // Duplicates are removed. Tags []string `json:"tags"` Webhook MonitorListResponseDataWebhook `json:"webhook" api:"nullable"` // Present while webhook deliveries are failing consecutively; null when deliveries @@ -2518,9 +2539,9 @@ type MonitorListResponseDataTargetSitemap struct { Type constant.Sitemap `json:"type" default:"sitemap"` // Sitemap URL to monitor. URL string `json:"url" api:"required" format:"uri"` - // URL path patterns to exclude. + // URL path patterns to exclude (max 50). Exclude []string `json:"exclude"` - // URL path patterns to include. + // URL path patterns to include (max 50). Include []string `json:"include"` // Maximum number of sitemap URLs to track (capped at 10,000). MaxURLs int64 `json:"max_urls"` @@ -2814,6 +2835,86 @@ func (r *MonitorDeleteResponse) UnmarshalJSON(data []byte) error { return apijson.UnmarshalRoot(data, r) } +type MonitorGetCreditUsageResponse struct { + Data []MonitorGetCreditUsageResponseData `json:"data" api:"required"` + // Sum of credits across all monitors in the window. + TotalCredits int64 `json:"total_credits" api:"required"` + // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. + JSON struct { + Data respjson.Field + TotalCredits respjson.Field + ExtraFields map[string]respjson.Field + raw string + } `json:"-"` +} + +// Returns the unmodified JSON received from the API +func (r MonitorGetCreditUsageResponse) RawJSON() string { return r.JSON.raw } +func (r *MonitorGetCreditUsageResponse) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} + +type MonitorGetCreditUsageResponseData struct { + // Credits charged to this monitor over the window. + Credits int64 `json:"credits" api:"required"` + MonitorID string `json:"monitor_id" api:"required"` + // Monitor name (falls back to the id when the monitor was deleted). + Name string `json:"name" api:"required"` + // Number of billed runs over the window. + Runs int64 `json:"runs" api:"required"` + // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. + JSON struct { + Credits respjson.Field + MonitorID respjson.Field + Name respjson.Field + Runs respjson.Field + ExtraFields map[string]respjson.Field + raw string + } `json:"-"` +} + +// Returns the unmodified JSON received from the API +func (r MonitorGetCreditUsageResponseData) RawJSON() string { return r.JSON.raw } +func (r *MonitorGetCreditUsageResponseData) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} + +type MonitorGetLimitsResponse struct { + // Maximum number of monitors allowed for the account. Defaults to the plan + // allowance unless a custom limit is set for the organization. + MonitorsLimit int64 `json:"monitors_limit" api:"required"` + // Number of monitors the account currently has. + MonitorsUsed int64 `json:"monitors_used" api:"required"` + // The plan tier the limit was resolved from. + // + // Any of "free", "starter", "pro", "scale". + Plan MonitorGetLimitsResponsePlan `json:"plan" api:"required"` + // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. + JSON struct { + MonitorsLimit respjson.Field + MonitorsUsed respjson.Field + Plan respjson.Field + ExtraFields map[string]respjson.Field + raw string + } `json:"-"` +} + +// Returns the unmodified JSON received from the API +func (r MonitorGetLimitsResponse) RawJSON() string { return r.JSON.raw } +func (r *MonitorGetLimitsResponse) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} + +// The plan tier the limit was resolved from. +type MonitorGetLimitsResponsePlan string + +const ( + MonitorGetLimitsResponsePlanFree MonitorGetLimitsResponsePlan = "free" + MonitorGetLimitsResponsePlanStarter MonitorGetLimitsResponsePlan = "starter" + MonitorGetLimitsResponsePlanPro MonitorGetLimitsResponsePlan = "pro" + MonitorGetLimitsResponsePlanScale MonitorGetLimitsResponsePlan = "scale" +) + type MonitorListAccountChangesResponse struct { Data []MonitorListAccountChangesResponseData `json:"data" api:"required"` HasMore bool `json:"has_more" api:"required"` @@ -2862,6 +2963,7 @@ type MonitorListAccountChangesResponseData struct { MatchedURLCount int64 `json:"matched_url_count"` RemovedURLCount int64 `json:"removed_url_count"` // User-defined tags for grouping and filtering monitors and their changes. + // Duplicates are removed. Tags []string `json:"tags"` // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. JSON struct { @@ -3046,6 +3148,7 @@ type MonitorListChangesResponseData struct { MatchedURLCount int64 `json:"matched_url_count"` RemovedURLCount int64 `json:"removed_url_count"` // User-defined tags for grouping and filtering monitors and their changes. + // Duplicates are removed. Tags []string `json:"tags"` // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. JSON struct { @@ -3202,6 +3305,7 @@ type MonitorGetChangeResponse struct { RunID string `json:"run_id" api:"required"` Summary string `json:"summary" api:"required"` // User-defined tags for grouping and filtering monitors and their changes. + // Duplicates are removed. Tags []string `json:"tags" api:"required"` // Any of "page", "sitemap", "extract". TargetType MonitorGetChangeResponseTargetType `json:"target_type" api:"required"` @@ -3353,6 +3457,7 @@ type MonitorNewParams struct { // Any of "web". Mode MonitorNewParamsMode `json:"mode,omitzero"` // User-defined tags for grouping and filtering monitors and their changes. + // Duplicates are removed. Tags []string `json:"tags,omitzero"` paramObj } @@ -3525,9 +3630,9 @@ type MonitorNewParamsTargetSitemap struct { URL string `json:"url" api:"required" format:"uri"` // Maximum number of sitemap URLs to track (capped at 10,000). MaxURLs param.Opt[int64] `json:"max_urls,omitzero"` - // URL path patterns to exclude. + // URL path patterns to exclude (max 50). Exclude []string `json:"exclude,omitzero"` - // URL path patterns to include. + // URL path patterns to include (max 50). Include []string `json:"include,omitzero"` // This field can be elided, and will marshal its zero value as "sitemap". Type constant.Sitemap `json:"type" default:"sitemap"` @@ -3625,6 +3730,7 @@ type MonitorUpdateParams struct { // Any of "active", "paused". Status MonitorUpdateParamsStatus `json:"status,omitzero"` // User-defined tags for grouping and filtering monitors and their changes. + // Duplicates are removed. Tags []string `json:"tags,omitzero"` // Discriminated union describing what the monitor watches. Target MonitorUpdateParamsTargetUnion `json:"target,omitzero"` @@ -3806,9 +3912,9 @@ type MonitorUpdateParamsTargetSitemap struct { URL string `json:"url" api:"required" format:"uri"` // Maximum number of sitemap URLs to track (capped at 10,000). MaxURLs param.Opt[int64] `json:"max_urls,omitzero"` - // URL path patterns to exclude. + // URL path patterns to exclude (max 50). Exclude []string `json:"exclude,omitzero"` - // URL path patterns to include. + // URL path patterns to include (max 50). Include []string `json:"include,omitzero"` // This field can be elided, and will marshal its zero value as "sitemap". Type constant.Sitemap `json:"type" default:"sitemap"` @@ -3888,34 +3994,36 @@ func (r *MonitorUpdateParamsWebhook) UnmarshalJSON(data []byte) error { } type MonitorListParams struct { + // Opaque pagination cursor from a previous response. Cursor param.Opt[string] `query:"cursor,omitzero" json:"-"` - Limit param.Opt[int64] `query:"limit,omitzero" json:"-"` + // Maximum number of items to return per page (1-100). Defaults to 25. + Limit param.Opt[int64] `query:"limit,omitzero" json:"-"` // Free-text search term, matched against the fields named in `search_by`. Q param.Opt[string] `query:"q,omitzero" json:"-"` // Filter to items that have this tag. Tag param.Opt[string] `query:"tag,omitzero" json:"-"` - // Any of "exact", "semantic". - ChangeDetectionType MonitorListParamsChangeDetectionType `query:"change_detection_type,omitzero" json:"-"` // Comma-separated fields to search with `q`. Defaults to all of them. Note // `instructions` only exists on extract monitors. // // Any of "name", "url", "instructions", "tags". SearchBy []string `query:"search_by,omitzero" json:"-"` + // Comma-separated list of tags to filter by (matches monitors having any of them). + Tags []string `query:"tags,omitzero" json:"-"` + // Filter by change detection type. + // + // Any of "exact", "semantic". + ChangeDetectionType MonitorListParamsChangeDetectionType `query:"change_detection_type,omitzero" json:"-"` // `prefix` for as-you-type prefix matching (default), `exact` for full-token // matching. // // Any of "exact", "prefix". SearchType MonitorListParamsSearchType `query:"search_type,omitzero" json:"-"` - // 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`. + // Filter monitors by lifecycle status. // // Any of "active", "paused", "failed". Status MonitorListParamsStatus `query:"status,omitzero" json:"-"` - // Comma-separated list of tags to filter by (matches monitors having any of them). - Tags []string `query:"tags,omitzero" json:"-"` + // Filter by target type. + // // Any of "page", "sitemap", "extract". TargetType MonitorListParamsTargetType `query:"target_type,omitzero" json:"-"` paramObj @@ -3929,6 +4037,7 @@ func (r MonitorListParams) URLQuery() (v url.Values, err error) { }) } +// Filter by change detection type. type MonitorListParamsChangeDetectionType string const ( @@ -3945,11 +4054,7 @@ const ( MonitorListParamsSearchTypePrefix MonitorListParamsSearchType = "prefix" ) -// 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`. +// Filter monitors by lifecycle status. type MonitorListParamsStatus string const ( @@ -3958,6 +4063,7 @@ const ( MonitorListParamsStatusFailed MonitorListParamsStatus = "failed" ) +// Filter by target type. type MonitorListParamsTargetType string const ( @@ -3966,16 +4072,42 @@ const ( MonitorListParamsTargetTypeExtract MonitorListParamsTargetType = "extract" ) +type MonitorGetCreditUsageParams struct { + // Only include items at or after this ISO 8601 timestamp. + Since param.Opt[time.Time] `query:"since,omitzero" format:"date-time" json:"-"` + // Only include items before this ISO 8601 timestamp. + Until param.Opt[time.Time] `query:"until,omitzero" format:"date-time" json:"-"` + paramObj +} + +// URLQuery serializes [MonitorGetCreditUsageParams]'s query parameters as +// `url.Values`. +func (r MonitorGetCreditUsageParams) URLQuery() (v url.Values, err error) { + return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{ + ArrayFormat: apiquery.ArrayQueryFormatComma, + NestedFormat: apiquery.NestedQueryFormatBrackets, + }) +} + type MonitorListAccountChangesParams struct { - Cursor param.Opt[string] `query:"cursor,omitzero" json:"-"` - Limit param.Opt[int64] `query:"limit,omitzero" json:"-"` - MonitorID param.Opt[string] `query:"monitor_id,omitzero" json:"-"` - Since param.Opt[time.Time] `query:"since,omitzero" format:"date-time" json:"-"` + // Opaque pagination cursor from a previous response. + Cursor param.Opt[string] `query:"cursor,omitzero" json:"-"` + // Maximum number of items to return per page (1-100). Defaults to 25. + Limit param.Opt[int64] `query:"limit,omitzero" json:"-"` + // Filter changes to a single monitor. + MonitorID param.Opt[string] `query:"monitor_id,omitzero" json:"-"` + // Only include items at or after this ISO 8601 timestamp. + Since param.Opt[time.Time] `query:"since,omitzero" format:"date-time" json:"-"` // Filter to items that have this tag. - Tag param.Opt[string] `query:"tag,omitzero" json:"-"` + Tag param.Opt[string] `query:"tag,omitzero" json:"-"` + // Only include items before this ISO 8601 timestamp. Until param.Opt[time.Time] `query:"until,omitzero" format:"date-time" json:"-"` + // Filter by change detection type. + // // Any of "exact", "semantic". ChangeDetectionType MonitorListAccountChangesParamsChangeDetectionType `query:"change_detection_type,omitzero" json:"-"` + // Filter by target type. + // // Any of "page", "sitemap", "extract". TargetType MonitorListAccountChangesParamsTargetType `query:"target_type,omitzero" json:"-"` paramObj @@ -3990,6 +4122,7 @@ func (r MonitorListAccountChangesParams) URLQuery() (v url.Values, err error) { }) } +// Filter by change detection type. type MonitorListAccountChangesParamsChangeDetectionType string const ( @@ -3997,6 +4130,7 @@ const ( MonitorListAccountChangesParamsChangeDetectionTypeSemantic MonitorListAccountChangesParamsChangeDetectionType = "semantic" ) +// Filter by target type. type MonitorListAccountChangesParamsTargetType string const ( @@ -4006,10 +4140,11 @@ const ( ) type MonitorListAccountRunsParams struct { + // Opaque pagination cursor from a previous response. Cursor param.Opt[string] `query:"cursor,omitzero" json:"-"` - Limit param.Opt[int64] `query:"limit,omitzero" json:"-"` - // Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` - // (insufficient credits, monitor paused, or superseded by a concurrent run). + // Maximum number of items to return per page (1-100). Defaults to 25. + Limit param.Opt[int64] `query:"limit,omitzero" json:"-"` + // Filter runs by lifecycle status. // // Any of "queued", "running", "completed", "failed", "skipped". Status MonitorListAccountRunsParamsStatus `query:"status,omitzero" json:"-"` @@ -4025,8 +4160,7 @@ func (r MonitorListAccountRunsParams) URLQuery() (v url.Values, err error) { }) } -// Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` -// (insufficient credits, monitor paused, or superseded by a concurrent run). +// Filter runs by lifecycle status. type MonitorListAccountRunsParamsStatus string const ( @@ -4038,11 +4172,15 @@ const ( ) type MonitorListChangesParams struct { - Cursor param.Opt[string] `query:"cursor,omitzero" json:"-"` - Limit param.Opt[int64] `query:"limit,omitzero" json:"-"` - Since param.Opt[time.Time] `query:"since,omitzero" format:"date-time" json:"-"` + // Opaque pagination cursor from a previous response. + Cursor param.Opt[string] `query:"cursor,omitzero" json:"-"` + // Maximum number of items to return per page (1-100). Defaults to 25. + Limit param.Opt[int64] `query:"limit,omitzero" json:"-"` + // Only include items at or after this ISO 8601 timestamp. + Since param.Opt[time.Time] `query:"since,omitzero" format:"date-time" json:"-"` // Filter to items that have this tag. - Tag param.Opt[string] `query:"tag,omitzero" json:"-"` + Tag param.Opt[string] `query:"tag,omitzero" json:"-"` + // Only include items before this ISO 8601 timestamp. Until param.Opt[time.Time] `query:"until,omitzero" format:"date-time" json:"-"` paramObj } @@ -4057,10 +4195,11 @@ func (r MonitorListChangesParams) URLQuery() (v url.Values, err error) { } type MonitorListRunsParams struct { + // Opaque pagination cursor from a previous response. Cursor param.Opt[string] `query:"cursor,omitzero" json:"-"` - Limit param.Opt[int64] `query:"limit,omitzero" json:"-"` - // Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` - // (insufficient credits, monitor paused, or superseded by a concurrent run). + // Maximum number of items to return per page (1-100). Defaults to 25. + Limit param.Opt[int64] `query:"limit,omitzero" json:"-"` + // Filter runs by lifecycle status. // // Any of "queued", "running", "completed", "failed", "skipped". Status MonitorListRunsParamsStatus `query:"status,omitzero" json:"-"` @@ -4075,8 +4214,7 @@ func (r MonitorListRunsParams) URLQuery() (v url.Values, err error) { }) } -// Lifecycle status of a run. `skipped` runs never executed — see `skip_reason` -// (insufficient credits, monitor paused, or superseded by a concurrent run). +// Filter runs by lifecycle status. type MonitorListRunsParamsStatus string const ( diff --git a/monitor_test.go b/monitor_test.go index d6689a9..a3815bb 100644 --- a/monitor_test.go +++ b/monitor_test.go @@ -148,12 +148,12 @@ func TestMonitorListWithOptionalParams(t *testing.T) { ChangeDetectionType: contextdev.MonitorListParamsChangeDetectionTypeExact, Cursor: contextdev.String("cursor"), Limit: contextdev.Int(1), - Q: contextdev.String("q"), + Q: contextdev.String("pricing"), SearchBy: []string{"name"}, SearchType: contextdev.MonitorListParamsSearchTypeExact, Status: contextdev.MonitorListParamsStatusActive, - Tag: contextdev.String("tag"), - Tags: []string{"string"}, + Tag: contextdev.String("pricing"), + Tags: []string{"x"}, TargetType: contextdev.MonitorListParamsTargetTypePage, }) if err != nil { @@ -188,6 +188,55 @@ func TestMonitorDelete(t *testing.T) { } } +func TestMonitorGetCreditUsageWithOptionalParams(t *testing.T) { + t.Skip("Mock server tests are disabled") + baseURL := "http://localhost:4010" + if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok { + baseURL = envURL + } + if !testutil.CheckTestServer(t, baseURL) { + return + } + client := contextdev.NewClient( + option.WithBaseURL(baseURL), + option.WithAPIKey("My API Key"), + ) + _, err := client.Monitors.GetCreditUsage(context.TODO(), contextdev.MonitorGetCreditUsageParams{ + Since: contextdev.Time(time.Now()), + Until: contextdev.Time(time.Now()), + }) + if err != nil { + var apierr *contextdev.Error + if errors.As(err, &apierr) { + t.Log(string(apierr.DumpRequest(true))) + } + t.Fatalf("err should be nil: %s", err.Error()) + } +} + +func TestMonitorGetLimits(t *testing.T) { + t.Skip("Mock server tests are disabled") + baseURL := "http://localhost:4010" + if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok { + baseURL = envURL + } + if !testutil.CheckTestServer(t, baseURL) { + return + } + client := contextdev.NewClient( + option.WithBaseURL(baseURL), + option.WithAPIKey("My API Key"), + ) + _, err := client.Monitors.GetLimits(context.TODO()) + if err != nil { + var apierr *contextdev.Error + if errors.As(err, &apierr) { + t.Log(string(apierr.DumpRequest(true))) + } + t.Fatalf("err should be nil: %s", err.Error()) + } +} + func TestMonitorListAccountChangesWithOptionalParams(t *testing.T) { t.Skip("Mock server tests are disabled") baseURL := "http://localhost:4010" @@ -205,9 +254,9 @@ func TestMonitorListAccountChangesWithOptionalParams(t *testing.T) { ChangeDetectionType: contextdev.MonitorListAccountChangesParamsChangeDetectionTypeExact, Cursor: contextdev.String("cursor"), Limit: contextdev.Int(1), - MonitorID: contextdev.String("monitor_id"), + MonitorID: contextdev.String("mon_123"), Since: contextdev.Time(time.Now()), - Tag: contextdev.String("tag"), + Tag: contextdev.String("pricing"), TargetType: contextdev.MonitorListAccountChangesParamsTargetTypePage, Until: contextdev.Time(time.Now()), }) @@ -267,7 +316,7 @@ func TestMonitorListChangesWithOptionalParams(t *testing.T) { Cursor: contextdev.String("cursor"), Limit: contextdev.Int(1), Since: contextdev.Time(time.Now()), - Tag: contextdev.String("tag"), + Tag: contextdev.String("pricing"), Until: contextdev.Time(time.Now()), }, ) diff --git a/parse.go b/parse.go index 69c162d..8fc2cbc 100644 --- a/parse.go +++ b/parse.go @@ -40,9 +40,7 @@ func NewParseService(opts ...option.RequestOption) (r ParseService) { } // Converts raw text, source code, web/data, PDF, Microsoft Office, and image bytes -// into LLM-usable Markdown. The base request costs 1 credit. When OCR runs -// (requires ocr=true), the entire call costs 5 credits; ocr=true requests where no -// OCR ends up running still cost 1 credit. +// into LLM-usable Markdown. func (r *ParseService) Handle(ctx context.Context, body io.Reader, params ParseHandleParams, opts ...option.RequestOption) (res *ParseHandleResponse, err error) { opts = slices.Concat(r.options, opts) opts = append([]option.RequestOption{option.WithRequestBody("application/octet-stream", body)}, opts...) @@ -156,24 +154,10 @@ func (r *ParseHandleResponseKeyMetadata) UnmarshalJSON(data []byte) error { } type ParseHandleParams struct { - // Include image references in Markdown output - IncludeImages param.Opt[bool] `query:"includeImages,omitzero" json:"-"` - // Preserve hyperlinks in Markdown output - IncludeLinks param.Opt[bool] `query:"includeLinks,omitzero" json:"-"` - // Gates all OCR. When true, PDFs get embedded-image OCR (recognized text inserted - // at each image's position in page reading order, preserving the text layer; - // pdf.start/pdf.end limit the page range), scanned PDFs with no text layer get - // full-document OCR, and raster images get their visible text transcribed. When - // false, no OCR runs: scanned PDFs may yield no content and images return only - // format/dimension metadata. Calls where OCR actually runs cost 5 credits instead - // of 1. - Ocr param.Opt[bool] `query:"ocr,omitzero" json:"-"` - // Shorten base64-encoded image data in the Markdown output - ShortenBase64Images param.Opt[bool] `query:"shortenBase64Images,omitzero" json:"-"` - // Extract only the main content from HTML-like inputs - UseMainContentOnly param.Opt[bool] `query:"useMainContentOnly,omitzero" json:"-"` - // Optional file extension hint. Case-insensitive; a leading dot is accepted (e.g. - // ".pdf"). + // Optional client identifier used for usage attribution. + Client param.Opt[string] `query:"client,omitzero" json:"-"` + // Optional file extension hint, such as pdf, docx, xlsx, pptx, html, json, csv, + // md, py, rtf, jpg, png, or txt. // // Any of "txt", "text", "md", "markdown", "html", "htm", "xhtml", "xml", "rss", // "atom", "csv", "tsv", "yaml", "yml", "py", "java", "js", "jsx", "mjs", "cjs", @@ -183,9 +167,32 @@ type ParseHandleParams struct { // "ppsx", "ppsm", "potx", "potm", "ppt", "pps", "pot", "jpg", "jpeg", "jpe", // "png", "gif", "bmp", "tiff", "tif", "webp", "ppm", "pbm", "pgm", "pnm". Extension ParseHandleParamsExtension `query:"extension,omitzero" json:"-"` - // PDF page-range controls. Use start/end to limit parsing (and OCR when ocr=true) - // to an inclusive 1-based page range. + // Include image references in Markdown output + IncludeImages ParseHandleParamsIncludeImagesUnion `query:"includeImages,omitzero" json:"-"` + // Preserve hyperlinks in Markdown output + IncludeLinks ParseHandleParamsIncludeLinksUnion `query:"includeLinks,omitzero" json:"-"` + // When true for PDF inputs, detect and OCR images embedded in the selected pages, + // inserting recognized text at each image's position in page reading order while + // preserving the PDF text layer. pdf.start/pdf.end limit the inclusive page range. + // When false, all OCR is disabled, including the automatic scanned-PDF fallback. + Ocr ParseHandleParamsOcrUnion `query:"ocr,omitzero" json:"-"` + // PDF page-range options as a JSON object, e.g. {"start": 2, "end": 5}. Pdf ParseHandleParamsPdf `query:"pdf,omitzero" json:"-"` + // Shorten base64-encoded image data in the Markdown output + ShortenBase64Images ParseHandleParamsShortenBase64ImagesUnion `query:"shortenBase64Images,omitzero" json:"-"` + // 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 []string `query:"tags,omitzero" json:"-"` + // Extract only the main content from HTML-like inputs + UseMainContentOnly ParseHandleParamsUseMainContentOnlyUnion `query:"useMainContentOnly,omitzero" json:"-"` + // 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. + // + // Any of "enabled", "disabled". + Zdr ParseHandleParamsZdr `query:"zdr,omitzero" json:"-"` paramObj } @@ -215,8 +222,8 @@ func (r ParseHandleParams) URLQuery() (v url.Values, err error) { }) } -// Optional file extension hint. Case-insensitive; a leading dot is accepted (e.g. -// ".pdf"). +// Optional file extension hint, such as pdf, docx, xlsx, pptx, html, json, csv, +// md, py, rtf, jpg, png, or txt. type ParseHandleParamsExtension string const ( @@ -292,8 +299,61 @@ const ( ParseHandleParamsExtensionPnm ParseHandleParamsExtension = "pnm" ) -// PDF page-range controls. Use start/end to limit parsing (and OCR when ocr=true) -// to an inclusive 1-based page range. +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type ParseHandleParamsIncludeImagesUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfParseHandlesIncludeImagesString) + OfParseHandlesIncludeImagesString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type ParseHandleParamsIncludeImagesString string + +const ( + ParseHandleParamsIncludeImagesStringTrue ParseHandleParamsIncludeImagesString = "true" + ParseHandleParamsIncludeImagesStringFalse ParseHandleParamsIncludeImagesString = "false" +) + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type ParseHandleParamsIncludeLinksUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfParseHandlesIncludeLinksString) + OfParseHandlesIncludeLinksString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type ParseHandleParamsIncludeLinksString string + +const ( + ParseHandleParamsIncludeLinksStringTrue ParseHandleParamsIncludeLinksString = "true" + ParseHandleParamsIncludeLinksStringFalse ParseHandleParamsIncludeLinksString = "false" +) + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type ParseHandleParamsOcrUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfParseHandlesOcrString) + OfParseHandlesOcrString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type ParseHandleParamsOcrString string + +const ( + ParseHandleParamsOcrStringTrue ParseHandleParamsOcrString = "true" + ParseHandleParamsOcrStringFalse ParseHandleParamsOcrString = "false" +) + +// PDF page-range options as a JSON object, e.g. {"start": 2, "end": 5}. type ParseHandleParamsPdf struct { // 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. @@ -310,3 +370,50 @@ func (r ParseHandleParamsPdf) URLQuery() (v url.Values, err error) { NestedFormat: apiquery.NestedQueryFormatBrackets, }) } + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type ParseHandleParamsShortenBase64ImagesUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfParseHandlesShortenBase64ImagesString) + OfParseHandlesShortenBase64ImagesString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type ParseHandleParamsShortenBase64ImagesString string + +const ( + ParseHandleParamsShortenBase64ImagesStringTrue ParseHandleParamsShortenBase64ImagesString = "true" + ParseHandleParamsShortenBase64ImagesStringFalse ParseHandleParamsShortenBase64ImagesString = "false" +) + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type ParseHandleParamsUseMainContentOnlyUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfParseHandlesUseMainContentOnlyString) + OfParseHandlesUseMainContentOnlyString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type ParseHandleParamsUseMainContentOnlyString string + +const ( + ParseHandleParamsUseMainContentOnlyStringTrue ParseHandleParamsUseMainContentOnlyString = "true" + ParseHandleParamsUseMainContentOnlyStringFalse ParseHandleParamsUseMainContentOnlyString = "false" +) + +// 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. +type ParseHandleParamsZdr string + +const ( + ParseHandleParamsZdrEnabled ParseHandleParamsZdr = "enabled" + ParseHandleParamsZdrDisabled ParseHandleParamsZdr = "disabled" +) diff --git a/parse_test.go b/parse_test.go index 4c04262..63cee25 100644 --- a/parse_test.go +++ b/parse_test.go @@ -32,16 +32,29 @@ func TestParseHandleWithOptionalParams(t *testing.T) { context.TODO(), io.Reader(bytes.NewBuffer([]byte("Example data"))), contextdev.ParseHandleParams{ - Extension: contextdev.ParseHandleParamsExtensionTxt, - IncludeImages: contextdev.Bool(true), - IncludeLinks: contextdev.Bool(true), - Ocr: contextdev.Bool(true), + Client: contextdev.String("x"), + Extension: contextdev.ParseHandleParamsExtensionTxt, + IncludeImages: contextdev.ParseHandleParamsIncludeImagesUnion{ + OfParseHandlesIncludeImagesString: contextdev.String("true"), + }, + IncludeLinks: contextdev.ParseHandleParamsIncludeLinksUnion{ + OfParseHandlesIncludeLinksString: contextdev.String("true"), + }, + Ocr: contextdev.ParseHandleParamsOcrUnion{ + OfParseHandlesOcrString: contextdev.String("true"), + }, Pdf: contextdev.ParseHandleParamsPdf{ End: contextdev.Int(1), Start: contextdev.Int(1), }, - ShortenBase64Images: contextdev.Bool(true), - UseMainContentOnly: contextdev.Bool(true), + ShortenBase64Images: contextdev.ParseHandleParamsShortenBase64ImagesUnion{ + OfParseHandlesShortenBase64ImagesString: contextdev.String("true"), + }, + Tags: []string{"production", "team-alpha"}, + UseMainContentOnly: contextdev.ParseHandleParamsUseMainContentOnlyUnion{ + OfParseHandlesUseMainContentOnlyString: contextdev.String("true"), + }, + Zdr: contextdev.ParseHandleParamsZdrEnabled, }, ) if err != nil { diff --git a/shared/constant/constants.go b/shared/constant/constants.go index b43d0b6..25a8648 100644 --- a/shared/constant/constants.go +++ b/shared/constant/constants.go @@ -27,8 +27,10 @@ type ByTransaction string // Always "by_transaction" type Exact string // Always "exact" type Extract string // Always "extract" type Page string // Always "page" +type Perform string // Always "perform" type Semantic string // Always "semantic" type Sitemap string // Always "sitemap" +type Wait string // Always "wait" func (c ByDirectURL) Default() ByDirectURL { return "by_direct_url" } func (c ByDomain) Default() ByDomain { return "by_domain" } @@ -39,8 +41,10 @@ func (c ByTransaction) Default() ByTransaction { return "by_transaction" } func (c Exact) Default() Exact { return "exact" } func (c Extract) Default() Extract { return "extract" } func (c Page) Default() Page { return "page" } +func (c Perform) Default() Perform { return "perform" } func (c Semantic) Default() Semantic { return "semantic" } func (c Sitemap) Default() Sitemap { return "sitemap" } +func (c Wait) Default() Wait { return "wait" } func (c ByDirectURL) MarshalJSON() ([]byte, error) { return marshalString(c) } func (c ByDomain) MarshalJSON() ([]byte, error) { return marshalString(c) } @@ -51,8 +55,10 @@ func (c ByTransaction) MarshalJSON() ([]byte, error) { return marshalString(c) } func (c Exact) MarshalJSON() ([]byte, error) { return marshalString(c) } func (c Extract) MarshalJSON() ([]byte, error) { return marshalString(c) } func (c Page) MarshalJSON() ([]byte, error) { return marshalString(c) } +func (c Perform) MarshalJSON() ([]byte, error) { return marshalString(c) } func (c Semantic) MarshalJSON() ([]byte, error) { return marshalString(c) } func (c Sitemap) MarshalJSON() ([]byte, error) { return marshalString(c) } +func (c Wait) MarshalJSON() ([]byte, error) { return marshalString(c) } type constant[T any] interface { Constant[T] diff --git a/utility.go b/utility.go index 4a4dd64..1945e43 100644 --- a/utility.go +++ b/utility.go @@ -118,6 +118,8 @@ type UtilityPrefetchParams struct { // than this value, it will be aborted with a 408 status code. Maximum allowed // value is 300000ms (5 minutes). TimeoutMs param.Opt[int64] `json:"timeoutMS,omitzero"` + // Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + Tags []string `json:"tags,omitzero"` paramObj } diff --git a/utility_test.go b/utility_test.go index 0a2ce19..1cc2df8 100644 --- a/utility_test.go +++ b/utility_test.go @@ -29,10 +29,11 @@ func TestUtilityPrefetchWithOptionalParams(t *testing.T) { _, err := client.Utility.Prefetch(context.TODO(), contextdev.UtilityPrefetchParams{ Identifier: contextdev.UtilityPrefetchParamsIdentifierUnion{ OfByDomain: &contextdev.UtilityPrefetchParamsIdentifierByDomain{ - Domain: "domain", + Domain: "xxx", }, }, Type: contextdev.UtilityPrefetchParamsTypeBrand, + Tags: []string{"production", "team-alpha"}, TimeoutMs: contextdev.Int(1000), }) if err != nil { diff --git a/web.go b/web.go index 60d030a..6a67bd1 100644 --- a/web.go +++ b/web.go @@ -15,6 +15,7 @@ import ( "github.com/context-dot-dev/context-go-sdk/v2/option" "github.com/context-dot-dev/context-go-sdk/v2/packages/param" "github.com/context-dot-dev/context-go-sdk/v2/packages/respjson" + "github.com/context-dot-dev/context-go-sdk/v2/shared/constant" ) // WebService contains methods and other services that help with interacting with @@ -97,7 +98,8 @@ func (r *WebService) WebCrawlMd(ctx context.Context, body WebWebCrawlMdParams, o return res, err } -// Scrapes the given URL and returns the raw HTML content of the page. +// 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. func (r *WebService) WebScrapeHTML(ctx context.Context, query WebWebScrapeHTMLParams, opts ...option.RequestOption) (res *WebWebScrapeHTMLResponse, err error) { opts = slices.Concat(r.options, opts) path := "web/scrape/html" @@ -107,8 +109,9 @@ func (r *WebService) WebScrapeHTML(ctx context.Context, query WebWebScrapeHTMLPa // 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. When enrichment is enabled, the entire -// call costs 5 credits. +// 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. func (r *WebService) WebScrapeImages(ctx context.Context, query WebWebScrapeImagesParams, opts ...option.RequestOption) (res *WebWebScrapeImagesResponse, err error) { opts = slices.Concat(r.options, opts) path := "web/scrape/images" @@ -122,16 +125,16 @@ func (r *WebService) WebScrapeImages(ctx context.Context, query WebWebScrapeImag // // ### Billing & errors // -// | HTTP status | Billed? | Meaning | -// | ----------- | -------------- | ---------------------------------------------------------------------------------------- | -// | 200 | Yes — 1 credit | Successful scrape, including a zero-length result when includeSelectors matched nothing | -// | 400 | No | Invalid input, skipped PDF, or the page could not be scraped | -// | 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 | -// | 415 | No | Unsupported content type | -// | 429 | No | Per-minute rate limit exceeded; honor Retry-After | -// | 500 | No | Internal error | +// | HTTP status | Billed? | Meaning | +// | ----------- | ----------------------------------------- | ---------------------------------------------------------------------------------------- | +// | 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing | +// | 400 | No | Invalid input, skipped PDF, or the page could not be scraped | +// | 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 | +// | 415 | No | Unsupported content type | +// | 429 | No | Per-minute rate limit exceeded; honor Retry-After | +// | 500 | No | Internal error | func (r *WebService) WebScrapeMd(ctx context.Context, query WebWebScrapeMdParams, opts ...option.RequestOption) (res *WebWebScrapeMdResponse, err error) { opts = slices.Concat(r.options, opts) path := "web/scrape/markdown" @@ -1125,7 +1128,8 @@ type WebScreenshotResponse struct { // 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. KeyMetadata WebScreenshotResponseKeyMetadata `json:"key_metadata"` - // Public URL of the uploaded screenshot image + // Public image URL for standard requests, or an in-memory data URL when ZDR is + // enabled. Screenshot string `json:"screenshot"` // Type of screenshot that was captured // @@ -2387,6 +2391,10 @@ type WebExtractParams struct { MaxDepth param.Opt[int64] `json:"maxDepth,omitzero"` // Maximum number of pages to analyze for extraction. Hard cap: 50. Defaults to 5. MaxPages param.Opt[int64] `json:"maxPages,omitzero"` + // 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 param.Opt[bool] `json:"settleAnimations,omitzero"` // Soft time budget for the crawl in milliseconds. Min: 10000 (10s). Max: 110000 // (110s). Default: 80000 (80s). StopAfterMs param.Opt[int64] `json:"stopAfterMs,omitzero"` @@ -2398,6 +2406,8 @@ type WebExtractParams struct { // crawled page. WaitForMs param.Opt[int64] `json:"waitForMs,omitzero"` Pdf WebExtractParamsPdf `json:"pdf,omitzero"` + // Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + Tags []string `json:"tags,omitzero"` paramObj } @@ -2438,6 +2448,10 @@ type WebExtractCompetitorsParams struct { // than this value, it will be aborted with a 408 status code. Maximum allowed // value is 300000ms (5 minutes). TimeoutMs param.Opt[int64] `query:"timeoutMS,omitzero" json:"-"` + // 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 []string `query:"tags,omitzero" json:"-"` paramObj } @@ -2451,6 +2465,11 @@ func (r WebExtractCompetitorsParams) URLQuery() (v url.Values, err error) { } type WebExtractFontsParams struct { + // 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. + MaxAgeMs param.Opt[int64] `query:"maxAgeMs,omitzero" json:"-"` // 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. @@ -2459,15 +2478,14 @@ type WebExtractFontsParams struct { // domain will be automatically normalized and validated. You must provide either // 'domain' or 'directUrl', but not both. Domain param.Opt[string] `query:"domain,omitzero" json:"-"` - // Maximum age in milliseconds for cached 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. - MaxAgeMs param.Opt[int64] `query:"maxAgeMs,omitzero" json:"-"` // 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 param.Opt[int64] `query:"timeoutMS,omitzero" json:"-"` + // 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 []string `query:"tags,omitzero" json:"-"` paramObj } @@ -2480,6 +2498,11 @@ func (r WebExtractFontsParams) URLQuery() (v url.Values, err error) { } type WebExtractStyleguideParams struct { + // 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. + MaxAgeMs param.Opt[int64] `query:"maxAgeMs,omitzero" json:"-"` // 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 @@ -2489,11 +2512,6 @@ type WebExtractStyleguideParams struct { // domain will be automatically normalized and validated. You must provide either // 'domain' or 'directUrl', but not both. Domain param.Opt[string] `query:"domain,omitzero" json:"-"` - // Maximum age in milliseconds for cached 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. - MaxAgeMs param.Opt[int64] `query:"maxAgeMs,omitzero" json:"-"` // 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). @@ -2503,6 +2521,10 @@ type WebExtractStyleguideParams struct { // // Any of "light", "dark". ColorScheme WebExtractStyleguideParamsColorScheme `query:"colorScheme,omitzero" json:"-"` + // 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 []string `query:"tags,omitzero" json:"-"` paramObj } @@ -2525,14 +2547,6 @@ const ( ) type WebScreenshotParams struct { - // 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 param.Opt[string] `query:"directUrl,omitzero" format:"uri" json:"-"` - // 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 param.Opt[string] `query:"domain,omitzero" json:"-"` // 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. @@ -2544,21 +2558,30 @@ type WebScreenshotParams struct { // top to bottom). The final slice may be shorter than the viewport height. Takes // precedence over fullScreenshot. Max: 100000. ScrollOffset param.Opt[int64] `query:"scrollOffset,omitzero" json:"-"` - // 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 param.Opt[int64] `query:"timeoutMS,omitzero" json:"-"` // 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. WaitForMs param.Opt[int64] `query:"waitForMs,omitzero" json:"-"` + // 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 param.Opt[string] `query:"directUrl,omitzero" format:"uri" json:"-"` + // 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 param.Opt[string] `query:"domain,omitzero" json:"-"` + // 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 param.Opt[int64] `query:"timeoutMS,omitzero" json:"-"` // Optional parameter to choose the site's visual theme in the screenshot. Use // 'light' or 'dark' when the site offers both appearances. // // Any of "light", "dark". ColorScheme WebScreenshotParamsColorScheme `query:"colorScheme,omitzero" json:"-"` - // Two-letter ISO 3166-1 alpha-2 country code for the website request location. - // When provided, Context.dev fetches the target page from that country. + // Two-letter ISO 3166-1 alpha-2 country code identifying a supported Context.dev + // residential proxy exit location. Must be one of Context.dev's supported + // countries. When provided, Context.dev fetches the target page from that country. // // Any of "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", @@ -2586,9 +2609,7 @@ type WebScreenshotParams struct { // 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. - // - // Any of "true", "false". - HandleCookiePopup WebScreenshotParamsHandleCookiePopup `query:"handleCookiePopup,omitzero" json:"-"` + HandleCookiePopup WebScreenshotParamsHandleCookiePopupUnion `query:"handleCookiePopup,omitzero" json:"-"` // 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 @@ -2598,8 +2619,19 @@ type WebScreenshotParams struct { // Any of "login", "signup", "blog", "careers", "pricing", "terms", "privacy", // "contact". Page WebScreenshotParamsPage `query:"page,omitzero" json:"-"` + // 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 []string `query:"tags,omitzero" json:"-"` // Optional browser viewport dimensions for the screenshot. Defaults to 1920x1080. Viewport WebScreenshotParamsViewport `query:"viewport,omitzero" json:"-"` + // 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. + // + // Any of "enabled", "disabled". + Zdr WebScreenshotParamsZdr `query:"zdr,omitzero" json:"-"` paramObj } @@ -2620,8 +2652,9 @@ const ( WebScreenshotParamsColorSchemeDark WebScreenshotParamsColorScheme = "dark" ) -// Two-letter ISO 3166-1 alpha-2 country code for the website request location. -// When provided, Context.dev fetches the target page from that country. +// Two-letter ISO 3166-1 alpha-2 country code identifying a supported Context.dev +// residential proxy exit location. Must be one of Context.dev's supported +// countries. When provided, Context.dev fetches the target page from that country. type WebScreenshotParamsCountry string const ( @@ -2841,14 +2874,22 @@ const ( WebScreenshotParamsFullScreenshotFalse WebScreenshotParamsFullScreenshot = "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. -type WebScreenshotParamsHandleCookiePopup string +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebScreenshotParamsHandleCookiePopupUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebScreenshotsHandleCookiePopupString) + OfWebScreenshotsHandleCookiePopupString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebScreenshotParamsHandleCookiePopupString string const ( - WebScreenshotParamsHandleCookiePopupTrue WebScreenshotParamsHandleCookiePopup = "true" - WebScreenshotParamsHandleCookiePopupFalse WebScreenshotParamsHandleCookiePopup = "false" + WebScreenshotParamsHandleCookiePopupStringTrue WebScreenshotParamsHandleCookiePopupString = "true" + WebScreenshotParamsHandleCookiePopupStringFalse WebScreenshotParamsHandleCookiePopupString = "false" ) // Optional parameter to specify which page type to screenshot. If provided, the @@ -2887,6 +2928,17 @@ func (r WebScreenshotParamsViewport) URLQuery() (v url.Values, err error) { }) } +// 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. +type WebScreenshotParamsZdr string + +const ( + WebScreenshotParamsZdrEnabled WebScreenshotParamsZdr = "enabled" + WebScreenshotParamsZdrDisabled WebScreenshotParamsZdr = "disabled" +) + type WebSearchParams struct { // Search query. Accepts natural language as well as Google-style search operators // such as `site:`, `-site:`, `inurl:`, `intitle:`, quoted phrases, and `OR`. @@ -2934,6 +2986,8 @@ type WebSearchParams struct { IncludeDomains []string `json:"includeDomains,omitzero"` // Inline Markdown scraping for each result. Set `enabled: true` to activate. MarkdownOptions WebSearchParamsMarkdownOptions `json:"markdownOptions,omitzero"` + // Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + Tags []string `json:"tags,omitzero"` paramObj } @@ -3336,6 +3390,15 @@ type WebWebCrawlMdParams struct { // PDF parsing controls. Use start/end to limit text extraction and embedded-image // detection/OCR to an inclusive 1-based page range. Pdf WebWebCrawlMdParamsPdf `json:"pdf,omitzero"` + // Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. + Tags []string `json:"tags,omitzero"` + // 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. + // + // Any of "enabled", "disabled". + Zdr WebWebCrawlMdParamsZdr `json:"zdr,omitzero"` paramObj } @@ -3585,31 +3648,46 @@ func (r *WebWebCrawlMdParamsPdf) UnmarshalJSON(data []byte) error { return apijson.UnmarshalRoot(data, r) } +// 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. +type WebWebCrawlMdParamsZdr string + +const ( + WebWebCrawlMdParamsZdrEnabled WebWebCrawlMdParamsZdr = "enabled" + WebWebCrawlMdParamsZdrDisabled WebWebCrawlMdParamsZdr = "disabled" +) + type WebWebScrapeHTMLParams struct { // Full URL to scrape (must include http:// or https:// protocol) URL string `query:"url" api:"required" format:"uri" json:"-"` - // When true, iframes are rendered inline into the returned HTML. - IncludeFrames param.Opt[bool] `query:"includeFrames,omitzero" json:"-"` // 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 param.Opt[int64] `query:"maxAgeMs,omitzero" json:"-"` - // 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 param.Opt[bool] `query:"settleAnimations,omitzero" json:"-"` + // Optional browser wait time in milliseconds after initial page load. Min: 0. Max: + // 30000 (30 seconds). + WaitForMs param.Opt[int64] `query:"waitForMs,omitzero" json:"-"` // 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 param.Opt[int64] `query:"timeoutMS,omitzero" json:"-"` - // When true, return only the page's main content in the HTML response, excluding - // headers, footers, sidebars, and navigation when detectable. - UseMainContentOnly param.Opt[bool] `query:"useMainContentOnly,omitzero" json:"-"` - // Optional browser wait time in milliseconds after initial page load. Min: 0. Max: - // 30000 (30 seconds). - WaitForMs param.Opt[int64] `query:"waitForMs,omitzero" json:"-"` - // Two-letter ISO 3166-1 alpha-2 country code for the website request location. - // When provided, Context.dev fetches the target page from that country. + // 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 []WebWebScrapeHTMLParamsActionUnion `query:"actions,omitzero" json:"-"` + // 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 []string `query:"excludeSelectors,omitzero" json:"-"` + // 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 []string `query:"includeSelectors,omitzero" json:"-"` + // Two-letter ISO 3166-1 alpha-2 country code identifying a supported Context.dev + // residential proxy exit location. Must be one of Context.dev's supported + // countries. When provided, Context.dev fetches the target page from that country. // // Any of "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", @@ -3628,21 +3706,33 @@ type WebWebScrapeHTMLParams struct { // "tj", "tl", "tm", "tn", "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz", // "vc", "ve", "vg", "vi", "vn", "ye", "yt", "za", "zm", "zw". Country WebWebScrapeHTMLParamsCountry `query:"country,omitzero" json:"-"` - // 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 []string `query:"excludeSelectors,omitzero" json:"-"` // 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 map[string]string `query:"headers,omitzero" json:"-"` - // 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 []string `query:"includeSelectors,omitzero" json:"-"` + // When true, iframes are rendered inline into the returned HTML. + IncludeFrames WebWebScrapeHTMLParamsIncludeFramesUnion `query:"includeFrames,omitzero" json:"-"` // PDF parsing controls. Use start/end to limit text extraction and embedded-image // detection/OCR to an inclusive 1-based page range. Pdf WebWebScrapeHTMLParamsPdf `query:"pdf,omitzero" json:"-"` + // 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 WebWebScrapeHTMLParamsSettleAnimationsUnion `query:"settleAnimations,omitzero" json:"-"` + // 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 []string `query:"tags,omitzero" json:"-"` + // When true, return only the page's main content in the HTML response, excluding + // headers, footers, sidebars, and navigation when detectable. + UseMainContentOnly WebWebScrapeHTMLParamsUseMainContentOnlyUnion `query:"useMainContentOnly,omitzero" json:"-"` + // 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. + // + // Any of "enabled", "disabled". + Zdr WebWebScrapeHTMLParamsZdr `query:"zdr,omitzero" json:"-"` paramObj } @@ -3654,8 +3744,64 @@ func (r WebWebScrapeHTMLParams) URLQuery() (v url.Values, err error) { }) } -// Two-letter ISO 3166-1 alpha-2 country code for the website request location. -// When provided, Context.dev fetches the target page from that country. +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeHTMLParamsActionUnion struct { + OfWait *WebWebScrapeHTMLParamsActionWait `query:",omitzero,inline"` + OfPerform *WebWebScrapeHTMLParamsActionPerform `query:",omitzero,inline"` + paramUnion +} + +func init() { + apijson.RegisterUnion[WebWebScrapeHTMLParamsActionUnion]( + "do", + apijson.Discriminator[WebWebScrapeHTMLParamsActionWait]("wait"), + apijson.Discriminator[WebWebScrapeHTMLParamsActionPerform]("perform"), + ) +} + +// Pause for a fixed number of milliseconds before continuing to the next action. +// +// The properties Do, TimeMs are required. +type WebWebScrapeHTMLParamsActionWait struct { + TimeMs int64 `query:"timeMs" api:"required" json:"-"` + // This field can be elided, and will marshal its zero value as "wait". + Do constant.Wait `query:"do" json:"-" default:"wait"` + paramObj +} + +// URLQuery serializes [WebWebScrapeHTMLParamsActionWait]'s query parameters as +// `url.Values`. +func (r WebWebScrapeHTMLParamsActionWait) URLQuery() (v url.Values, err error) { + return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{ + ArrayFormat: apiquery.ArrayQueryFormatComma, + NestedFormat: apiquery.NestedQueryFormatBrackets, + }) +} + +// Resolve and perform one natural-language browser action. +// +// The properties Action, Do are required. +type WebWebScrapeHTMLParamsActionPerform struct { + Action string `query:"action" api:"required" json:"-"` + // This field can be elided, and will marshal its zero value as "perform". + Do constant.Perform `query:"do" json:"-" default:"perform"` + paramObj +} + +// URLQuery serializes [WebWebScrapeHTMLParamsActionPerform]'s query parameters as +// `url.Values`. +func (r WebWebScrapeHTMLParamsActionPerform) URLQuery() (v url.Values, err error) { + return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{ + ArrayFormat: apiquery.ArrayQueryFormatComma, + NestedFormat: apiquery.NestedQueryFormatBrackets, + }) +} + +// Two-letter ISO 3166-1 alpha-2 country code identifying a supported Context.dev +// residential proxy exit location. Must be one of Context.dev's supported +// countries. When provided, Context.dev fetches the target page from that country. type WebWebScrapeHTMLParamsCountry string const ( @@ -3865,21 +4011,39 @@ const ( WebWebScrapeHTMLParamsCountryZw WebWebScrapeHTMLParamsCountry = "zw" ) +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeHTMLParamsIncludeFramesUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeHTMLsIncludeFramesString) + OfWebWebScrapeHTMLsIncludeFramesString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeHTMLParamsIncludeFramesString string + +const ( + WebWebScrapeHTMLParamsIncludeFramesStringTrue WebWebScrapeHTMLParamsIncludeFramesString = "true" + WebWebScrapeHTMLParamsIncludeFramesStringFalse WebWebScrapeHTMLParamsIncludeFramesString = "false" +) + // PDF parsing controls. Use start/end to limit text extraction and embedded-image // detection/OCR to an inclusive 1-based page range. type WebWebScrapeHTMLParamsPdf struct { // 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 param.Opt[int64] `query:"end,omitzero" json:"-"` + // First 1-based PDF page to parse. When omitted, parsing starts at the first page. + Start param.Opt[int64] `query:"start,omitzero" json:"-"` // When true, detect and OCR images embedded in the selected PDF pages, inserting // recognized text at each image's position in page reading order while preserving // the PDF text layer. This is separate from automatic scanned-PDF OCR fallback. - Ocr param.Opt[bool] `query:"ocr,omitzero" json:"-"` + Ocr WebWebScrapeHTMLParamsPdfOcrUnion `query:"ocr,omitzero" json:"-"` // When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and // a 400 WEBSITE_ACCESS_ERROR is returned. - ShouldParse param.Opt[bool] `query:"shouldParse,omitzero" json:"-"` - // First 1-based PDF page to parse. When omitted, parsing starts at the first page. - Start param.Opt[int64] `query:"start,omitzero" json:"-"` + ShouldParse WebWebScrapeHTMLParamsPdfShouldParseUnion `query:"shouldParse,omitzero" json:"-"` paramObj } @@ -3892,31 +4056,122 @@ func (r WebWebScrapeHTMLParamsPdf) URLQuery() (v url.Values, err error) { }) } +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeHTMLParamsPdfOcrUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeHTMLsPdfOcrString) + OfWebWebScrapeHTMLsPdfOcrString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeHTMLParamsPdfOcrString string + +const ( + WebWebScrapeHTMLParamsPdfOcrStringTrue WebWebScrapeHTMLParamsPdfOcrString = "true" + WebWebScrapeHTMLParamsPdfOcrStringFalse WebWebScrapeHTMLParamsPdfOcrString = "false" +) + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeHTMLParamsPdfShouldParseUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeHTMLsPdfShouldParseString) + OfWebWebScrapeHTMLsPdfShouldParseString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeHTMLParamsPdfShouldParseString string + +const ( + WebWebScrapeHTMLParamsPdfShouldParseStringTrue WebWebScrapeHTMLParamsPdfShouldParseString = "true" + WebWebScrapeHTMLParamsPdfShouldParseStringFalse WebWebScrapeHTMLParamsPdfShouldParseString = "false" +) + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeHTMLParamsSettleAnimationsUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeHTMLsSettleAnimationsString) + OfWebWebScrapeHTMLsSettleAnimationsString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeHTMLParamsSettleAnimationsString string + +const ( + WebWebScrapeHTMLParamsSettleAnimationsStringTrue WebWebScrapeHTMLParamsSettleAnimationsString = "true" + WebWebScrapeHTMLParamsSettleAnimationsStringFalse WebWebScrapeHTMLParamsSettleAnimationsString = "false" +) + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeHTMLParamsUseMainContentOnlyUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeHTMLsUseMainContentOnlyString) + OfWebWebScrapeHTMLsUseMainContentOnlyString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeHTMLParamsUseMainContentOnlyString string + +const ( + WebWebScrapeHTMLParamsUseMainContentOnlyStringTrue WebWebScrapeHTMLParamsUseMainContentOnlyString = "true" + WebWebScrapeHTMLParamsUseMainContentOnlyStringFalse WebWebScrapeHTMLParamsUseMainContentOnlyString = "false" +) + +// 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. +type WebWebScrapeHTMLParamsZdr string + +const ( + WebWebScrapeHTMLParamsZdrEnabled WebWebScrapeHTMLParamsZdr = "enabled" + WebWebScrapeHTMLParamsZdrDisabled WebWebScrapeHTMLParamsZdr = "disabled" +) + type WebWebScrapeImagesParams struct { // Page URL to inspect. Must include http:// or https://. URL string `query:"url" api:"required" format:"uri" json:"-"` - // 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. - Dedupe param.Opt[bool] `query:"dedupe,omitzero" json:"-"` // Reuse a cached result this many milliseconds old or newer. Default: 86400000 (1 // day). Set to 0 to bypass cache. Maximum: 2592000000 (30 days). MaxAgeMs param.Opt[int64] `query:"maxAgeMs,omitzero" json:"-"` + // Optional browser wait time in milliseconds after initial page load before + // collecting images. Min: 0. Max: 30000 (30 seconds). + WaitForMs param.Opt[int64] `query:"waitForMs,omitzero" json:"-"` // 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 param.Opt[int64] `query:"timeoutMS,omitzero" json:"-"` - // Optional browser wait time in milliseconds after initial page load before - // collecting images. Min: 0. Max: 30000 (30 seconds). - WaitForMs param.Opt[int64] `query:"waitForMs,omitzero" json:"-"` + // 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 []WebWebScrapeImagesParamsActionUnion `query:"actions,omitzero" json:"-"` // Optional per-image processing, sent as deep-object query params such as // enrichment[resolution]=true. Enrichment WebWebScrapeImagesParamsEnrichment `query:"enrichment,omitzero" json:"-"` + // 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. + Dedupe WebWebScrapeImagesParamsDedupeUnion `query:"dedupe,omitzero" json:"-"` // 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 map[string]string `query:"headers,omitzero" json:"-"` + // 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 []string `query:"tags,omitzero" json:"-"` paramObj } @@ -3929,18 +4184,91 @@ func (r WebWebScrapeImagesParams) URLQuery() (v url.Values, err error) { }) } +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeImagesParamsActionUnion struct { + OfWait *WebWebScrapeImagesParamsActionWait `query:",omitzero,inline"` + OfPerform *WebWebScrapeImagesParamsActionPerform `query:",omitzero,inline"` + paramUnion +} + +func init() { + apijson.RegisterUnion[WebWebScrapeImagesParamsActionUnion]( + "do", + apijson.Discriminator[WebWebScrapeImagesParamsActionWait]("wait"), + apijson.Discriminator[WebWebScrapeImagesParamsActionPerform]("perform"), + ) +} + +// Pause for a fixed number of milliseconds before continuing to the next action. +// +// The properties Do, TimeMs are required. +type WebWebScrapeImagesParamsActionWait struct { + TimeMs int64 `query:"timeMs" api:"required" json:"-"` + // This field can be elided, and will marshal its zero value as "wait". + Do constant.Wait `query:"do" json:"-" default:"wait"` + paramObj +} + +// URLQuery serializes [WebWebScrapeImagesParamsActionWait]'s query parameters as +// `url.Values`. +func (r WebWebScrapeImagesParamsActionWait) URLQuery() (v url.Values, err error) { + return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{ + ArrayFormat: apiquery.ArrayQueryFormatComma, + NestedFormat: apiquery.NestedQueryFormatBrackets, + }) +} + +// Resolve and perform one natural-language browser action. +// +// The properties Action, Do are required. +type WebWebScrapeImagesParamsActionPerform struct { + Action string `query:"action" api:"required" json:"-"` + // This field can be elided, and will marshal its zero value as "perform". + Do constant.Perform `query:"do" json:"-" default:"perform"` + paramObj +} + +// URLQuery serializes [WebWebScrapeImagesParamsActionPerform]'s query parameters +// as `url.Values`. +func (r WebWebScrapeImagesParamsActionPerform) URLQuery() (v url.Values, err error) { + return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{ + ArrayFormat: apiquery.ArrayQueryFormatComma, + NestedFormat: apiquery.NestedQueryFormatBrackets, + }) +} + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeImagesParamsDedupeUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeImagessDedupeString) + OfWebWebScrapeImagessDedupeString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeImagesParamsDedupeString string + +const ( + WebWebScrapeImagesParamsDedupeStringTrue WebWebScrapeImagesParamsDedupeString = "true" + WebWebScrapeImagesParamsDedupeStringFalse WebWebScrapeImagesParamsDedupeString = "false" +) + // Optional per-image processing, sent as deep-object query params such as // enrichment[resolution]=true. type WebWebScrapeImagesParamsEnrichment struct { + // Per-image enrichment timeout in milliseconds. Default: 30000. Maximum: 60000. + MaxTimePerMs param.Opt[int64] `query:"maxTimePerMs,omitzero" json:"-"` // Classify each image by visual asset type. - Classification param.Opt[bool] `query:"classification,omitzero" json:"-"` + Classification WebWebScrapeImagesParamsEnrichmentClassificationUnion `query:"classification,omitzero" json:"-"` // Host materializable images on the Brand.dev CDN and return their URL and MIME // type. - HostedURL param.Opt[bool] `query:"hostedUrl,omitzero" json:"-"` - // Per-image enrichment timeout in milliseconds. Default: 30000. Maximum: 60000. - MaxTimePerMs param.Opt[int64] `query:"maxTimePerMs,omitzero" json:"-"` + HostedURL WebWebScrapeImagesParamsEnrichmentHostedURLUnion `query:"hostedUrl,omitzero" json:"-"` // Measure image width and height when possible. - Resolution param.Opt[bool] `query:"resolution,omitzero" json:"-"` + Resolution WebWebScrapeImagesParamsEnrichmentResolutionUnion `query:"resolution,omitzero" json:"-"` paramObj } @@ -3953,38 +4281,90 @@ func (r WebWebScrapeImagesParamsEnrichment) URLQuery() (v url.Values, err error) }) } +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeImagesParamsEnrichmentClassificationUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeImagessEnrichmentClassificationString) + OfWebWebScrapeImagessEnrichmentClassificationString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeImagesParamsEnrichmentClassificationString string + +const ( + WebWebScrapeImagesParamsEnrichmentClassificationStringTrue WebWebScrapeImagesParamsEnrichmentClassificationString = "true" + WebWebScrapeImagesParamsEnrichmentClassificationStringFalse WebWebScrapeImagesParamsEnrichmentClassificationString = "false" +) + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeImagesParamsEnrichmentHostedURLUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeImagessEnrichmentHostedURLString) + OfWebWebScrapeImagessEnrichmentHostedURLString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeImagesParamsEnrichmentHostedURLString string + +const ( + WebWebScrapeImagesParamsEnrichmentHostedURLStringTrue WebWebScrapeImagesParamsEnrichmentHostedURLString = "true" + WebWebScrapeImagesParamsEnrichmentHostedURLStringFalse WebWebScrapeImagesParamsEnrichmentHostedURLString = "false" +) + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeImagesParamsEnrichmentResolutionUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeImagessEnrichmentResolutionString) + OfWebWebScrapeImagessEnrichmentResolutionString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeImagesParamsEnrichmentResolutionString string + +const ( + WebWebScrapeImagesParamsEnrichmentResolutionStringTrue WebWebScrapeImagesParamsEnrichmentResolutionString = "true" + WebWebScrapeImagesParamsEnrichmentResolutionStringFalse WebWebScrapeImagesParamsEnrichmentResolutionString = "false" +) + type WebWebScrapeMdParams struct { // Full URL to scrape into LLM usable Markdown (must include http:// or https:// // protocol) URL string `query:"url" api:"required" format:"uri" json:"-"` - // When true, the contents of iframes are rendered to Markdown. - IncludeFrames param.Opt[bool] `query:"includeFrames,omitzero" json:"-"` - // Include image references in Markdown output - IncludeImages param.Opt[bool] `query:"includeImages,omitzero" json:"-"` - // Preserve hyperlinks in Markdown output - IncludeLinks param.Opt[bool] `query:"includeLinks,omitzero" json:"-"` // 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 param.Opt[int64] `query:"maxAgeMs,omitzero" json:"-"` - // 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. - SettleAnimations param.Opt[bool] `query:"settleAnimations,omitzero" json:"-"` - // Shorten base64-encoded image data in the Markdown output - ShortenBase64Images param.Opt[bool] `query:"shortenBase64Images,omitzero" json:"-"` + // Optional browser wait time in milliseconds after initial page load before + // converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). + WaitForMs param.Opt[int64] `query:"waitForMs,omitzero" json:"-"` // 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 param.Opt[int64] `query:"timeoutMS,omitzero" json:"-"` - // Extract only the main content of the page, excluding headers, footers, sidebars, - // and navigation - UseMainContentOnly param.Opt[bool] `query:"useMainContentOnly,omitzero" json:"-"` - // Optional browser wait time in milliseconds after initial page load before - // converting the page to Markdown. Min: 0. Max: 30000 (30 seconds). - WaitForMs param.Opt[int64] `query:"waitForMs,omitzero" json:"-"` - // Two-letter ISO 3166-1 alpha-2 country code for the website request location. - // When provided, Context.dev fetches the target page from that country. + // 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 []WebWebScrapeMdParamsActionUnion `query:"actions,omitzero" json:"-"` + // 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 []string `query:"excludeSelectors,omitzero" json:"-"` + // 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]". + IncludeSelectors []string `query:"includeSelectors,omitzero" json:"-"` + // Two-letter ISO 3166-1 alpha-2 country code identifying a supported Context.dev + // residential proxy exit location. Must be one of Context.dev's supported + // countries. When provided, Context.dev fetches the target page from that country. // // Any of "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", @@ -4003,21 +4383,39 @@ type WebWebScrapeMdParams struct { // "tj", "tl", "tm", "tn", "tr", "tt", "tw", "tz", "ua", "ug", "us", "uy", "uz", // "vc", "ve", "vg", "vi", "vn", "ye", "yt", "za", "zm", "zw". Country WebWebScrapeMdParamsCountry `query:"country,omitzero" json:"-"` - // 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 []string `query:"excludeSelectors,omitzero" json:"-"` // 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 map[string]string `query:"headers,omitzero" json:"-"` - // 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]". - IncludeSelectors []string `query:"includeSelectors,omitzero" json:"-"` + // When true, the contents of iframes are rendered to Markdown. + IncludeFrames WebWebScrapeMdParamsIncludeFramesUnion `query:"includeFrames,omitzero" json:"-"` + // Include image references in Markdown output + IncludeImages WebWebScrapeMdParamsIncludeImagesUnion `query:"includeImages,omitzero" json:"-"` + // Preserve hyperlinks in Markdown output + IncludeLinks WebWebScrapeMdParamsIncludeLinksUnion `query:"includeLinks,omitzero" json:"-"` // PDF parsing controls. Use start/end to limit text extraction and embedded-image // detection/OCR to an inclusive 1-based page range. Pdf WebWebScrapeMdParamsPdf `query:"pdf,omitzero" json:"-"` + // 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. + SettleAnimations WebWebScrapeMdParamsSettleAnimationsUnion `query:"settleAnimations,omitzero" json:"-"` + // Shorten base64-encoded image data in the Markdown output + ShortenBase64Images WebWebScrapeMdParamsShortenBase64ImagesUnion `query:"shortenBase64Images,omitzero" json:"-"` + // 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 []string `query:"tags,omitzero" json:"-"` + // Extract only the main content of the page, excluding headers, footers, sidebars, + // and navigation + UseMainContentOnly WebWebScrapeMdParamsUseMainContentOnlyUnion `query:"useMainContentOnly,omitzero" json:"-"` + // 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. + // + // Any of "enabled", "disabled". + Zdr WebWebScrapeMdParamsZdr `query:"zdr,omitzero" json:"-"` paramObj } @@ -4029,8 +4427,64 @@ func (r WebWebScrapeMdParams) URLQuery() (v url.Values, err error) { }) } -// Two-letter ISO 3166-1 alpha-2 country code for the website request location. -// When provided, Context.dev fetches the target page from that country. +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeMdParamsActionUnion struct { + OfWait *WebWebScrapeMdParamsActionWait `query:",omitzero,inline"` + OfPerform *WebWebScrapeMdParamsActionPerform `query:",omitzero,inline"` + paramUnion +} + +func init() { + apijson.RegisterUnion[WebWebScrapeMdParamsActionUnion]( + "do", + apijson.Discriminator[WebWebScrapeMdParamsActionWait]("wait"), + apijson.Discriminator[WebWebScrapeMdParamsActionPerform]("perform"), + ) +} + +// Pause for a fixed number of milliseconds before continuing to the next action. +// +// The properties Do, TimeMs are required. +type WebWebScrapeMdParamsActionWait struct { + TimeMs int64 `query:"timeMs" api:"required" json:"-"` + // This field can be elided, and will marshal its zero value as "wait". + Do constant.Wait `query:"do" json:"-" default:"wait"` + paramObj +} + +// URLQuery serializes [WebWebScrapeMdParamsActionWait]'s query parameters as +// `url.Values`. +func (r WebWebScrapeMdParamsActionWait) URLQuery() (v url.Values, err error) { + return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{ + ArrayFormat: apiquery.ArrayQueryFormatComma, + NestedFormat: apiquery.NestedQueryFormatBrackets, + }) +} + +// Resolve and perform one natural-language browser action. +// +// The properties Action, Do are required. +type WebWebScrapeMdParamsActionPerform struct { + Action string `query:"action" api:"required" json:"-"` + // This field can be elided, and will marshal its zero value as "perform". + Do constant.Perform `query:"do" json:"-" default:"perform"` + paramObj +} + +// URLQuery serializes [WebWebScrapeMdParamsActionPerform]'s query parameters as +// `url.Values`. +func (r WebWebScrapeMdParamsActionPerform) URLQuery() (v url.Values, err error) { + return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{ + ArrayFormat: apiquery.ArrayQueryFormatComma, + NestedFormat: apiquery.NestedQueryFormatBrackets, + }) +} + +// Two-letter ISO 3166-1 alpha-2 country code identifying a supported Context.dev +// residential proxy exit location. Must be one of Context.dev's supported +// countries. When provided, Context.dev fetches the target page from that country. type WebWebScrapeMdParamsCountry string const ( @@ -4240,21 +4694,75 @@ const ( WebWebScrapeMdParamsCountryZw WebWebScrapeMdParamsCountry = "zw" ) +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeMdParamsIncludeFramesUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeMdsIncludeFramesString) + OfWebWebScrapeMdsIncludeFramesString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeMdParamsIncludeFramesString string + +const ( + WebWebScrapeMdParamsIncludeFramesStringTrue WebWebScrapeMdParamsIncludeFramesString = "true" + WebWebScrapeMdParamsIncludeFramesStringFalse WebWebScrapeMdParamsIncludeFramesString = "false" +) + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeMdParamsIncludeImagesUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeMdsIncludeImagesString) + OfWebWebScrapeMdsIncludeImagesString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeMdParamsIncludeImagesString string + +const ( + WebWebScrapeMdParamsIncludeImagesStringTrue WebWebScrapeMdParamsIncludeImagesString = "true" + WebWebScrapeMdParamsIncludeImagesStringFalse WebWebScrapeMdParamsIncludeImagesString = "false" +) + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeMdParamsIncludeLinksUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeMdsIncludeLinksString) + OfWebWebScrapeMdsIncludeLinksString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeMdParamsIncludeLinksString string + +const ( + WebWebScrapeMdParamsIncludeLinksStringTrue WebWebScrapeMdParamsIncludeLinksString = "true" + WebWebScrapeMdParamsIncludeLinksStringFalse WebWebScrapeMdParamsIncludeLinksString = "false" +) + // PDF parsing controls. Use start/end to limit text extraction and embedded-image // detection/OCR to an inclusive 1-based page range. type WebWebScrapeMdParamsPdf struct { // 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 param.Opt[int64] `query:"end,omitzero" json:"-"` + // First 1-based PDF page to parse. When omitted, parsing starts at the first page. + Start param.Opt[int64] `query:"start,omitzero" json:"-"` // When true, detect and OCR images embedded in the selected PDF pages, inserting // recognized text at each image's position in page reading order while preserving // the PDF text layer. This is separate from automatic scanned-PDF OCR fallback. - Ocr param.Opt[bool] `query:"ocr,omitzero" json:"-"` + Ocr WebWebScrapeMdParamsPdfOcrUnion `query:"ocr,omitzero" json:"-"` // When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and // a 400 WEBSITE_ACCESS_ERROR is returned. - ShouldParse param.Opt[bool] `query:"shouldParse,omitzero" json:"-"` - // First 1-based PDF page to parse. When omitted, parsing starts at the first page. - Start param.Opt[int64] `query:"start,omitzero" json:"-"` + ShouldParse WebWebScrapeMdParamsPdfShouldParseUnion `query:"shouldParse,omitzero" json:"-"` paramObj } @@ -4267,12 +4775,116 @@ func (r WebWebScrapeMdParamsPdf) URLQuery() (v url.Values, err error) { }) } +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeMdParamsPdfOcrUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeMdsPdfOcrString) + OfWebWebScrapeMdsPdfOcrString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeMdParamsPdfOcrString string + +const ( + WebWebScrapeMdParamsPdfOcrStringTrue WebWebScrapeMdParamsPdfOcrString = "true" + WebWebScrapeMdParamsPdfOcrStringFalse WebWebScrapeMdParamsPdfOcrString = "false" +) + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeMdParamsPdfShouldParseUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeMdsPdfShouldParseString) + OfWebWebScrapeMdsPdfShouldParseString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeMdParamsPdfShouldParseString string + +const ( + WebWebScrapeMdParamsPdfShouldParseStringTrue WebWebScrapeMdParamsPdfShouldParseString = "true" + WebWebScrapeMdParamsPdfShouldParseStringFalse WebWebScrapeMdParamsPdfShouldParseString = "false" +) + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeMdParamsSettleAnimationsUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeMdsSettleAnimationsString) + OfWebWebScrapeMdsSettleAnimationsString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeMdParamsSettleAnimationsString string + +const ( + WebWebScrapeMdParamsSettleAnimationsStringTrue WebWebScrapeMdParamsSettleAnimationsString = "true" + WebWebScrapeMdParamsSettleAnimationsStringFalse WebWebScrapeMdParamsSettleAnimationsString = "false" +) + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeMdParamsShortenBase64ImagesUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeMdsShortenBase64ImagesString) + OfWebWebScrapeMdsShortenBase64ImagesString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeMdParamsShortenBase64ImagesString string + +const ( + WebWebScrapeMdParamsShortenBase64ImagesStringTrue WebWebScrapeMdParamsShortenBase64ImagesString = "true" + WebWebScrapeMdParamsShortenBase64ImagesStringFalse WebWebScrapeMdParamsShortenBase64ImagesString = "false" +) + +// Only one field can be non-zero. +// +// Use [param.IsOmitted] to confirm if a field is set. +type WebWebScrapeMdParamsUseMainContentOnlyUnion struct { + OfBool param.Opt[bool] `query:",omitzero,inline"` + // Check if union is this variant with + // !param.IsOmitted(union.OfWebWebScrapeMdsUseMainContentOnlyString) + OfWebWebScrapeMdsUseMainContentOnlyString param.Opt[string] `query:",omitzero,inline"` + paramUnion +} + +type WebWebScrapeMdParamsUseMainContentOnlyString string + +const ( + WebWebScrapeMdParamsUseMainContentOnlyStringTrue WebWebScrapeMdParamsUseMainContentOnlyString = "true" + WebWebScrapeMdParamsUseMainContentOnlyStringFalse WebWebScrapeMdParamsUseMainContentOnlyString = "false" +) + +// 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. +type WebWebScrapeMdParamsZdr string + +const ( + WebWebScrapeMdParamsZdrEnabled WebWebScrapeMdParamsZdr = "enabled" + WebWebScrapeMdParamsZdrDisabled WebWebScrapeMdParamsZdr = "disabled" +) + type WebWebScrapeSitemapParams struct { // Domain to build a sitemap for Domain string `query:"domain" api:"required" json:"-"` // Maximum number of links to return from the sitemap crawl. Defaults to 10,000. // Minimum is 1, maximum is 100,000. MaxLinks param.Opt[int64] `query:"maxLinks,omitzero" json:"-"` + // Optional explicit sitemap URL. When provided, exactly this sitemap is crawled + // instead of discovering the domain's sitemaps. + SitemapURL param.Opt[string] `query:"sitemapUrl,omitzero" format:"uri" json:"-"` // 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). @@ -4284,6 +4896,17 @@ type WebWebScrapeSitemapParams struct { // 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 map[string]string `query:"headers,omitzero" json:"-"` + // 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 []string `query:"tags,omitzero" json:"-"` + // 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. + // + // Any of "enabled", "disabled". + Zdr WebWebScrapeSitemapParamsZdr `query:"zdr,omitzero" json:"-"` paramObj } @@ -4295,3 +4918,14 @@ func (r WebWebScrapeSitemapParams) URLQuery() (v url.Values, err error) { NestedFormat: apiquery.NestedQueryFormatBrackets, }) } + +// 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. +type WebWebScrapeSitemapParamsZdr string + +const ( + WebWebScrapeSitemapParamsZdrEnabled WebWebScrapeSitemapParamsZdr = "enabled" + WebWebScrapeSitemapParamsZdrDisabled WebWebScrapeSitemapParamsZdr = "disabled" +) diff --git a/web_test.go b/web_test.go index 8981173..11779f3 100644 --- a/web_test.go +++ b/web_test.go @@ -46,9 +46,11 @@ func TestWebExtractWithOptionalParams(t *testing.T) { ShouldParse: contextdev.Bool(true), Start: contextdev.Int(1), }, - StopAfterMs: contextdev.Int(10000), - TimeoutMs: contextdev.Int(1000), - WaitForMs: contextdev.Int(0), + SettleAnimations: contextdev.Bool(true), + StopAfterMs: contextdev.Int(10000), + Tags: []string{"production", "team-alpha"}, + TimeoutMs: contextdev.Int(1000), + WaitForMs: contextdev.Int(0), }) if err != nil { var apierr *contextdev.Error @@ -75,6 +77,7 @@ func TestWebExtractCompetitorsWithOptionalParams(t *testing.T) { _, err := client.Web.ExtractCompetitors(context.TODO(), contextdev.WebExtractCompetitorsParams{ Domain: "xxx", NumCompetitors: contextdev.Int(1), + Tags: []string{"production", "team-alpha"}, TimeoutMs: contextdev.Int(1000), }) if err != nil { @@ -101,8 +104,9 @@ func TestWebExtractFontsWithOptionalParams(t *testing.T) { ) _, err := client.Web.ExtractFonts(context.TODO(), contextdev.WebExtractFontsParams{ DirectURL: contextdev.String("https://example.com"), - Domain: contextdev.String("domain"), - MaxAgeMs: contextdev.Int(86400000), + Domain: contextdev.String("xxx"), + MaxAgeMs: contextdev.Int(0), + Tags: []string{"production", "team-alpha"}, TimeoutMs: contextdev.Int(1000), }) if err != nil { @@ -130,8 +134,9 @@ func TestWebExtractStyleguideWithOptionalParams(t *testing.T) { _, err := client.Web.ExtractStyleguide(context.TODO(), contextdev.WebExtractStyleguideParams{ ColorScheme: contextdev.WebExtractStyleguideParamsColorSchemeLight, DirectURL: contextdev.String("https://example.com"), - Domain: contextdev.String("domain"), - MaxAgeMs: contextdev.Int(86400000), + Domain: contextdev.String("xxx"), + MaxAgeMs: contextdev.Int(0), + Tags: []string{"production", "team-alpha"}, TimeoutMs: contextdev.Int(1000), }) if err != nil { @@ -157,21 +162,25 @@ func TestWebScreenshotWithOptionalParams(t *testing.T) { option.WithAPIKey("My API Key"), ) _, err := client.Web.Screenshot(context.TODO(), contextdev.WebScreenshotParams{ - ColorScheme: contextdev.WebScreenshotParamsColorSchemeLight, - Country: contextdev.WebScreenshotParamsCountryDe, - DirectURL: contextdev.String("https://example.com"), - Domain: contextdev.String("domain"), - FullScreenshot: contextdev.WebScreenshotParamsFullScreenshotTrue, - HandleCookiePopup: contextdev.WebScreenshotParamsHandleCookiePopupTrue, - MaxAgeMs: contextdev.Int(0), - Page: contextdev.WebScreenshotParamsPageLogin, - ScrollOffset: contextdev.Int(0), - TimeoutMs: contextdev.Int(1000), + ColorScheme: contextdev.WebScreenshotParamsColorSchemeLight, + Country: contextdev.WebScreenshotParamsCountryDe, + DirectURL: contextdev.String("https://example.com"), + Domain: contextdev.String("xxx"), + FullScreenshot: contextdev.WebScreenshotParamsFullScreenshotTrue, + HandleCookiePopup: contextdev.WebScreenshotParamsHandleCookiePopupUnion{ + OfWebScreenshotsHandleCookiePopupString: contextdev.String("true"), + }, + MaxAgeMs: contextdev.Int(0), + Page: contextdev.WebScreenshotParamsPageLogin, + ScrollOffset: contextdev.Int(0), + Tags: []string{"production", "team-alpha"}, + TimeoutMs: contextdev.Int(1), Viewport: contextdev.WebScreenshotParamsViewport{ Height: contextdev.Int(240), Width: contextdev.Int(240), }, WaitForMs: contextdev.Int(0), + Zdr: contextdev.WebScreenshotParamsZdrEnabled, }) if err != nil { var apierr *contextdev.Error @@ -219,6 +228,7 @@ func TestWebSearchWithOptionalParams(t *testing.T) { }, NumResults: contextdev.Int(10), QueryFanout: contextdev.Bool(true), + Tags: []string{"production", "team-alpha"}, TimeoutMs: contextdev.Int(1000), }) if err != nil { @@ -264,10 +274,12 @@ func TestWebWebCrawlMdWithOptionalParams(t *testing.T) { SettleAnimations: contextdev.Bool(true), ShortenBase64Images: contextdev.Bool(true), StopAfterMs: contextdev.Int(10000), + Tags: []string{"production", "team-alpha"}, TimeoutMs: contextdev.Int(1000), URLRegex: contextdev.String("^https?://[^/]+/blog/"), UseMainContentOnly: contextdev.Bool(true), WaitForMs: contextdev.Int(0), + Zdr: contextdev.WebWebCrawlMdParamsZdrEnabled, }) if err != nil { var apierr *contextdev.Error @@ -292,25 +304,42 @@ func TestWebWebScrapeHTMLWithOptionalParams(t *testing.T) { option.WithAPIKey("My API Key"), ) _, err := client.Web.WebScrapeHTML(context.TODO(), contextdev.WebWebScrapeHTMLParams{ - URL: "https://example.com", + URL: "https://example.com", + Actions: []contextdev.WebWebScrapeHTMLParamsActionUnion{{ + OfWait: &contextdev.WebWebScrapeHTMLParamsActionWait{ + TimeMs: 0, + }, + }}, Country: contextdev.WebWebScrapeHTMLParamsCountryDe, - ExcludeSelectors: []string{"string"}, + ExcludeSelectors: []string{"x"}, Headers: map[string]string{ "foo": "J!", }, - IncludeFrames: contextdev.Bool(true), - IncludeSelectors: []string{"string"}, + IncludeFrames: contextdev.WebWebScrapeHTMLParamsIncludeFramesUnion{ + OfWebWebScrapeHTMLsIncludeFramesString: contextdev.String("true"), + }, + IncludeSelectors: []string{"x"}, MaxAgeMs: contextdev.Int(0), Pdf: contextdev.WebWebScrapeHTMLParamsPdf{ - End: contextdev.Int(1), - Ocr: contextdev.Bool(true), - ShouldParse: contextdev.Bool(true), - Start: contextdev.Int(1), + End: contextdev.Int(1), + Ocr: contextdev.WebWebScrapeHTMLParamsPdfOcrUnion{ + OfWebWebScrapeHTMLsPdfOcrString: contextdev.String("true"), + }, + ShouldParse: contextdev.WebWebScrapeHTMLParamsPdfShouldParseUnion{ + OfWebWebScrapeHTMLsPdfShouldParseString: contextdev.String("true"), + }, + Start: contextdev.Int(1), + }, + SettleAnimations: contextdev.WebWebScrapeHTMLParamsSettleAnimationsUnion{ + OfWebWebScrapeHTMLsSettleAnimationsString: contextdev.String("true"), }, - SettleAnimations: contextdev.Bool(true), - TimeoutMs: contextdev.Int(1000), - UseMainContentOnly: contextdev.Bool(true), - WaitForMs: contextdev.Int(0), + Tags: []string{"production", "team-alpha"}, + TimeoutMs: contextdev.Int(1), + UseMainContentOnly: contextdev.WebWebScrapeHTMLParamsUseMainContentOnlyUnion{ + OfWebWebScrapeHTMLsUseMainContentOnlyString: contextdev.String("true"), + }, + WaitForMs: contextdev.Int(0), + Zdr: contextdev.WebWebScrapeHTMLParamsZdrEnabled, }) if err != nil { var apierr *contextdev.Error @@ -335,19 +364,33 @@ func TestWebWebScrapeImagesWithOptionalParams(t *testing.T) { option.WithAPIKey("My API Key"), ) _, err := client.Web.WebScrapeImages(context.TODO(), contextdev.WebWebScrapeImagesParams{ - URL: "https://example.com", - Dedupe: contextdev.Bool(true), + URL: "https://example.com", + Actions: []contextdev.WebWebScrapeImagesParamsActionUnion{{ + OfWait: &contextdev.WebWebScrapeImagesParamsActionWait{ + TimeMs: 0, + }, + }}, + Dedupe: contextdev.WebWebScrapeImagesParamsDedupeUnion{ + OfWebWebScrapeImagessDedupeString: contextdev.String("true"), + }, Enrichment: contextdev.WebWebScrapeImagesParamsEnrichment{ - Classification: contextdev.Bool(true), - HostedURL: contextdev.Bool(true), - MaxTimePerMs: contextdev.Int(1), - Resolution: contextdev.Bool(true), + Classification: contextdev.WebWebScrapeImagesParamsEnrichmentClassificationUnion{ + OfWebWebScrapeImagessEnrichmentClassificationString: contextdev.String("true"), + }, + HostedURL: contextdev.WebWebScrapeImagesParamsEnrichmentHostedURLUnion{ + OfWebWebScrapeImagessEnrichmentHostedURLString: contextdev.String("true"), + }, + MaxTimePerMs: contextdev.Int(1), + Resolution: contextdev.WebWebScrapeImagesParamsEnrichmentResolutionUnion{ + OfWebWebScrapeImagessEnrichmentResolutionString: contextdev.String("true"), + }, }, Headers: map[string]string{ "foo": "J!", }, MaxAgeMs: contextdev.Int(0), - TimeoutMs: contextdev.Int(1000), + Tags: []string{"production", "team-alpha"}, + TimeoutMs: contextdev.Int(1), WaitForMs: contextdev.Int(0), }) if err != nil { @@ -373,28 +416,51 @@ func TestWebWebScrapeMdWithOptionalParams(t *testing.T) { option.WithAPIKey("My API Key"), ) _, err := client.Web.WebScrapeMd(context.TODO(), contextdev.WebWebScrapeMdParams{ - URL: "https://example.com", + URL: "https://example.com", + Actions: []contextdev.WebWebScrapeMdParamsActionUnion{{ + OfWait: &contextdev.WebWebScrapeMdParamsActionWait{ + TimeMs: 0, + }, + }}, Country: contextdev.WebWebScrapeMdParamsCountryDe, - ExcludeSelectors: []string{"string"}, + ExcludeSelectors: []string{"x"}, Headers: map[string]string{ "foo": "J!", }, - IncludeFrames: contextdev.Bool(true), - IncludeImages: contextdev.Bool(true), - IncludeLinks: contextdev.Bool(true), - IncludeSelectors: []string{"string"}, + IncludeFrames: contextdev.WebWebScrapeMdParamsIncludeFramesUnion{ + OfWebWebScrapeMdsIncludeFramesString: contextdev.String("true"), + }, + IncludeImages: contextdev.WebWebScrapeMdParamsIncludeImagesUnion{ + OfWebWebScrapeMdsIncludeImagesString: contextdev.String("true"), + }, + IncludeLinks: contextdev.WebWebScrapeMdParamsIncludeLinksUnion{ + OfWebWebScrapeMdsIncludeLinksString: contextdev.String("true"), + }, + IncludeSelectors: []string{"x"}, MaxAgeMs: contextdev.Int(0), Pdf: contextdev.WebWebScrapeMdParamsPdf{ - End: contextdev.Int(1), - Ocr: contextdev.Bool(true), - ShouldParse: contextdev.Bool(true), - Start: contextdev.Int(1), + End: contextdev.Int(1), + Ocr: contextdev.WebWebScrapeMdParamsPdfOcrUnion{ + OfWebWebScrapeMdsPdfOcrString: contextdev.String("true"), + }, + ShouldParse: contextdev.WebWebScrapeMdParamsPdfShouldParseUnion{ + OfWebWebScrapeMdsPdfShouldParseString: contextdev.String("true"), + }, + Start: contextdev.Int(1), }, - SettleAnimations: contextdev.Bool(true), - ShortenBase64Images: contextdev.Bool(true), - TimeoutMs: contextdev.Int(1000), - UseMainContentOnly: contextdev.Bool(true), - WaitForMs: contextdev.Int(0), + SettleAnimations: contextdev.WebWebScrapeMdParamsSettleAnimationsUnion{ + OfWebWebScrapeMdsSettleAnimationsString: contextdev.String("true"), + }, + ShortenBase64Images: contextdev.WebWebScrapeMdParamsShortenBase64ImagesUnion{ + OfWebWebScrapeMdsShortenBase64ImagesString: contextdev.String("true"), + }, + Tags: []string{"production", "team-alpha"}, + TimeoutMs: contextdev.Int(1), + UseMainContentOnly: contextdev.WebWebScrapeMdParamsUseMainContentOnlyUnion{ + OfWebWebScrapeMdsUseMainContentOnlyString: contextdev.String("true"), + }, + WaitForMs: contextdev.Int(0), + Zdr: contextdev.WebWebScrapeMdParamsZdrEnabled, }) if err != nil { var apierr *contextdev.Error @@ -419,13 +485,16 @@ func TestWebWebScrapeSitemapWithOptionalParams(t *testing.T) { option.WithAPIKey("My API Key"), ) _, err := client.Web.WebScrapeSitemap(context.TODO(), contextdev.WebWebScrapeSitemapParams{ - Domain: "domain", + Domain: "xxx", Headers: map[string]string{ "foo": "J!", }, - MaxLinks: contextdev.Int(1), - TimeoutMs: contextdev.Int(1000), - URLRegex: contextdev.String("^https?://[^/]+/blog/"), + MaxLinks: contextdev.Int(1), + SitemapURL: contextdev.String("https://example.com"), + Tags: []string{"production", "team-alpha"}, + TimeoutMs: contextdev.Int(1), + URLRegex: contextdev.String("^https?://[^/]+/blog/"), + Zdr: contextdev.WebWebScrapeSitemapParamsZdrEnabled, }) if err != nil { var apierr *contextdev.Error