tax

type AddonDef struct {
	// Key that defines how to uniquely idenitfy the add-on.
	Key cbc.Key `json:"key" jsonschema:"title=Key"`

	// Requires defines any additional addons that this one depends on to operate
	// correctly.
	Requires []cbc.Key `json:"requires,omitempty" jsonschema:"title=Requires"`

	// Name of the add-on
	Name i18n.String `json:"name" jsonschema:"title=Name"`

	// Description of the add-on
	Description i18n.String `json:"description,omitempty" jsonschema:"title=Description"`

	// Sources is a list of sources that are used to provide the data for the add-on.
	Sources []*cbc.Source `json:"sources,omitempty" jsonschema:"title=Sources"`

	// Extensions defines the list of extensions that are associated with an add-on.
	Extensions []*cbc.Definition `json:"extensions" jsonschema:"title=Extensions"`

	// Tags is slice of tag sets that define what can be assigned to each document schema.
	Tags []*TagSet `json:"tags,omitempty" jsonschema:"title=Tags"`

	// Scenarios are applied to documents after normalization and before
	// validation to ensure that form specific extensions have been added
	// to the document.
	Scenarios []*ScenarioSet `json:"scenarios" jsonschema:"title=Scenarios"`

	// Identities that are specific for the add-on and may be validated against or
	// used during conversion processes.
	Identities []*cbc.Definition `json:"identities,omitempty" jsonschema:"title=Identities"`

	// Inboxes is a list of keys that are used to identify where copies of
	// documents can be sent.
	Inboxes []*cbc.Definition `json:"inboxes,omitempty" jsonschema:"title=Inboxes"`

	// Normalizer performs the normalization rules for the add-on.
	Normalizer func(doc any) `json:"-"`

	// Validator performs the validation rules for the add-on.
	Validator func(doc any) error `json:"-"`

	// Corrections is used to provide a map of correction definitions that
	// are supported by the add-on.
	Corrections CorrectionSet `json:"corrections" jsonschema:"title=Corrections"`
}

type AddonList []cbc.Key

type Addons struct {
	// Addons defines a list of keys used to identify tax addons that apply special
	// normalization, scenarios, and validation rules to a document.
	List AddonList `json:"$addons,omitempty" jsonschema:"title=Addons"`
}

type CatalogueDef struct {
	// Key defines a unique identifier for the catalogue.
	Key cbc.Key `json:"key"`
	// Name is the name of the catalogue.
	Name i18n.String `json:"name"`
	// Description is a human readable description of the catalogue.
	Description i18n.String `json:"description,omitempty"`
	// Extensions defines all the extensions offered by the catalogue.
	Extensions []*cbc.Definition `json:"extensions"`
}

type CategoryDef struct {
	// Code to be used in documents
	Code cbc.Code `json:"code" jsonschema:"title=Code"`

	// Short name of the category to be used instead of code in output
	Name i18n.String `json:"name" jsonschema:"title=Name"`

	// Human name for the code to use for titles
	Title i18n.String `json:"title,omitempty" jsonschema:"title=Title"`

	// Useful description of the category.
	Description *i18n.String `json:"desc,omitempty" jsonschema:"title=Description"`

	// Retained when true implies that the tax amount will be retained
	// by the buyer on behalf of the supplier, and thus subtracted from
	// the invoice taxable base total. Typically used for taxes related to
	// income.
	Retained bool `json:"retained,omitempty" jsonschema:"title=Retained"`

	// Informative when true implies that the tax amount will be calculated
	// and reported but will not affect the invoice totals. Typically used
	// for taxes that are embedded in the base amount or don't impact the
	// final payable amount.
	Informative bool `json:"informative,omitempty" jsonschema:"title=Informative"`

	// Specific tax definitions inside this category.
	Keys []*KeyDef `json:"keys,omitempty" jsonschema:"title=Keys"`

	// Rates defines the set of rates that can be used with this category.
	Rates []*RateDef `json:"rates,omitempty" jsonschema:"title=Rates"`

	// Extensions defines a list of extension keys that may be used or required
	// as an alternative or alongside choosing a rate for the tax category.
	// Every key must be defined in the Regime's extensions table.
	Extensions []cbc.Key `json:"extensions,omitempty" jsonschema:"title=Extensions"`

	// Map defines a set of regime specific code mappings.
	Map cbc.CodeMap `json:"map,omitempty" jsonschema:"title=Map"`

	// List of sources for the information contained in this category and most importantly,
	// an official source where the tax rates can be reviewed and updated in the future.
	Sources []*cbc.Source `json:"sources,omitempty" jsonschema:"title=Sources"`

	// Extension key-value pairs that will be copied to the tax combo if this
	// category is used.
	Ext Extensions `json:"ext,omitempty" jsonschema:"title=Extensions"`

	// Meta contains additional information about the category that is relevant
	// for local frequently used formats.
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Meta"`
}

