Merge pull request #327 from VictorAvelar/review-structs-vs-api-refer…

…ence

Ensure API parity on all resources

.github/workflows/golangci-lint.yml

@@ -35,11 +35,15 @@ jobs:
     permissions:
       contents: read
       pull-requests: read
+      checks: write
     steps:
       - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+        with:
+          fetch-depth: '0'
       - uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491
         with:
           go-version: 1.22.X
       - uses: golangci/golangci-lint-action@3cfe3a4abbb849e10058ce4af15d205b6da42804
         with:
           version: latest
+          install-mode: binary

.github/workflows/main.yml

@@ -40,4 +40,4 @@ jobs:
       - uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491
         with:
           go-version: ${{ matrix.go }}
-      - run: go test -v -failfast ./...
+      - run: go test -failfast ./...

Taskfile.yml

@@ -64,6 +64,8 @@ tasks:
   update-docs:
     cmds:
       - gomarkdoc --output docs/README.md ./mollie
+      - git add --all
+      - "git commit --message 'chore(docs): update generated docs'"
     silent: false
 
   sub-pkg-docs:

docs/v4-upgrade.md

@@ -0,0 +1,24 @@
+# Notable changes included in v4
+
+## Breaking changes
+
+- `idempotency` package has moved from the `mollie` directory to the `pkg` directory.
+- `pagination` package has moved from the`mollie` directory to the `pkg` directory.
+- `connect` package has moved from the `mollie` directory to the `pkg` directory.
+- root namespace is not `github.com/VictorAvelar/mollie-api-go/v4/`.
+- Changes in all resources:
+  - Data structures to describe request content in create, update and get operations are no longer the same, e.g. for `payments` there is a `CreatePayment` struct, a `UpdatePayment` struct and a `Payment` struct. This enables future extensions and modifications without having to check for cross request compatibility.
+  - Data structures that describe available url parameters are consistently names `List{ResourceName}Options`.
+  - Data structures that describe lists responses are consistently named as follows: e.g. for payments: `PaymentsList`
+- API aliases now use the parent objects, e.g. for settlements when listing payments the options passed to the request are using the `ListPaymentsOptions` object and not a local object.
+- All resources were checked for API consistency and parity, optional resources with custom types are now pointers to ensure proper json encoding and decoding to avoid issues as the one mentioned un #271
+- All resources embed a struct containing all the fields specific to access tokens, following this pattern the same happens for fields specific to Mollie connect
+
+## Other changes
+
+- `testify.Suite` was removed from all testing.
+- Improvements for devcontainer files
+- Major versions of multiple github actions updated
+- Base `Dockerfile` using Go 1.22.x
+- Tests were update to use the new types.
+- Test coverage was slightly improved.

mollie/balances.go

@@ -208,9 +208,6 @@ const (
 	PlatformPaymentChargeback              TransactionType = "platform-payment-chargeback"
 )
 
