industry.go

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

package contextdev

import (
	"context"
	"net/http"
	"net/url"
	"slices"

	"github.com/context-dot-dev/context-go-sdk/v2/internal/apijson"
	"github.com/context-dot-dev/context-go-sdk/v2/internal/apiquery"
	"github.com/context-dot-dev/context-go-sdk/v2/internal/requestconfig"
	"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"
)

// IndustryService contains methods and other services that help with interacting
// with the context.dev API.
//
// Note, unlike clients, this service does not read variables from the environment
// automatically. You should not instantiate this service directly, and instead use
// the [NewIndustryService] method instead.
type IndustryService struct {
	options []option.RequestOption
}

// NewIndustryService generates a new service that applies the given options to
// each request. These options are applied after the parent client's options (if
// there is one), and before any request-specific options.
func NewIndustryService(opts ...option.RequestOption) (r IndustryService) {
	r = IndustryService{}
	r.options = opts
	return
}

// Classify a company into NAICS industry codes.
func (r *IndustryService) GetNaics(ctx context.Context, query IndustryGetNaicsParams, opts ...option.RequestOption) (res *IndustryGetNaicsResponse, err error) {
	opts = slices.Concat(r.options, opts)
	path := "web/naics"
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, query, &res, opts...)
	return res, err
}

// Classify a company into SIC industry codes.
func (r *IndustryService) GetSic(ctx context.Context, query IndustryGetSicParams, opts ...option.RequestOption) (res *IndustryGetSicResponse, err error) {
	opts = slices.Concat(r.options, opts)
	path := "web/sic"
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, query, &res, opts...)
	return res, err
}

type IndustryGetNaicsResponse struct {
	// Unique ID of this request, also in `X-Request-Id`. Include it when contacting
	// support.
	RequestID string `json:"request_id" api:"required" format:"uuid"`
	// Array of NAICS codes and titles.
	Codes []IndustryGetNaicsResponseCode `json:"codes"`
	// Domain found for the brand
	Domain string `json:"domain"`
	// Credits this request used and your remaining balance.
	KeyMetadata IndustryGetNaicsResponseKeyMetadata `json:"key_metadata"`
	// True when the timeout ended processing and this response contains only usable
	// results completed so far. Unfinished results are omitted.
	Partial bool `json:"partial"`
	// Always `ok` on success.
	Status string `json:"status"`
	// Industry classification type, for naics api it will be `naics`
	Type string `json:"type"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		RequestID   respjson.Field
		Codes       respjson.Field
		Domain      respjson.Field
		KeyMetadata respjson.Field
		Partial     respjson.Field
		Status      respjson.Field
		Type        respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r IndustryGetNaicsResponse) RawJSON() string { return r.JSON.raw }
func (r *IndustryGetNaicsResponse) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type IndustryGetNaicsResponseCode struct {
	// NAICS code
	Code string `json:"code" api:"required"`
	// Confidence level for how well this NAICS code matches the company description
	//
	// Any of "high", "medium", "low".
	Confidence string `json:"confidence" api:"required"`
	// NAICS title
	Name string `json:"name" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Code        respjson.Field
		Confidence  respjson.Field
		Name        respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r IndustryGetNaicsResponseCode) RawJSON() string { return r.JSON.raw }
func (r *IndustryGetNaicsResponseCode) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// Credits this request used and your remaining balance.
type IndustryGetNaicsResponseKeyMetadata struct {
	// Credits charged for this request.
	CreditsConsumed int64 `json:"credits_consumed" api:"required"`
	// Credits remaining for your organization.
	CreditsRemaining int64 `json:"credits_remaining" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		CreditsConsumed  respjson.Field
		CreditsRemaining respjson.Field
		ExtraFields      map[string]respjson.Field
		raw              string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r IndustryGetNaicsResponseKeyMetadata) RawJSON() string { return r.JSON.raw }
func (r *IndustryGetNaicsResponseKeyMetadata) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type IndustryGetSicResponse struct {
	// Unique ID of this request, also in `X-Request-Id`. Include it when contacting
	// support.
	RequestID string `json:"request_id" api:"required" format:"uuid"`
	// Echoes back which SIC dataset was used to classify the brand.
	//
	// Any of "original_sic", "latest_sec".
	Classification IndustryGetSicResponseClassification `json:"classification"`
	// Array of SIC codes with confidence scores. Extra fields depend on the requested
	// classification: `original_sic` results include `majorGroup` and
	// `majorGroupName`; `latest_sec` results include `office`.
	Codes []IndustryGetSicResponseCode `json:"codes"`
	// Domain found for the brand
	Domain string `json:"domain"`
	// Credits this request used and your remaining balance.
	KeyMetadata IndustryGetSicResponseKeyMetadata `json:"key_metadata"`
	// True when the timeout ended processing and this response contains only usable
	// results completed so far. Unfinished results are omitted.
	Partial bool `json:"partial"`
	// Always `ok` on success.
	Status string `json:"status"`
	// Industry classification type, for sic api it will be `sic`
	Type string `json:"type"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		RequestID      respjson.Field
		Classification respjson.Field
		Codes          respjson.Field
		Domain         respjson.Field
		KeyMetadata    respjson.Field
		Partial        respjson.Field
		Status         respjson.Field
		Type           respjson.Field
		ExtraFields    map[string]respjson.Field
		raw            string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r IndustryGetSicResponse) RawJSON() string { return r.JSON.raw }
func (r *IndustryGetSicResponse) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// Echoes back which SIC dataset was used to classify the brand.
type IndustryGetSicResponseClassification string

const (
	IndustryGetSicResponseClassificationOriginalSic IndustryGetSicResponseClassification = "original_sic"
	IndustryGetSicResponseClassificationLatestSec   IndustryGetSicResponseClassification = "latest_sec"
)

type IndustryGetSicResponseCode struct {
	// SIC code (4-digit).
	Code string `json:"code" api:"required"`
	// Confidence level for how well this SIC code matches the company description.
	//
	// Any of "high", "medium", "low".
	Confidence string `json:"confidence" api:"required"`
	// SIC industry title.
	Name string `json:"name" api:"required"`
	// 2-digit major group identifier (the leading two digits of the code). Only
	// present when `classification` is `original_sic`.
	MajorGroup string `json:"majorGroup"`
	// Description of the 2-digit major group. Only present when `classification` is
	// `original_sic`.
	MajorGroupName string `json:"majorGroupName"`
	// SEC review office responsible for filings under this code. Only present when
	// `classification` is `latest_sec`.
	Office string `json:"office"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Code           respjson.Field
		Confidence     respjson.Field
		Name           respjson.Field
		MajorGroup     respjson.Field
		MajorGroupName respjson.Field
		Office         respjson.Field
		ExtraFields    map[string]respjson.Field
		raw            string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r IndustryGetSicResponseCode) RawJSON() string { return r.JSON.raw }
func (r *IndustryGetSicResponseCode) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// Credits this request used and your remaining balance.
type IndustryGetSicResponseKeyMetadata struct {
	// Credits charged for this request.
	CreditsConsumed int64 `json:"credits_consumed" api:"required"`
	// Credits remaining for your organization.
	CreditsRemaining int64 `json:"credits_remaining" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		CreditsConsumed  respjson.Field
		CreditsRemaining respjson.Field
		ExtraFields      map[string]respjson.Field
		raw              string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r IndustryGetSicResponseKeyMetadata) RawJSON() string { return r.JSON.raw }
func (r *IndustryGetSicResponseKeyMetadata) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type IndustryGetNaicsParams struct {
	// Brand domain or title to retrieve NAICS code for. If a valid domain is provided,
	// it will be used for classification, otherwise, we will search for the brand
	// using the provided title.
	Input string `query:"input" api:"required" json:"-"`
	// Maximum number of NAICS codes to return. Must be between 1 and 10. Defaults
	// to 5.
	MaxResults param.Opt[int64] `query:"maxResults,omitzero" json:"-"`
	// Minimum number of NAICS codes to return. Must be at least 1. Defaults to 1.
	MinResults param.Opt[int64] `query:"minResults,omitzero" json:"-"`
	// Comma-separated labels for filtering usage, e.g. `production,team-alpha`.
	Tags []string `query:"tags,omitzero" json:"-"`
	// Request deadline and what to return when it passes.
	TimeoutOpts IndustryGetNaicsParamsTimeoutOpts `query:"timeoutOpts,omitzero" json:"-"`
	// `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless
	// your organization has ZDR.
	//
	// Any of "enabled", "disabled".
	Zdr IndustryGetNaicsParamsZdr `query:"zdr,omitzero" json:"-"`
	paramObj
}

// URLQuery serializes [IndustryGetNaicsParams]'s query parameters as `url.Values`.
func (r IndustryGetNaicsParams) URLQuery() (v url.Values, err error) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatBrackets,
	})
}

// Request deadline and what to return when it passes.
//
// The property Milliseconds is required.
type IndustryGetNaicsParamsTimeoutOpts struct {
	// Deadline in milliseconds.
	Milliseconds int64 `query:"milliseconds" api:"required" json:"-"`
	// "fail" returns 408 at the deadline. "return-partial" returns available results;
	// inspect the response’s partial flag.
	//
	// Any of "fail", "return-partial".
	Behavior string `query:"behavior,omitzero" json:"-"`
	paramObj
}

// URLQuery serializes [IndustryGetNaicsParamsTimeoutOpts]'s query parameters as
// `url.Values`.
func (r IndustryGetNaicsParamsTimeoutOpts) URLQuery() (v url.Values, err error) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatBrackets,
	})
}

// `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless
// your organization has ZDR.
type IndustryGetNaicsParamsZdr string

const (
	IndustryGetNaicsParamsZdrEnabled  IndustryGetNaicsParamsZdr = "enabled"
	IndustryGetNaicsParamsZdrDisabled IndustryGetNaicsParamsZdr = "disabled"
)

type IndustryGetSicParams struct {
	// Brand domain or title to retrieve SIC code for. If a valid domain is provided,
	// it will be used for classification, otherwise, we will search for the brand
	// using the provided title.
	Input string `query:"input" api:"required" json:"-"`
	// Maximum number of SIC codes to return. Must be between 1 and 10. Defaults to 5.
	MaxResults param.Opt[int64] `query:"maxResults,omitzero" json:"-"`
	// Minimum number of SIC codes to return. Must be at least 1. Defaults to 1.
	MinResults param.Opt[int64] `query:"minResults,omitzero" json:"-"`
	// Comma-separated labels for filtering usage, e.g. `production,team-alpha`.
	Tags []string `query:"tags,omitzero" json:"-"`
	// Request deadline and what to return when it passes.
	TimeoutOpts IndustryGetSicParamsTimeoutOpts `query:"timeoutOpts,omitzero" json:"-"`
	// SIC dataset: `original_sic` (1987) or `latest_sec` (current SEC list).
	//
	// Any of "original_sic", "latest_sec".
	Type IndustryGetSicParamsType `query:"type,omitzero" json:"-"`
	// `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless
	// your organization has ZDR.
	//
	// Any of "enabled", "disabled".
	Zdr IndustryGetSicParamsZdr `query:"zdr,omitzero" json:"-"`
	paramObj
}

// URLQuery serializes [IndustryGetSicParams]'s query parameters as `url.Values`.
func (r IndustryGetSicParams) URLQuery() (v url.Values, err error) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatBrackets,
	})
}

// Request deadline and what to return when it passes.
//
// The property Milliseconds is required.
type IndustryGetSicParamsTimeoutOpts struct {
	// Deadline in milliseconds.
	Milliseconds int64 `query:"milliseconds" api:"required" json:"-"`
	// "fail" returns 408 at the deadline. "return-partial" returns available results;
	// inspect the response’s partial flag.
	//
	// Any of "fail", "return-partial".
	Behavior string `query:"behavior,omitzero" json:"-"`
	paramObj
}

// URLQuery serializes [IndustryGetSicParamsTimeoutOpts]'s query parameters as
// `url.Values`.
func (r IndustryGetSicParamsTimeoutOpts) URLQuery() (v url.Values, err error) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatBrackets,
	})
}

// SIC dataset: `original_sic` (1987) or `latest_sec` (current SEC list).
type IndustryGetSicParamsType string

const (
	IndustryGetSicParamsTypeOriginalSic IndustryGetSicParamsType = "original_sic"
	IndustryGetSicParamsTypeLatestSec   IndustryGetSicParamsType = "latest_sec"
)

// `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless
// your organization has ZDR.
type IndustryGetSicParamsZdr string

const (
	IndustryGetSicParamsZdrEnabled  IndustryGetSicParamsZdr = "enabled"
	IndustryGetSicParamsZdrDisabled IndustryGetSicParamsZdr = "disabled"
)