type CategoryTotal struct {
	Code        cbc.Code     `json:"code" jsonschema:"title=Code"`
	Retained    bool         `json:"retained,omitempty" jsonschema:"title=Retained"`
	Informative bool         `json:"informative,omitempty" jsonschema:"title=Informative"`
	Rates       []*RateTotal `json:"rates" jsonschema:"title=Rates"`
	Amount      num.Amount   `json:"amount" jsonschema:"title=Amount"`
	Surcharge   *num.Amount  `json:"surcharge,omitempty" jsonschema:"title=Surcharge"`
}

type Combo struct {
	// Tax category code from those available inside a region.
	Category cbc.Code `json:"cat" jsonschema:"title=Category"`
	// Country code override when issuing with taxes applied from different countries.
	Country l10n.TaxCountryCode `json:"country,omitempty" jsonschema:"title=Country"`
	// Key helps determine the tax situation within the category.
	Key cbc.Key `json:"key,omitempty"`
	// Rate within a category and for a given key to apply.
	Rate cbc.Key `json:"rate,omitempty" jsonschema:"title=Rate"`
	// Percent defines the percentage set manually or determined from the
	// key. A nil percent implies that this tax combo is either exempt or not-subject.
	Percent *num.Percentage `json:"percent,omitempty" jsonschema:"title=Percent" jsonschema_extras:"calculated=true"`
	// Some countries require an additional surcharge (may be determined if key present).
	Surcharge *num.Percentage `json:"surcharge,omitempty" jsonschema:"title=Surcharge" jsonschema_extras:"calculated=true"`
	// Local codes that apply for a given rate or percentage that need to be identified and validated.
	Ext Extensions `json:"ext,omitempty" jsonschema:"title=Extensions"`
	// contains filtered or unexported fields
}

type CorrectionDefinition struct {
	// Partial or complete schema URL for the document type supported by correction.
	Schema string `json:"schema" jsonschema:"title=Schema"`
	// The types of sub-documents supported by the regime
	Types []cbc.Key `json:"types,omitempty" jsonschema:"title=Types"`
	// Extension keys that can be included
	Extensions []cbc.Key `json:"extensions,omitempty" jsonschema:"title=Extensions"`
	// ReasonRequired when true implies that a reason must be provided
	ReasonRequired bool `json:"reason_required,omitempty" jsonschema:"title=Reason Required"`
	// Stamps that must be copied from the preceding document.
	Stamps []cbc.Key `json:"stamps,omitempty" jsonschema:"title=Stamps"`
	// Copy tax from the preceding document to the document ref.
	CopyTax bool `json:"copy_tax,omitempty" jsonschema:"title=Copy Tax Totals"`
}

type CorrectionSet []*CorrectionDefinition

type Error cbc.Key

type Extensions map[cbc.Key]cbc.Code

type Identity struct {
	// Tax country code for Where the tax identity was issued.
	Country l10n.TaxCountryCode `json:"country" jsonschema:"title=Country Code"`

	// Normalized code shown on the original identity document.
	Code cbc.Code `json:"code,omitempty" jsonschema:"title=Code"`

	// Scheme is an optional field that may be used to override the tax regime's
	// default tax scheme. Many electronic formats such as UBL or CII define an
	// equivalent field. Examples: `VAT`, `GST`, `ST`, etc.
	Scheme cbc.Code `json:"scheme,omitempty" jsonschema:"title=Scheme"`

	// Type is set according to the requirements of each regime, some have a single
	// tax document type code, others require a choice to be made.
	//
	// Deprecated: Tax Identities should only be used for VAT or similar codes
	// for companies. Use the identities array for other types of identification.
	Type cbc.Key `json:"type,omitempty" jsonschema:"title=Type"`

	// Zone identifies a sub-locality within a country.
	//
	// Deprecated: Removed 2024-03-14 in favour of using tax tags
	// and extensions with local data when required. Maintained here to support
	// data migration.
	Zone l10n.Code `json:"zone,omitempty" jsonschema:"title=Zone"`
}