-// ContextValues is a map of TransactionType to ContextValue.
-type ContextValues map[TransactionType]ContextValue
-
 // BalanceTransactionsList contains an array of embedded transactions.
 type BalanceTransactionsList struct {
 	Count    int `json:"count,omitempty"`

mollie/captures.go

@@ -7,8 +7,55 @@ import (
 	"time"
 )
 
-// CapturesService operates over captures resource.
-type CapturesService service
+// CaptureMode describes the mode of a capture.
+type CaptureMode string
+
+// CaptureMode possible values.
+const (
+	AutomaticCapture CaptureMode = "automatic"
+	ManualCapture    CaptureMode = "manual"
+)
+
+// CaptureStatus describes the status of a capture.
+type CaptureStatus string
+
+// CaptureStatus possible values.
+const (
+	CaptureStatusPending   CaptureStatus = "pending"
+	CaptureStatusSucceeded CaptureStatus = "succeeded"
+	CaptureStatusFailed    CaptureStatus = "failed"
+)
+
+// CreateCapture describes the payload for creating a capture.
+type CreateCapture struct {
+	Description string  `json:"description,omitempty"`
+	Metadata    any     `json:"metadata,omitempty"`
+	Amount      *Amount `json:"amount,omitempty"`
+	CaptureAccessTokenFields
+}
+
+// CaptureAccessTokenFields describes the payload for creating a capture with an access token.
+type CaptureAccessTokenFields struct {
+	Testmode bool `json:"testmode,omitempty"`
+}
+
+// Capture describes a single capture.
+// Captures are used for payments that have the authorize-then-capture flow.
+type Capture struct {
+	Resource         string        `json:"resource,omitempty"`
+	ID               string        `json:"id,omitempty"`
+	Mode             Mode          `json:"mode,omitempty"`
+	Amount           *Amount       `json:"amount,omitempty"`
+	Status           CaptureStatus `json:"status,omitempty"`
+	SettlementAmount *Amount       `json:"settlementAmount,omitempty"`
+	PaymentID        string        `json:"paymentId,omitempty"`
+	ShipmentID       string        `json:"shipmentId,omitempty"`
+	SettlementID     string        `json:"settlementId,omitempty"`
+	CreatedAt        *time.Time    `json:"createdAt,omitempty"`
+	Metadata         any           `json:"metadata,omitempty"`
+	Links            CaptureLinks  `json:"_links,omitempty"`
+	CaptureAccessTokenFields
+}
 
 // CaptureLinks contains relevant links for a capture object.
 type CaptureLinks struct {
@@ -19,19 +66,11 @@ type CaptureLinks struct {
 	Documentation *URL `json:"documentation,omitempty"`
 }
 
-// Capture describes a single capture.
-// Captures are used for payments that have the authorize-then-capture flow.
-type Capture struct {
-	Resource         string       `json:"resource,omitempty"`
-	ID               string       `json:"id,omitempty"`
-	Mode             Mode         `json:"mode,omitempty"`
-	Amount           *Amount      `json:"amount,omitempty"`
-	SettlementAmount *Amount      `json:"settlementAmount,omitempty"`
-	PaymentID        string       `json:"paymentId,omitempty"`
-	ShipmentID       string       `json:"shipmentId,omitempty"`
-	SettlementID     string       `json:"settlementId,omitempty"`
-	CreatedAt        *time.Time   `json:"createdAt,omitempty"`
-	Links            CaptureLinks `json:"_links,omitempty"`
+// CaptureOptions describes the query params available to use when retrieving captures.
+//
+// See: https://docs.mollie.com/reference/v2/captures-api/get-capture#embedding-of-related-resources
+type CaptureOptions struct {
+	Embed []EmbedValue `url:"embed,omitempty"`
 }
 
 // CapturesList describes a list of captures.
@@ -43,14 +82,47 @@ type CapturesList struct {
 	Links PaginationLinks `json:"_links,omitempty"`
 }
 
+// CapturesService operates over captures resource.
+type CapturesService service
+
 // Get retrieves a single capture by its ID.
 // Note the original payment’s ID is needed as well.
 //
 // See: https://docs.mollie.com/reference/v2/captures-api/get-capture
-func (cs *CapturesService) Get(ctx context.Context, payment, capture string) (res *Response, c *Capture, err error) {
+func (cs *CapturesService) Get(ctx context.Context, payment, capture string, options *CaptureOptions) (
+	res *Response,
+	c *Capture,
+	err error,
+) {
 	u := fmt.Sprintf("v2/payments/%s/captures/%s", payment, capture)
 
-	res, err = cs.client.get(ctx, u, nil)
+	res, err = cs.client.get(ctx, u, options)
+	if err != nil {
+		return
+	}
+
+	if err = json.Unmarshal(res.content, &c); err != nil {
+		return
+	}
+
+	return
+}
+
+// Create creates a new capture for a payment.
+//
+// See: https://docs.mollie.com/reference/v2/captures-api/create-capture
+func (cs *CapturesService) Create(ctx context.Context, payment string, capture CreateCapture) (
+	res *Response,
+	c *Capture,
+	err error,
+) {
+	u := fmt.Sprintf("v2/payments/%s/captures", payment)
+
+	if cs.client.HasAccessToken() && cs.client.config.testing {
+		capture.Testmode = true
+	}
+
+	res, err = cs.client.post(ctx, u, capture, nil)
 	if err != nil {
 		return
 	}
@@ -65,10 +137,14 @@ func (cs *CapturesService) Get(ctx context.Context, payment, capture string) (re
 // List retrieves all captures for a certain payment.
 //
 // See: https://docs.mollie.com/reference/v2/captures-api/list-captures
-func (cs *CapturesService) List(ctx context.Context, payment string) (res *Response, cl *CapturesList, err error) {
+func (cs *CapturesService) List(ctx context.Context, payment string, options *CaptureOptions) (
+	res *Response,
+	cl *CapturesList,
+	err error,
+) {
 	u := fmt.Sprintf("v2/payments/%s/captures", payment)
 
-	res, err = cs.client.get(ctx, u, nil)
+	res, err = cs.client.get(ctx, u, options)
 	if err != nil {
 		return
 	}