Documentation
¶
Overview ¶
Package stores is the store-platform contract (design expansion phase 7, M30): what ReputeCast reads from a merchant's own Shopify or WooCommerce shop and how it is told about changes, on the pattern of the sending providers and the payment providers. Each adapter implements Client against its platform's API over plain HTTP, verifies and parses its webhooks (WebhookParser), and registers itself with Register; core code (internal/commerce) talks only to these interfaces. Every adapter passes the shared suite in internal/stores/contracttest against its fake.
Never read or kept, whatever the platform sends: addresses, phone numbers, payment details and order notes (brief §3.6). The parsers drop them before anything else sees the payload.
Index ¶
- Constants
- Variables
- func Exponent(currency string) int
- func FormatAmount(v int64, currency string) string
- func IsRateLimited(err error) (time.Duration, bool)
- func NormalizeHost(address string) string
- func ParseAmount(s, currency string) int64
- func Register(d Descriptor)
- func StripLanding(landing string) string
- type Capability
- type Checkout
- type Client
- type Collection
- type Config
- type Consent
- type Customer
- type Descriptor
- type Event
- type LineItem
- type Order
- type Page
- type Product
- type Range
- type RateLimited
- type Refund
- type Shop
- type UTM
- type Webhook
- type WebhookParser
Constants ¶
const ( ConsentSubscribed = "subscribed" ConsentNotSubscribed = "not_subscribed" ConsentUnsubscribed = "unsubscribed" ConsentPending = "pending" )
Marketing consent states.
const ( CountProducts = "products" CountCustomers = "customers" CountOrders = "orders" )
Kinds Count accepts.
const ( EventOrder = "order" EventOrderDeleted = "order_deleted" EventRefund = "refund" EventCustomer = "customer" EventCheckout = "checkout" EventProduct = "product" EventProductDeleted = "product_deleted" EventUninstalled = "uninstalled" // EventPing is WooCommerce's delivery check when a webhook is created. EventPing = "ping" )
Event kinds, normalized across platforms.
const ClickTokenParam = "rc"
ClickTokenParam is the query parameter that carries ReputeCast's click token on links to a store (phase 7: `rc`).
const CurrencyHeader = "X-ReputeCast-Store-Currency"
CurrencyHeader carries the store's currency into Parse, for payloads that don't name theirs (Shopify's products and refunds): the service sets it on the stored headers before parsing.
Variables ¶
var ( // an uninstalled app, a deleted key). ErrUnauthorized = errors.New("store: credentials refused") // ErrPermission: the credentials lack an access scope. ErrPermission = errors.New("store: missing access") ErrUnavailable = errors.New("store: unavailable") // ErrNotFound: an object the store doesn't have. ErrNotFound = errors.New("store: not found") // ErrNotAStore: the address doesn't answer like a store of the platform. ErrNotAStore = errors.New("store: not a store of this platform") // ErrBadSignature: a webhook whose signature doesn't verify. ErrBadSignature = errors.New("store: webhook signature verification failed") // ErrUnsupported: the platform can't do it. ErrUnsupported = errors.New("store: not supported by the platform") )
Errors adapters return.
Functions ¶
func FormatAmount ¶
FormatAmount writes minor units as a decimal amount ("58.00").
func IsRateLimited ¶
IsRateLimited reports whether err is a throttle, and how long to wait.
func NormalizeHost ¶
NormalizeHost turns what a person typed ("https://Shop.Acme.io/", "acme-merch.myshopify.com/admin") into a bare lowercase host.
func ParseAmount ¶
ParseAmount reads a decimal amount ("58.00", "58.0", "1234") into minor units of currency, rounding half away from zero past its precision. An empty or unreadable amount is 0.
func Register ¶
func Register(d Descriptor)
Register adds an adapter; adapters call it from their package's init.
func StripLanding ¶
StripLanding keeps a landing page's path and query without the click token, so what is stored can't be replayed as a token.
Types ¶
type Capability ¶
type Capability string
Capability is a badge on a store's catalog card and page (brief §3.6).
const ( CapOrders Capability = "orders" CapProducts Capability = "products" CapCustomers Capability = "customers" // customers who accepted marketing CapCheckouts Capability = "checkouts" // abandoned checkouts CapWriteBack Capability = "write_back" // unsubscribes passed back CapAttribution Capability = "attribution" // orders credited to emails )
Capabilities, in the order of the cards.
type Checkout ¶
type Checkout struct {
ID string
Email string
Customer *Customer
AcceptsMarketing bool
Items []LineItem
Subtotal int64
Total int64
Currency string
// RecoveryURL is the store's own link back to the checkout.
RecoveryURL string
ClickToken string
CreatedAt time.Time
UpdatedAt time.Time
CompletedAt *time.Time
}
Checkout is a checkout with an email address (a candidate abandoned checkout until it becomes an order).
type Client ¶
type Client interface {
// Shop reads the store's name, domains and currency.
Shop(ctx context.Context) (Shop, error)
// Count counts products, customers or orders in a range, for the
// first import's progress.
Count(ctx context.Context, kind string, r Range) (int, error)
Products(ctx context.Context, cursor string, r Range) (Page[Product], error)
Collections(ctx context.Context, cursor string) (Page[Collection], error)
Customers(ctx context.Context, cursor string, r Range) (Page[Customer], error)
Orders(ctx context.Context, cursor string, r Range) (Page[Order], error)
// Checkouts lists checkouts with an email that didn't become orders
// (ErrUnsupported where the platform has none of its own).
Checkouts(ctx context.Context, cursor string, r Range) (Page[Checkout], error)
Webhooks(ctx context.Context) ([]Webhook, error)
Subscribe(ctx context.Context, topic, address, secret string) (Webhook, error)
Unsubscribe(ctx context.Context, id string) error
// SetConsent tells the store a customer unsubscribed (consent
// write-back; ErrUnsupported or ErrPermission without it).
SetConsent(ctx context.Context, customerID, state string, at time.Time) error
}
Client is a store reached with the workspace's own credentials.
type Collection ¶
Collection is a group of products (Shopify's collections, WooCommerce's product categories).
type Config ¶
type Config struct {
// Domain is the store's canonical host: acme-merch.myshopify.com, or
// the WooCommerce site's host.
Domain string
// BaseURL overrides https://{Domain} (tests; the fakes).
BaseURL string
// HTTP overrides the client (the SSRF guard's in production).
HTTP *http.Client
// Token is a Shopify access token (write-only, sealed at rest).
Token string
// Key and Secret are a WooCommerce REST API key (sealed at rest).
Key, Secret string
// APIVersion overrides the adapter's pinned API version.
APIVersion string
// Now overrides the clock (tests).
Now func() time.Time
// RetryWait overrides the pause between retries of 5xx answers.
RetryWait time.Duration
}
Config opens a client on a store.
type Consent ¶
type Consent struct {
// State: subscribed, not_subscribed, unsubscribed or pending.
State string
// Level: single_opt_in, confirmed_opt_in or unknown.
Level string
UpdatedAt *time.Time
// Text is the exact checkbox text, when the platform records it (the
// ReputeCast plugin at a WooCommerce checkout).
Text string
// IP is the address the consent was given from, when recorded.
IP string
}
Consent is a customer's email-marketing consent in the store.
type Customer ¶
type Customer struct {
ID string
Email string
FirstName string
LastName string
Country string
Consent Consent
CreatedAt time.Time
UpdatedAt time.Time
}
Customer is a store customer. Only an email, a name and a country are read; never an address or a phone number.
type Descriptor ¶
type Descriptor struct {
Key string
Name string
// Capabilities with everything set up (WooCommerce's consent and
// abandoned checkouts need the ReputeCast plugin).
Capabilities []Capability
// Topics are the webhooks ReputeCast registers, in the order of the
// store page's table.
Topics []string
// Open connects to a store.
Open func(cfg Config) (Client, error)
// Webhooks verifies and parses deliveries.
Webhooks WebhookParser
}
Descriptor describes an adapter.
func Adapters ¶
func Adapters() []Descriptor
Adapters lists the registered adapters in registration order.
func (Descriptor) Has ¶
func (d Descriptor) Has(c Capability) bool
Has reports whether d has a capability.
type Event ¶
type Event struct {
Kind string
// Topic is the platform's own topic ("orders/create", "order.updated").
Topic string
// DeliveryID identifies the delivery; a retry carries the same one.
DeliveryID string
// TriggeredAt is when the platform sent it (zero when unknown).
TriggeredAt time.Time
Order *Order
Customer *Customer
Checkout *Checkout
Product *Product
Refund *Refund
// DeletedID is a deleted product's or order's id.
DeletedID string
}
Event is one verified webhook delivery, normalized.
type LineItem ¶
type LineItem struct {
ProductID string `json:"productId"`
VariantID string `json:"variantId,omitempty"`
Title string `json:"title"`
Variant string `json:"variant,omitempty"`
Quantity int `json:"quantity"`
// Price is the unit price, in minor units.
Price int64 `json:"price"`
ImageURL string `json:"imageUrl,omitempty"`
}
LineItem is one line of an order or a checkout.
type Order ¶
type Order struct {
ID string
Name string // "#4409"
Number string // "4409"
Email string
// Customer is the buyer as the order carries them, with the consent
// given at checkout.
Customer *Customer
AcceptsMarketing bool
PlacedAt time.Time
UpdatedAt time.Time
Currency string
// Subtotal, Total and Refunded are in minor units; Refunds lists each
// refund (an order's refunds are counted once each, whichever event
// brings them).
Subtotal int64
Total int64
Refunded int64
Refunds []Refund
Discounts []string
Items []LineItem
// LandingPage is the page the buyer arrived on (path and query, or a
// full URL), with its UTM parameters and ReputeCast's click token.
LandingPage string
UTM UTM
ClickToken string
// CheckoutToken links the order to the checkout it completed.
CheckoutToken string
Cancelled bool
// Test orders (Shopify's test mode, Bogus gateway) are kept apart.
Test bool
}
Order is one order. Email is read to match the buyer to a contact and never stored.
type Product ¶
type Product struct {
ID string
Title string
Handle string
URL string
ImageURL string
ImageAlt string
// Price and CompareAt are in minor units of Currency; CompareAt is 0
// when the product isn't on sale.
Price int64
CompareAt int64
Currency string
// Available reports whether it can be bought; Inventory is the stock
// when the store tracks it (nil otherwise).
Available bool
Inventory *int
// Status: active, draft or archived (removed products arrive as a
// deletion, never as a status).
Status string
Collections []string
CreatedAt time.Time
UpdatedAt time.Time
}
Product is one product, with the price of its cheapest variant.
type Range ¶
type Range struct {
// CreatedSince keeps what was created at or after it (the first
// import's 3, 6 or 12 months).
CreatedSince time.Time
// UpdatedSince keeps what changed at or after it (the nightly
// reconciliation and polling a missing webhook).
UpdatedSince time.Time
}
Range limits what a list returns.
type RateLimited ¶
RateLimited is a request the store throttled: wait RetryAfter.
func (*RateLimited) Error ¶
func (e *RateLimited) Error() string
type Shop ¶
type Shop struct {
Name string `json:"name"`
// Domain is the canonical host (acme-merch.myshopify.com).
Domain string `json:"domain"`
// PublicDomain is the storefront's own domain (shop.acme.io).
PublicDomain string `json:"publicDomain"`
Currency string `json:"currency"`
}
Shop is what connecting reads about the store.
type UTM ¶
type UTM struct {
Source string `json:"source,omitempty"`
Medium string `json:"medium,omitempty"`
Campaign string `json:"campaign,omitempty"`
Content string `json:"content,omitempty"`
Term string `json:"term,omitempty"`
}
UTM are an order's landing page parameters.
func ParseLanding ¶
ParseLanding reads a landing page (a path with its query, or a full URL) into its UTM parameters and click token.
type WebhookParser ¶
type WebhookParser interface {
// Verify checks the signature against the store's secret.
Verify(h http.Header, body []byte, secret string) error
// Topic reads the delivery's topic and id from its headers.
Topic(h http.Header) (topic, delivery string)
// Parse normalizes a verified delivery.
Parse(h http.Header, body []byte) (Event, error)
}
WebhookParser verifies and parses one adapter's deliveries.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package contracttest is the shared suite every store adapter passes, like the sending and payment adapters' (internal/providers/contracttest, internal/payments/contracttest): the registry entry, reading the shop, products with paging and availability, collections, customers with their marketing consent, orders in a range with the landing page's click token, abandoned checkouts, webhooks (subscribe, list, remove), consent write-back, webhook signatures (a bad or tampered one refused) and the recorded payloads' parsing, refused credentials, throttling and an outage — against the adapter's fake of the platform, with no network.
|
Package contracttest is the shared suite every store adapter passes, like the sending and payment adapters' (internal/providers/contracttest, internal/payments/contracttest): the registry entry, reading the shop, products with paging and availability, collections, customers with their marketing consent, orders in a range with the landing page's click token, abandoned checkouts, webhooks (subscribe, list, remove), consent write-back, webhook signatures (a bad or tampered one refused) and the recorded payloads' parsing, refused credentials, throttling and an outage — against the adapter's fake of the platform, with no network. |
|
Package shopify is the Shopify store adapter: a custom app the merchant creates in their own Shopify account (Dev Dashboard), installed through Shopify's own approval page (OAuth authorization code grant), then Shopify's GraphQL Admin API over plain HTTPS with the app's access token (no SDK), and webhooks verified with the app's client secret (HMAC).
|
Package shopify is the Shopify store adapter: a custom app the merchant creates in their own Shopify account (Dev Dashboard), installed through Shopify's own approval page (OAuth authorization code grant), then Shopify's GraphQL Admin API over plain HTTPS with the app's access token (no SDK), and webhooks verified with the app's client secret (HMAC). |
|
shopifytest
Package shopifytest is an in-memory Shopify: the store's storefront metadata (/meta.json), the app install (OAuth's code exchange and token refresh) and the subset of the GraphQL Admin API the adapter calls, answered from an in-memory store in the shapes Shopify returns, plus helpers that build signed webhook deliveries in Shopify's REST payload shape.
|
Package shopifytest is an in-memory Shopify: the store's storefront metadata (/meta.json), the app install (OAuth's code exchange and token refresh) and the subset of the GraphQL Admin API the adapter calls, answered from an in-memory store in the shapes Shopify returns, plus helpers that build signed webhook deliveries in Shopify's REST payload shape. |
|
Package woocommerce is the WooCommerce store adapter: WooCommerce's REST API (wc/v3) over plain HTTPS with a REST API key the merchant creates with Read/Write access (sealed at rest, never shown again), and webhooks registered with a secret whose signatures are checked on arrival.
|
Package woocommerce is the WooCommerce store adapter: WooCommerce's REST API (wc/v3) over plain HTTPS with a REST API key the merchant creates with Read/Write access (sealed at rest, never shown again), and webhooks registered with a secret whose signatures are checked on arrival. |
|
wootest
Package wootest is an in-memory WooCommerce site: the REST index (with the ReputeCast plugin's namespace when it's active), the wc/v3 endpoints the adapter calls (currency, products, categories, orders, webhooks) behind a REST API key, and helpers that build signed webhook deliveries in WooCommerce's payload shape, with the plugin's order meta.
|
Package wootest is an in-memory WooCommerce site: the REST index (with the ReputeCast plugin's namespace when it's active), the wc/v3 endpoints the adapter calls (currency, products, categories, orders, webhooks) behind a REST API key, and helpers that build signed webhook deliveries in WooCommerce's payload shape, with the plugin's order meta. |