Documentation
¶
Overview ¶
Package store describes a VTEX storefront.
The design principle is discover, don't declare: almost everything that differs between VTEX stores — auth capabilities, payment systems, sellers, delivery SLAs — is readable from the store's own public API at runtime. A descriptor carries only what cannot be discovered: the base URL, business rules with no API representation, and drivers for behavior VTEX ID cannot express generically.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Capabilities ¶
type Capabilities struct {
Account string `json:"account"`
Classic bool `json:"classic"`
AccessKey bool `json:"accessKey"`
OAuthProviders []string `json:"oauthProviders"`
// AuthenticationToken links the start call to the subsequent validate
// call. VTEX rejects a validate that reuses a token from a different
// start, so it must be threaded through, not re-fetched.
AuthenticationToken string `json:"-"`
}
Capabilities is what a live storefront reports about itself. Reading this is what lets a store descriptor stay three fields long.
func Probe ¶
Probe reads a store's auth capabilities from the public VTEX ID authentication-start endpoint. No credentials required, no side effects.
It asks twice when it has to. Scoping the call to the account is what makes a store's custom OAuth provider visible, but some stores answer a scoped call with only that provider, hiding an access key VTEX ID still accepts. Prezunic reports classic=false, accessKey=false and a "Prezunic Login" provider when scoped, yet unscoped it reports accessKey=true — and accesskey/send really does email a code. Believing the scoped answer alone made the CLI refuse the only login that store has.
Only the access key is taken from the unscoped answer. The unscoped call also reports classic=true for stores whose classic login is documented as disabled, and that claim could not be confirmed: the classic validate endpoint answers WrongCredentials for an unregistered address whether or not the method is enabled, so there is no way to tell from outside. An unverified capability would route a login down a path that may not work, so classic is left exactly as the scoped call reported it.
func (*Capabilities) HasOAuthProvider ¶
func (c *Capabilities) HasOAuthProvider(name string) bool
HasOAuthProvider reports whether the store offers the named provider.
type HTTPDoer ¶
HTTPDoer is the narrow slice of *http.Client that drivers and the probe need. It keeps this package free of any dependency on package vtex.
type OAuthDriver ¶
type OAuthDriver interface {
// ProviderName must match an entry in oauthProviders[].providerName
// from the authentication-start probe.
ProviderName() string
// Login returns a VTEX JWT — the VtexIdclientAutCookie_<account> value.
Login(ctx context.Context, c HTTPDoer, baseURL, email, password string) (string, error)
}
OAuthDriver drives a store-specific OAuth provider that VTEX ID cannot handle generically. Only stores whose classic auth is disabled need one.
type Quirks ¶
type Quirks uint32
Quirks are behavioral toggles for stores that deviate from stock VTEX.
const ( // ClearSaleFingerprint registers a ClearSale device fingerprint before // credit-card payment. Without it Zona Sul's gateway returns Cielo // code 59, suspected fraud. ClearSaleFingerprint Quirks = 1 << iota // GatewayCallback polls the checkout gatewayCallback endpoint after // payment, retrying on HTTP 428 and 500. GatewayCallback )
type SearchMode ¶
type SearchMode int
SearchMode selects which catalog backend to query.
const ( // SearchAuto tries Intelligent Search REST and falls back to the // catalog REST API. Correct for every store observed so far. SearchAuto SearchMode = iota SearchIntelligentREST SearchCatalogREST // SearchGraphQL uses a persisted query and requires SearchHash and // BindingID. Only for stores that block both REST paths — the hash // rotates on every VTEX search-graphql release and breaks silently. SearchGraphQL )
type Store ¶
type Store struct {
// Name drives the binary name, config dir, keyring service, and env
// var prefix. It is the one field that must never change for a
// published CLI.
Name string
DisplayName string
BaseURL string
// Account overrides the VTEX account name. Derived from BaseURL when
// empty, which is correct for every store observed.
Account string
Search SearchMode
// SearchHash and BindingID apply only to SearchGraphQL.
SearchHash string
BindingID string
// Wishlist carries the persisted-query hashes for vtex.wish-list.
// A zero value means this store's wishlist is not reachable.
Wishlist WishlistHashes
// MinOrder is a business rule with no API representation. Zona Sul
// enforces R$100 but reports it only as a checkout error string.
MinOrder money.Centavos
OAuth OAuthDriver
Quirks Quirks
}
Store describes one VTEX storefront.
func (Store) AccountBaseURL ¶ added in v0.5.0
AccountBaseURL is the VTEX platform host for this account.
Nearly every storefront API answers on the store's own domain, but the Subscriptions (RNS) API resolves the account from the request subdomain. On a www.<store> vanity domain it therefore derives the account "www" and rejects the call with HTTP 400, so those endpoints must be addressed here instead.
func (Store) AccountName ¶
AccountName returns the VTEX account name, deriving it from the base URL host when not set: www.frescatto.com -> frescatto, www.zonasul.com.br -> zonasul.
func (Store) AuthCookieName ¶
AuthCookieName is the VTEX ID cookie this store issues.
func (Store) EnvPrefix ¶
EnvPrefix is the uppercased store name used for env var overrides, e.g. FRESCATTO_JSON.
func (Store) KeyringService ¶
KeyringService namespaces secrets per store.
type WishlistHashes ¶ added in v0.4.0
type WishlistHashes struct {
View string // ViewLists
Add string // AddToList
Remove string // RemoveFromList
}
WishlistHashes are the persisted-query hashes for the vtex.wish-list operations. They are the only way to reach that API — plain, non-persisted queries against the same provider are rejected — and they are tied to the store's installed app version, so they must be captured per store from a live browser session.
func (WishlistHashes) CanRead ¶ added in v0.4.0
func (w WishlistHashes) CanRead() bool
CanRead reports whether the store's wishlist can be listed.
func (WishlistHashes) CanWrite ¶ added in v0.4.0
func (w WishlistHashes) CanWrite() bool
CanWrite reports whether the store's wishlist can be modified.
Source Files