client

Documentation

Index

• type Client
  • func New(baseURL string) *Client
  • func (c *Client) BuildRequestSummary(method, rawPath string, params, data any) RequestSummary
  • func (c *Client) DeleteJSON(ctx context.Context, rawPath string, out any) error
  • func (c *Client) DeleteJSONWithQuery(ctx context.Context, rawPath string, query map[string]any, out any) error
  • func (c *Client) DoRaw(ctx context.Context, request RawRequest) (RawResponse, error)
  • func (c *Client) GetJSON(ctx context.Context, rawPath string, out any) error
  • func (c *Client) GetJSONWithQuery(ctx context.Context, rawPath string, query map[string]any, out any) error
  • func (c *Client) PatchJSON(ctx context.Context, rawPath string, payload any, out any) error
  • func (c *Client) PostJSON(ctx context.Context, rawPath string, payload any, out any) error
  • func (c *Client) PutJSON(ctx context.Context, rawPath string, payload any, out any) error
  • func (c *Client) ResolveURL(rawPath string) string
  • func (c *Client) SendStream(ctx context.Context, request RawRequest) (io.ReadCloser, error)
  • func (c *Client) SetBaseURL(u string)
  • func (c *Client) SetBearerToken(token string)
• type HTTPError
  • func (e *HTTPError) Error() string
• type RawRequest
• type RawResponse
  • func (r RawResponse) RequestID() string
• type RequestSummary

Types

type Client

type Client struct {
	BaseURL    string
	HTTPClient *http.Client
	Headers    map[string]string
	// Debug, when non-nil, dumps each request (method/URL/headers, auth values
	// redacted) and the raw response to it. Off by default.
	Debug io.Writer
}

Client wraps the underlying HTTP client and target base URL.

func New

func New(baseURL string) *Client

New creates a minimal API client.

func (*Client) BuildRequestSummary

func (c *Client) BuildRequestSummary(method, rawPath string, params, data any) RequestSummary

BuildRequestSummary creates a lightweight request preview.

func (*Client) DeleteJSON

func (c *Client) DeleteJSON(ctx context.Context, rawPath string, out any) error

func (*Client) DeleteJSONWithQuery

func (c *Client) DeleteJSONWithQuery(ctx context.Context, rawPath string, query map[string]any, out any) error

func (*Client) DoRaw

func (c *Client) DoRaw(ctx context.Context, request RawRequest) (RawResponse, error)

DoRaw executes a generic HTTP request and returns a parsed response payload.

Header write order (later writes overwrite earlier ones):

1. Content-Type (from Headers["Content-Type"] or "application/json" default)
2. Accept default
3. request.Headers (Content-Type excluded; empty values skipped)
4. c.Headers — always last, so caller cannot forge Access-Token via request.Headers.

func (*Client) GetJSON

func (c *Client) GetJSON(ctx context.Context, rawPath string, out any) error

func (*Client) GetJSONWithQuery

func (c *Client) GetJSONWithQuery(ctx context.Context, rawPath string, query map[string]any, out any) error

func (*Client) PatchJSON

func (c *Client) PatchJSON(ctx context.Context, rawPath string, payload any, out any) error

func (*Client) PostJSON

func (c *Client) PostJSON(ctx context.Context, rawPath string, payload any, out any) error

func (*Client) PutJSON

func (c *Client) PutJSON(ctx context.Context, rawPath string, payload any, out any) error

func (*Client) ResolveURL

func (c *Client) ResolveURL(rawPath string) string

ResolveURL resolves a request path against the configured base URL.

func (*Client) SendStream

func (c *Client) SendStream(ctx context.Context, request RawRequest) (io.ReadCloser, error)

SendStream executes an HTTP request and returns the response body as an io.ReadCloser without buffering it in memory. Use for large/streamed downloads (zip / wasm / streamed exports). Callers MUST defer Close.

Uses an internal http.Client with NO Timeout — long downloads must rely on ctx for cancellation. c.HTTPClient.Timeout would otherwise cut large transfers.

func (*Client) SetBaseURL

func (c *Client) SetBaseURL(u string)

SetBaseURL updates the target base URL (e.g. once the auth gate resolves the store domain). Trailing slashes are stripped, matching New.

func (*Client) SetBearerToken

func (c *Client) SetBearerToken(token string)

SetBearerToken sets the access token. Shoplazza OpenAPI uses Access-Token header (not Authorization: Bearer).

type HTTPError

type HTTPError struct {
	StatusCode int
	Body       string
	Method     string
	Path       string
}

HTTPError wraps a non-2xx HTTP response. Method and Path name the failing request so a server error can identify which endpoint it came from.

func (*HTTPError) Error

func (e *HTTPError) Error() string

type RawRequest

type RawRequest struct {
	Method  string
	Path    string
	Params  map[string]any
	Data    any               // For DoRaw's multipart branch (Headers["Content-Type"] set), Data must be io.Reader, []byte, or untyped nil; typed-nil readers panic and strings must be wrapped as []byte or strings.NewReader.
	Headers map[string]string // Optional. Honored by DoRaw only; ignored by SendStream.
	// NoTimeout makes DoRaw bypass the client-wide HTTPClient.Timeout and rely
	// on ctx for cancellation instead. Set it for long-running transfers that
	// exceed the request timeout. Ignored by SendStream.
	NoTimeout bool
}

RawRequest is a generic HTTP request for the raw api layer.

type RawResponse

type RawResponse struct {
	StatusCode  int                 `json:"status_code"`
	ContentType string              `json:"content_type,omitempty"`
	Headers     map[string][]string `json:"headers,omitempty"`
	Body        any                 `json:"body,omitempty"`
}

RawResponse is the generic raw api execution result.

func (RawResponse) RequestID

func (r RawResponse) RequestID() string

RequestID returns the first Request-Id header value, or "" if absent.

type RequestSummary

type RequestSummary struct {
	Method string `json:"method"`
	Path   string `json:"path"`
	URL    string `json:"url"`
	Params any    `json:"params,omitempty"`
	Data   any    `json:"data,omitempty"`
}

RequestSummary is a lightweight raw request preview.