type KeyDef struct {
	// Key identifies this rate within the system
	Key cbc.Key `json:"key,omitempty" jsonschema:"title=Key"`

	// Human name of the rate set
	Name i18n.String `json:"name,omitempty" jsonschema:"title=Name"`
	// Useful description of the rate.
	Description i18n.String `json:"desc,omitempty" jsonschema:"title=Description"`

	// NoPercent when true implies that the rate when used in a tax Combo should
	// not define a percent value.
	NoPercent bool `json:"no_percent,omitempty" jsonschema:"title=No Percent"`
}

type Normalizer func(doc any)

type Normalizers []Normalizer

type Note struct {
	// Tax category code from those available inside a region.
	Category cbc.Code `json:"cat,omitempty" jsonschema:"title=Category"`
	// Key usually identifies the tax rate key this note applies to (e.g. "exempt",
	// "reverse-charge"), but may also be used for other identifiers depending on context.
	Key cbc.Key `json:"key,omitempty" jsonschema:"title=Key"`
	// Text contains the exemption reason or explanation.
	Text string `json:"text" jsonschema:"title=Text"`
	// Extensions for additional structured data.
	Ext Extensions `json:"ext,omitempty" jsonschema:"title=Extensions"`
}

type RateDef struct {
	// Rate defines the key for which this rate applies.
	Rate cbc.Key `json:"rate" jsonschema:"title=Rate"`

	// Keys identifies the set of tax keys defined in the category that this
	// rate can be used with.
	Keys []cbc.Key `json:"keys,omitempty" jsonschema:"title=Keys"`

	// Human name of the rate
	Name i18n.String `json:"name" jsonschema:"title=Name"`
	// Useful description of the rate.
	Description i18n.String `json:"desc,omitempty" jsonschema:"title=Description"`

	// Values contains a list of Value objects that contain the
	// current and historical percentage values for the rate and
	// additional filters.
	// Order is important, newer values should come before
	// older values.
	Values []*RateValueDef `json:"values,omitempty" jsonschema:"title=Values"`

	// Meta contains additional information about the rate that is relevant
	// for local frequently used implementations.
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Meta"`
}

type RateTotal struct {
	// Country code override when issuing with taxes applied from different countries,
	// it'd be very strange to mix rates from different countries, but in theory
	// this would be possible.
	Country l10n.TaxCountryCode `json:"country,omitempty" jsonschema:"title=Country"`
	// Tax key if supported by the category.
	Key cbc.Key `json:"key,omitempty" jsonschema:"title=Key"`
	// If the rate is defined with extensions, they'll be used to group by also.
	Ext Extensions `json:"ext,omitempty" jsonschema:"title=Extensions"`
	// Base amount that the percentage is applied to.
	Base num.Amount `json:"base" jsonschema:"title=Base"`
	// Percentage of the rate. Will be nil when taxes are **exempt**.
	Percent *num.Percentage `json:"percent,omitempty" jsonschema:"title=Percent"`
	// Surcharge applied to the rate.
	Surcharge *RateTotalSurcharge `json:"surcharge,omitempty" jsonschema:"title=Surcharge"`
	// Total amount of rate, excluding surcharges
	Amount num.Amount `json:"amount" jsonschema:"title=Amount"`
}

type RateTotalSurcharge struct {
	Percent num.Percentage `json:"percent" jsonschema:"title=Percent"`
	Amount  num.Amount     `json:"amount" jsonschema:"title=Amount"`
}

type RateValueDef struct {
	// Only apply this rate if one of the tags is present in the invoice.
	// Tags []cbc.Key `json:"tags,omitempty" jsonschema:"title=Tags"`
	// Ext map of keys that can be used to filter to determine if the rate applies.
	Ext Extensions `json:"ext,omitempty" jsonschema:"title=Extensions"`
	// Date from which this value should be applied.
	Since *cal.Date `json:"since,omitempty" jsonschema:"title=Since"`
	// Percent rate that should be applied
	Percent num.Percentage `json:"percent" jsonschema:"title=Percent"`
	// An additional surcharge to apply.
	Surcharge *num.Percentage `json:"surcharge,omitempty" jsonschema:"title=Surcharge"`
	// When true, this value should no longer be used.
	Disabled bool `json:"disabled,omitempty" jsonschema:"title=Disabled"`
}

