stores

package
v1.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: AGPL-3.0 Imports: 10 Imported by: 0

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

View Source
const (
	ConsentSubscribed    = "subscribed"
	ConsentNotSubscribed = "not_subscribed"
	ConsentUnsubscribed  = "unsubscribed"
	ConsentPending       = "pending"
)

Marketing consent states.

View Source
const (
	CountProducts  = "products"
	CountCustomers = "customers"
	CountOrders    = "orders"
)

Kinds Count accepts.

View Source
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.

View Source
const ClickTokenParam = "rc"

ClickTokenParam is the query parameter that carries ReputeCast's click token on links to a store (phase 7: `rc`).

View Source
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

View Source
var (
	// ErrUnauthorized: the store refused the credentials (a revoked token,
	// 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: the store can't be reached or answers 5xx.
	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 Exponent

func Exponent(currency string) int

Exponent is how many decimals a currency's minor unit has.

func FormatAmount

func FormatAmount(v int64, currency string) string

FormatAmount writes minor units as a decimal amount ("58.00").

func IsRateLimited

func IsRateLimited(err error) (time.Duration, bool)

IsRateLimited reports whether err is a throttle, and how long to wait.

func NormalizeHost

func NormalizeHost(address string) string

NormalizeHost turns what a person typed ("https://Shop.Acme.io/", "acme-merch.myshopify.com/admin") into a bare lowercase host.

func ParseAmount

func ParseAmount(s, currency string) int64

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

func StripLanding(landing string) string

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

type Collection struct {
	ID       string
	Title    string
	Handle   string
	Products int
}

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 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.

func (Consent) Accepted

func (c Consent) Accepted() bool

Accepted reports whether the customer accepted marketing.

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 Lookup

func Lookup(key string) (Descriptor, bool)

Lookup returns a registered adapter.

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 Page

type Page[T any] struct {
	Items []T
	Next  string
}

Page is one page of a list; Next is empty on the last page.

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

type RateLimited struct {
	RetryAfter time.Duration
}

RateLimited is a request the store throttled: wait RetryAfter.

func (*RateLimited) Error

func (e *RateLimited) Error() string

type Refund

type Refund struct {
	ID      string
	OrderID string
	Amount  int64
	At      time.Time
}

Refund is money returned on an order.

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

func ParseLanding(landing string) (UTM, string)

ParseLanding reads a landing page (a path with its query, or a full URL) into its UTM parameters and click token.

type Webhook

type Webhook struct {
	ID      string
	Topic   string
	Address string
}

Webhook is a webhook subscription in the store.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL