path: root/lulu.go

// Package lulu is a client library for the Lulu book printing API.
package lulu

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"net/url"
	"os"
	"time"

	"golang.org/x/oauth2/clientcredentials"
)

const (
	SandboxUrl    = "https://api.sandbox.lulu.com/"
	ProductionUrl = "https://api.lulu.com/"

	tokenPath            = "/auth/realms/glasstree/protocol/openid-connect/token"
	validateInteriorPath = "/validate-interior"
	coverDimensionsPath  = "/cover-dimensions"
	validateCoverPath    = "/validate-cover"
	printJobCostPath     = "/print-job-cost-calculations"
	printJobsPath        = "/print-jobs"
)

// ApiUrl is the location of the API server. It is set to the sandbox
// environment by default; change it to the production environment when
// you are ready to deploy.
var ApiUrl = SandboxUrl

var (
	Debug    = false // print debug info to stdout
	debugLog = log.New(os.Stderr, "DEBUG ", log.LstdFlags|log.Llongfile)
)

type Client struct {
	c *http.Client
}

// NewClient returns a client that will use the given client-key and
// client-secret to connect to the API server.
func NewClient(ctx context.Context, key, secret string) (*Client, error) {
	tokenUrl, err := url.JoinPath(ApiUrl, tokenPath)
	if err != nil {
		return nil, pkgErrf(err, "error creating client")
	}

	cfg := &clientcredentials.Config{
		ClientID:     key,
		ClientSecret: secret,
		TokenURL:     tokenUrl,
	}
	return &Client{cfg.Client(ctx)}, nil
}

// ValidateInterior starts a server-side validation job for the interior
// file located at srcUrl using manufacturing settings given by mfg. It
// returns the ID of the job. Use GetInteriorValidation() to poll the
// status of the job.
//
// https://api.lulu.com/docs/#tag/Files-validation/operation/Validate-Interior_create
func (c *Client) ValidateInterior(srcUrl string, mfg PkgId) (uint, error) {
	id, err := c.validateInterior(validateInteriorReq{srcUrl, mfg})
	if err != nil {
		return 0, pkgErr(err)
	}
	return id, nil
}

// ValidateInteriorBasic is like ValidateInterior but without the
// optional pod_package_id.
//
// https://api.lulu.com/docs/#tag/Files-validation/operation/Validate-Interior_create
func (c *Client) ValidateInteriorBasic(srcUrl string) (uint, error) {
	id, err := c.validateInterior(validateInteriorBasicReq{srcUrl})
	if err != nil {
		return 0, pkgErr(err)
	}
	return id, nil
}

func (c *Client) validateInterior(payload any) (uint, error) {
	var rec InteriorValidationRecord
	err := c.postDecode(validateInteriorPath, payload, http.StatusCreated, &rec)
	return rec.Id, err
}

// GetInteriorValidation retrieves information about an interior file
// validation job that was started by ValidateInterior().
//
// https://api.lulu.com/docs/#tag/Files-validation/operation/Validate-Interior_read
func (c *Client) GetInteriorValidation(id uint) (InteriorValidationRecord, error) {
	path, err := url.JoinPath(validateInteriorPath, fmt.Sprint(id))
	if err != nil {
		return InteriorValidationRecord{}, pkgErr(err)
	}
	var rec InteriorValidationRecord
	if err := c.getDecode(path, &rec); err != nil {
		return InteriorValidationRecord{}, pkgErr(err)
	}
	return rec, nil
}

// CoverDimensions calculates the required dimensions of the cover for a
// book with the given manufacturing settings and number of pages. The
// returned dimensions are given in the specified units of measurement.
//
// https://api.lulu.com/docs/#tag/Files-validation/operation/Cover-Dimensions_create
func (c *Client) CoverDimensions(mfg PkgId, npages uint, unit Unit) (CoverDimensions, error) {
	payload := coverDimensionsReq{mfg, npages, unit}
	var dims CoverDimensions
	err := c.postDecode(coverDimensionsPath, payload, http.StatusCreated, &dims)
	if err != nil {
		return CoverDimensions{}, pkgErr(err)
	}
	return dims, nil
}

// ValidateCover starts a server-side validation job for the cover file
// located at srcUrl, returning the job ID. mfg is the manufacturing
// settings of the book, and npages is the number of interior pages. Use
// GetCoverValidation() to poll the status of the job.
//
// https://api.lulu.com/docs/#tag/Files-validation/operation/Validate-Cover_create
func (c *Client) ValidateCover(srcUrl string, mfg PkgId, npages uint) (uint, error) {
	payload := validateCoverReq{srcUrl, mfg, npages}
	var rec CoverValidationRecord
	err := c.postDecode(validateCoverPath, payload, http.StatusCreated, &rec)
	if err != nil {
		return 0, pkgErr(err)
	}
	return rec.Id, nil
}

// GetCoverValidiation retrieves information about a cover file
// validation job that was started by ValidiateCover().
//
// https://api.lulu.com/docs/#tag/Files-validation/operation/Validate-Cover_read
func (c *Client) GetCoverValidation(id uint) (CoverValidationRecord, error) {
	path, err := url.JoinPath(validateCoverPath, fmt.Sprint(id))
	if err != nil {
		return CoverValidationRecord{}, pkgErr(err)
	}
	var rec CoverValidationRecord
	if err := c.getDecode(path, &rec); err != nil {
		return CoverValidationRecord{}, pkgErr(err)
	}
	return rec, nil
}

// PrintJobCost calculates the cost of a hypothetical print order without
// actually creating a print job.
//
// https://api.lulu.com/docs/#tag/Print-Job-Cost-Calculations/operation/Print-Job-cost-calculations_create
func (c *Client) PrintJobCost(items []PrintJobCostLineItem, addr ShippingAddress, shipOpt ShippingLevel) (PrintJobCost, ShippingAddressValidation, error) {
	reqAddr := printJobCostReqShipAddr{
		City:     addr.City,
		Country:  addr.Country,
		PostCode: addr.PostCode,
		State:    addr.State,
		Street1:  addr.Street1,
		Phone:    addr.Phone,
	}
	payload := printJobCostReq{items, reqAddr, shipOpt}

	var resp printJobCostResp
	err := c.postDecode(printJobCostPath, payload, http.StatusCreated, &resp)
	if err != nil {
		return PrintJobCost{}, ShippingAddressValidation{}, pkgErr(err)
	}
	return resp.cost(), resp.AddressValidation, nil
}

// GetPrintJobs retrieves a list of all print jobs that have been
// created, filtered by a set of optional query parameters.
//
// https://api.lulu.com/docs/#tag/Print-Jobs/operation/Print-Jobs_list
func (c *Client) GetPrintJobs(queries ...PrintJobQuery) ([]PrintJob, error) {
	var q printJobQueries
	q.apply(queries...)
	qvals := q.vals()

	verify := func(v any) error {
		resp := v.(*getPrintJobsResp)
		if int(resp.Count) != len(resp.Results) {
			return fmt.Errorf("count (%d) != len(results) (%d)", resp.Count, len(resp.Results))
		} else if len(resp.Results) == 0 && resp.Next != "" {
			return fmt.Errorf("no results on this page, but server returned a next page: %s", resp.Next)
		}
		return nil
	}

	var jobs []PrintJob
	for page := 1; ; page++ {
		qvals.Set("page", fmt.Sprint(page))
		var resp getPrintJobsResp
		if err := c.getQueryDecodeVerify(printJobsPath, qvals, &resp, verify); err != nil {
			return jobs, pkgErr(err)
		}
		if len(resp.Results) > 0 {
			jobs = append(jobs, resp.Results...)
		}
		if len(resp.Results) == 0 || len(resp.Next) == 0 {
			return jobs, nil
		}
	}
}

// Print creates a new print job.
//
//	contact: Email address that should be contacted if questions
//	regarding the Print-Job arise. Lulu recommends to use the
//	email of a person who is responsible for placing the Print-Job
//	like a developer or business owner.
//
//	externalId: Arbitrary string to identify and connect a print
//	job to your systems. Set it to an order number, a purchase
//	order or whatever else works for your particular use case.
//
//	productionDelay: Delay before a newly created Print-Job is
//	sent to production. Minimum is 60 minutes, maximum is 2880
//	minutes (=48 hours). As most cancellation requests occur right
//	after an order has been placed, it makes sense to wait for
//	some time before sending an order to production. Once
//	production has started, orders cannot be canceled anymore.
//
//	addr: The postal address of the customer that the order will
//	be sent to.
//
//	shipOpt: Shipping method.
//
//	items: List of books to print.
//
// https://api.lulu.com/docs/#tag/Print-Jobs/operation/Print-Jobs_create
func (c *Client) Print(contact EmailAddress, externalId string, productionDelay time.Duration, addr ShippingAddress, shipOpt ShippingLevel, items []Printable) (PrintJob, error) {
	if err := verifyProductionDelay(productionDelay); err != nil {
		return PrintJob{}, pkgErr(err)
	}

	req := printReq{
		Contact:             contact,
		ExternalId:          externalId,
		LineItems:           items,
		ProductionDelayMins: uint(productionDelay.Round(time.Minute).Minutes()),
		ShipAddr:            addr,
		ShipOpt:             shipOpt,
	}

	var job PrintJob
	err := c.postDecode(printJobsPath, req, http.StatusCreated, &job)
	if err != nil {
		return job, pkgErr(err)
	}
	return job, nil
}

func verifyProductionDelay(delay time.Duration) error {
	if delay < MinProductionDelay || delay > MaxProductionDelay {
		return fmt.Errorf("production delay %s out of range: must be [%s, %s]",
			delay, MinProductionDelay, MaxProductionDelay)
	}
	return nil
}

// getDecode sends a GET request and unmarshals the response.
func (c *Client) getDecode(path string, v any) error {
	verify := func(v any) error { return nil }
	return c.getQueryDecodeVerify(path, nil, v, verify)
}

// getDecodeVerify sends a GET /path/?query request and unmarshals and
// verifies the response.
func (c *Client) getQueryDecodeVerify(path string, query url.Values, v any, verify func(any) error) error {
	url, err := url.JoinPath(ApiUrl, path)
	if err != nil {
		return err
	}
	url += "?" + query.Encode()

	resp, err := c.c.Get(url)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return errRespStatus{resp}
	}
	if err := decodeResponse(resp, v); err != nil {
		return err
	}
	if err := verify(v); err != nil {
		return errResp{resp, err}
	}
	return nil
}

// postDecode sends a POST request and unmarshals the response.
func (c *Client) postDecode(path string, payload any, wantStatus int, v any) error {
	resp, err := c.post(path, payload)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	if resp.StatusCode != wantStatus {
		return errRespStatus{resp}
	}
	return decodeResponse(resp, v)
}

func (c *Client) post(path string, payload any) (*http.Response, error) {
	body, err := json.Marshal(payload)
	if err != nil {
		return nil, errEncReq{payload, path, err}
	}
	url, err := url.JoinPath(ApiUrl, path)
	if err != nil {
		return nil, err
	}

	debugf("POST %s request: `%s`\n", url, body)

	return c.c.Post(url, "application/json", bytes.NewBuffer(body))
}

func decodeResponse(resp *http.Response, v any) error {
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return errReadResp{resp, err}
	}

	debugf("%s %s response: `%s`\n", resp.Request.Method, resp.Request.URL, body)

	if err := json.Unmarshal(body, v); err != nil {
		return errDecResp{resp, body, err}
	}
	return nil
}

func debugf(format string, a ...any) {
	if Debug {
		debugLog.Printf(format, a...)
	}
}