type Regime struct {
	// Country code that identifies the tax regime applicable to the document.
	// It determines which country-specific tax rules, normalizations, and validations are applied.
	// It may be determined automatically via normalization of a supplier or issuer tax identity
	// country code.
	Country RegimeCode `json:"$regime,omitempty" jsonschema:"title=Tax Regime"`
}

type RegimeCode l10n.TaxCountryCode

type RegimeDef struct {
	// Name of the tax regime.
	Name i18n.String `json:"name" jsonschema:"title=Name"`

	// Introductory details about the regime.
	Description i18n.String `json:"description,omitempty" jsonschema:"title=Description"`

	// Sources is a list of references to tax authority or other relevant documentation that
	// can be used to validate the regime's data and be used in the future to check for updates
	// and changes.
	Sources []*cbc.Source `json:"sources,omitempty" jsonschema:"title=Sources"`

	// Location name for the country's central time zone. Accepted
	// values from IANA Time Zone Database (https://iana.org/time-zones). If a country has multiple
	// time zones, the most common or central one should be used.
	TimeZone string `json:"time_zone" jsonschema:"title=Time Zone"`

	// Country code for tax purposes which usually coincides with the ISO 3166-1 alpha-2 code, but not
	// always.
	Country l10n.TaxCountryCode `json:"country" jsonschema:"title=Code"`

	// Alternative localization codes that may be used to identify the tax regime
	// in specific circumstances.
	AltCountryCodes []l10n.Code `json:"alt_country_codes,omitempty" jsonschema:"title=Alternative Country Codes"`

	// Specific Locality, region, city, province, county, or similar code inside
	// the country, if needed.
	Zone l10n.Code `json:"zone,omitempty" jsonschema:"title=Zone"`

	// Currency used by the country.
	Currency currency.Code `json:"currency" jsonschema:"title=Currency"`

	// TaxScheme defines the principal scheme of consumption tax that should be
	// applied to the regime and associated with Tax IDs in some export formats
	// such as UBL or CII. Some regimes may not have a Tax Scheme and as a
	// consequence will not use tax identities, like the US.
	TaxScheme cbc.Code `json:"tax_scheme,omitempty" jsonschema:"title=Tax Scheme"`

	// Rounding rule to use when calculating the tax totals. See the RoundingRule
	// constants for more details. If not provided, the default is RoundingRulePrecise.
	CalculatorRoundingRule cbc.Key `json:"calculator_rounding_rule,omitempty" jsonschema:"title=Calculator Rounding Rule"`

	// Tags that can be applied at the document level to identify additional
	// considerations.
	Tags []*TagSet `json:"tags,omitempty" jsonschema:"title=Tags"`

	// Extensions defines the keys that can be used for extended or extra data inside the regime that
	// is specific to the regime and cannot be easily determined from other GOBL structures.
	// Typically these are used to define local codes for suppliers, customers, products, or tax rates.
	Extensions []*cbc.Definition `json:"extensions,omitempty" jsonschema:"title=Extensions"`

	// Identities used in addition to regular tax identities and specific for the
	// regime that may be validated against.
	Identities []*cbc.Definition `json:"identities,omitempty" jsonschema:"title=Identities"`

	// PaymentMeansKeys specific for the regime that extend the original
	// base payment means keys.
	PaymentMeansKeys []*cbc.Definition `json:"payment_means_keys,omitempty" jsonschema:"title=Payment Means Keys"`

	// InboxKeys specific to the regime that can be used to identify where a document
	// should be forwarded to.
	InboxKeys []*cbc.Definition `json:"inbox_keys,omitempty" jsonschema:"title=Inbox Keys"`

	// Scenarios are used to describe a specific set of conditions and rules that apply to a specific
	// document schema. These provide a more generic solution for normalization and validation of documents
	// in regimes with specific requirements.
	Scenarios []*ScenarioSet `json:"scenarios,omitempty" jsonschema:"title=Scenarios"`

	// Configuration details for corrections to be used with correction options.
	Corrections CorrectionSet `json:"corrections,omitempty" jsonschema:"title=Corrections"`

	// List of tax categories.
	Categories []*CategoryDef `json:"categories" jsonschema:"title=Categories"`

	// Validator is a method to use to validate a document in a given region.
	Validator Validator `json:"-"`

	// Normalizer is used to perform regime specific normalizations on data,
	// that might need to take place such as with tax codes and removing white-space.
	Normalizer Normalizer `json:"-"`
}

type RegimeDefCollection struct {
	// contains filtered or unexported fields
}

type Scenario struct {
	// Name of the scenario for further information.
	Name i18n.String `json:"name,omitempty" jsonschema:"title=Name"`

	// Description of the scenario for documentation purposes.
	Desc i18n.String `json:"desc,omitempty" jsonschema:"title=Description"`

	// Type of document, if present.
	Types []cbc.Key `json:"type,omitempty" jsonschema:"title=Type"`

	// Array of tags that have been applied to the document.
	Tags []cbc.Key `json:"tags,omitempty" jsonschema:"title=Tags"`

	// Categories is an optional list of tax category codes that acts as a filter.
	// When set, at least one of the specified categories must be present in the
	// document's line taxes for the scenario to match.
	Categories []cbc.Code `json:"cat,omitempty" jsonschema:"title=Tax Categories"`

	// Extension key that must be present in the document.
	ExtKey cbc.Key `json:"ext_key,omitempty" jsonschema:"title=Extension Key"`

	// Extension code that along side the key must be present for a match
	// to happen. This cannot be used without an `cbc.Code`. The value will
	// be copied to the note code if needed.
	ExtCode cbc.Code `json:"ext_code,omitempty" jsonschema:"title=Extension Code"`

	// Filter defines a custom filter method for when the regular basic filters
	// are not sufficient.
	Filter func(doc any) bool `json:"-"`

	// A note to be added to the document if the scenario is applied.
	Note *Note `json:"note,omitempty" jsonschema:"title=Note"`

	// Codes is used to define additional codes for regime specific
	// situations.
	Codes cbc.CodeMap `json:"codes,omitempty" jsonschema:"title=Codes"`

	// Ext represents a set of tax extensions that should be applied to
	// the document in the appropriate "tax" context.
	Ext Extensions `json:"ext,omitempty" jsonschema:"title=Extensions"`
}

type ScenarioDocument interface {
	// GetType returns a type associated with the document.
	GetType() cbc.Key
	// GetTags returns a list of the tags used in the document.
	GetTags() []cbc.Key
	// GetExtensions an array of extensions that used in the document.
	GetExtensions() []Extensions
	// GetTaxCategories returns a list of tax categories used in the document's lines,
	// charges, and discounts.
	GetTaxCategories() []cbc.Code
}

type ScenarioSet struct {
	// Partial or complete schema URL for the document type
	Schema string `json:"schema" jsonschema:"title=Schema"`

	// List of scenarios for the schema
	List []*Scenario `json:"list" jsonschema:"title=List"`
}

type ScenarioSummary struct {
	Notes []*Note
	Codes cbc.CodeMap
	Ext   Extensions
}

type Set []*Combo

type TagSet struct {
	// Schema that the tags are associated with.
	Schema string `json:"schema" jsonschema:"title=Schema"`

	// List of tags for the schema
	List []*cbc.Definition `json:"list" jsonschema:"title=List"`
}

type Tags struct {
	// Tags are used to help identify specific tax scenarios or requirements that may
	// apply changes to the contents of the document or imply a specific meaning.
	// Converters may use tags to help identify specific situations that do not have
	// a specific extension, for example; self-billed or partial invoices may be
	// identified by their respective tags.
	List []cbc.Key `json:"$tags,omitempty" jsonschema:"title=Tags"`
}

type TaxableLine interface {
	GetTaxes() Set
	GetTotal() num.Amount
}

type Total struct {
	// Grouping of all the taxes by their category
	Categories []*CategoryTotal `json:"categories,omitempty" jsonschema:"title=Categories"`
	// Total value of all non-retained or indirect taxes.
	Sum num.Amount `json:"sum" jsonschema:"title=Sum"`
	// Sum of retained or withheld tax amounts
	Retained *num.Amount `json:"retained,omitempty" jsonschema:"title=Retained"`
}

type TotalCalculator struct {
	Country  l10n.TaxCountryCode
	Rounding cbc.Key
	Currency currency.Code
	Date     cal.Date
	Lines    []TaxableLine
	Includes cbc.Code // Tax included in price
	// contains filtered or unexported fields
}

type Validator func(doc any) error