feat(api): configure page_number pagination for the v3 list endpoints

Stainless-Generated-From: b8fa12b79cebbaaefde08f1f51edca776b39c285

Author: stlc-bot

README.md

@@ -295,9 +295,34 @@ This library provides some conveniences for working with paginated list endpoint
 
 You can use `.ListAutoPaging()` methods to iterate through items across all pages:
 
+```go
+iter := client.Webhooks.ListAutoPaging(context.TODO(), sentdm.WebhookListParams{})
+// Automatically fetches more pages as needed.
+for iter.Next() {
+	webhookResponse := iter.Current()
+	fmt.Printf("%+v\n", webhookResponse)
+}
+if err := iter.Err(); err != nil {
+	panic(err.Error())
+}
+```
+
 Or you can use simple `.List()` methods to fetch a single page and receive a standard response object
 with additional helper methods like `.GetNextPage()`, e.g.:
 
+```go
+page, err := client.Webhooks.List(context.TODO(), sentdm.WebhookListParams{})
+for page != nil {
+	for _, webhook := range page.Data.Webhooks {
+		fmt.Printf("%+v\n", webhook)
+	}
+	page, err = page.GetNextPage()
+}
+if err != nil {
+	panic(err.Error())
+}
+```
+
 ### Errors
 
 When the API returns a non-success status code, we return an error with type

api.md

@@ -16,6 +16,7 @@ import (
 	shimjson "github.com/sentdm/sent-dm-go/internal/encoding/json"
 	"github.com/sentdm/sent-dm-go/internal/requestconfig"
 	"github.com/sentdm/sent-dm-go/option"
+	"github.com/sentdm/sent-dm-go/packages/pagination"
 	"github.com/sentdm/sent-dm-go/packages/param"
 	"github.com/sentdm/sent-dm-go/packages/respjson"
 )
@@ -101,14 +102,30 @@ func (r *ContactService) Update(ctx context.Context, id string, params ContactUp
 
 // Retrieves a paginated list of contacts for the authenticated customer. Supports
 // filtering by search term, channel, or phone number.
-func (r *ContactService) List(ctx context.Context, params ContactListParams, opts ...option.RequestOption) (res *ContactListResponse, err error) {
+func (r *ContactService) List(ctx context.Context, params ContactListParams, opts ...option.RequestOption) (res *pagination.ContactsPage[ContactResponse], err error) {
+	var raw *http.Response
 	if !param.IsOmitted(params.XProfileID) {
 		opts = append(opts, option.WithHeader("x-profile-id", fmt.Sprintf("%v", params.XProfileID.Value)))
 	}
 	opts = slices.Concat(r.Options, opts)
+	opts = append([]option.RequestOption{option.WithResponseInto(&raw)}, opts...)
 	path := "v3/contacts"
-	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, params, &res, opts...)
-	return res, err
+	cfg, err := requestconfig.NewRequestConfig(ctx, http.MethodGet, path, params, &res, opts...)
+	if err != nil {
+		return nil, err
+	}
+	err = cfg.Execute()
+	if err != nil {
+		return nil, err
+	}
+	res.SetPageConfig(cfg, raw)
+	return res, nil
+}
+
+// Retrieves a paginated list of contacts for the authenticated customer. Supports
+// filtering by search term, channel, or phone number.
+func (r *ContactService) ListAutoPaging(ctx context.Context, params ContactListParams, opts ...option.RequestOption) *pagination.ContactsPageAutoPager[ContactResponse] {
+	return pagination.NewContactsPageAutoPager(r.List(ctx, params, opts...))
 }
 
 // **Deprecated.** Use `PATCH /v3/contacts/{id}` with `{"opt_out": true}` instead,
@@ -325,54 +342,6 @@ func (r *ContactResponse) UnmarshalJSON(data []byte) error {
 	return apijson.UnmarshalRoot(data, r)
 }
 
-// Standard API response envelope for all v3 endpoints
-type ContactListResponse struct {
-	// A paginated list of contacts.
-	Data ContactListResponseData `json:"data" api:"nullable"`
-	// Error information
-	Error ErrorDetail `json:"error" api:"nullable"`
-	// Request and response metadata
-	Meta APIMeta `json:"meta"`
-	// Indicates whether the request was successful
-	Success bool `json:"success"`
-	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
-	JSON struct {
-		Data        respjson.Field
-		Error       respjson.Field
-		Meta        respjson.Field
-		Success     respjson.Field
-		ExtraFields map[string]respjson.Field
-		raw         string
-	} `json:"-"`
-}
-
-// Returns the unmodified JSON received from the API
-func (r ContactListResponse) RawJSON() string { return r.JSON.raw }
-func (r *ContactListResponse) UnmarshalJSON(data []byte) error {
-	return apijson.UnmarshalRoot(data, r)
-}
-
-// A paginated list of contacts.
-type ContactListResponseData struct {
-	// The contacts on this page.
-	Contacts []ContactResponse `json:"contacts"`
-	// Pagination metadata for list responses
-	Pagination PaginationMeta `json:"pagination"`
-	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
-	JSON struct {
-		Contacts    respjson.Field
-		Pagination  respjson.Field
-		ExtraFields map[string]respjson.Field
-		raw         string
-	} `json:"-"`
-}
-
-// Returns the unmodified JSON received from the API
-func (r ContactListResponseData) RawJSON() string { return r.JSON.raw }
-func (r *ContactListResponseData) UnmarshalJSON(data []byte) error {
-	return apijson.UnmarshalRoot(data, r)
-}
-
 type ContactNewParams struct {
 	// Phone number of the contact to create
 	PhoneNumber string `json:"phone_number" api:"required"`
@@ -420,16 +389,16 @@ func (r *ContactUpdateParams) UnmarshalJSON(data []byte) error {
 }
 
 type ContactListParams struct {
-	// Page number (1-indexed)
-	Page int64 `query:"page" api:"required" json:"-"`
-	// Number of items per page
-	PageSize int64 `query:"page_size" api:"required" json:"-"`
 	// Optional channel filter (sms, whatsapp)
 	Channel param.Opt[string] `query:"channel,omitzero" json:"-"`
 	// Optional phone number filter (alternative to list view)
 	Phone param.Opt[string] `query:"phone,omitzero" json:"-"`
 	// Optional search term for filtering contacts
-	Search     param.Opt[string] `query:"search,omitzero" json:"-"`
+	Search param.Opt[string] `query:"search,omitzero" json:"-"`
+	// Page number (1-indexed)
+	Page param.Opt[int64] `query:"page,omitzero" json:"-"`
+	// Number of items per page
+	PageSize   param.Opt[int64]  `query:"page_size,omitzero" json:"-"`
 	XProfileID param.Opt[string] `header:"x-profile-id,omitzero" format:"uuid" json:"-"`
 	paramObj
 }

contact.go

@@ -117,9 +117,9 @@ func TestContactListWithOptionalParams(t *testing.T) {
 		option.WithAPIKey("My API Key"),
 	)
 	_, err := client.Contacts.List(context.TODO(), sentdm.ContactListParams{
-		Page:       0,
-		PageSize:   0,
 		Channel:    sentdm.String("channel"),
+		Page:       sentdm.Int(0),
+		PageSize:   sentdm.Int(0),
 		Phone:      sentdm.String("phone"),
 		Search:     sentdm.String("search"),
 		XProfileID: sentdm.String("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"),

contact_test.go

@@ -15,6 +15,7 @@ import (
 	"github.com/sentdm/sent-dm-go/internal/apiquery"
 	"github.com/sentdm/sent-dm-go/internal/requestconfig"
 	"github.com/sentdm/sent-dm-go/option"
+	"github.com/sentdm/sent-dm-go/packages/pagination"
 	"github.com/sentdm/sent-dm-go/packages/param"
 	"github.com/sentdm/sent-dm-go/packages/respjson"
 )
@@ -49,30 +50,62 @@ func NewConversationService(opts ...option.RequestOption) (r ConversationService
 
 // Retrieves a paginated list of the authenticated customer's messages across all
 // conversations, ordered by created date (most recent first).
-func (r *ConversationService) List(ctx context.Context, params ConversationListParams, opts ...option.RequestOption) (res *APIResponseOfConversationMessagesList, err error) {
+func (r *ConversationService) List(ctx context.Context, params ConversationListParams, opts ...option.RequestOption) (res *pagination.ConversationsPage[ConversationMessagesListMessage], err error) {
+	var raw *http.Response
 	if !param.IsOmitted(params.XProfileID) {
 		opts = append(opts, option.WithHeader("x-profile-id", fmt.Sprintf("%v", params.XProfileID.Value)))
 	}
 	opts = slices.Concat(r.Options, opts)
+	opts = append([]option.RequestOption{option.WithResponseInto(&raw)}, opts...)
 	path := "v3/conversations"
-	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, params, &res, opts...)
-	return res, err
+	cfg, err := requestconfig.NewRequestConfig(ctx, http.MethodGet, path, params, &res, opts...)
+	if err != nil {
+		return nil, err
+	}
+	err = cfg.Execute()
+	if err != nil {
+		return nil, err
+	}
+	res.SetPageConfig(cfg, raw)
+	return res, nil
+}
+
+// Retrieves a paginated list of the authenticated customer's messages across all
+// conversations, ordered by created date (most recent first).
+func (r *ConversationService) ListAutoPaging(ctx context.Context, params ConversationListParams, opts ...option.RequestOption) *pagination.ConversationsPageAutoPager[ConversationMessagesListMessage] {
+	return pagination.NewConversationsPageAutoPager(r.List(ctx, params, opts...))
 }
 
 // Retrieves a paginated list of the messages in a single conversation (scoped to
 // the authenticated customer), ordered by created date (most recent first).
-func (r *ConversationService) ListMessages(ctx context.Context, id string, params ConversationListMessagesParams, opts ...option.RequestOption) (res *APIResponseOfConversationMessagesList, err error) {
+func (r *ConversationService) ListMessages(ctx context.Context, id string, params ConversationListMessagesParams, opts ...option.RequestOption) (res *pagination.ConversationsPage[ConversationMessagesListMessage], err error) {
+	var raw *http.Response
 	if !param.IsOmitted(params.XProfileID) {
 		opts = append(opts, option.WithHeader("x-profile-id", fmt.Sprintf("%v", params.XProfileID.Value)))
 	}
 	opts = slices.Concat(r.Options, opts)
+	opts = append([]option.RequestOption{option.WithResponseInto(&raw)}, opts...)
 	if id == "" {
 		err = errors.New("missing required id parameter")
 		return nil, err
 	}
 	path := fmt.Sprintf("v3/conversations/%s", id)
-	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, params, &res, opts...)
-	return res, err
+	cfg, err := requestconfig.NewRequestConfig(ctx, http.MethodGet, path, params, &res, opts...)
+	if err != nil {
+		return nil, err
+	}
+	err = cfg.Execute()
+	if err != nil {
+		return nil, err
+	}
+	res.SetPageConfig(cfg, raw)
+	return res, nil
+}
+
+// Retrieves a paginated list of the messages in a single conversation (scoped to
+// the authenticated customer), ordered by created date (most recent first).
+func (r *ConversationService) ListMessagesAutoPaging(ctx context.Context, id string, params ConversationListMessagesParams, opts ...option.RequestOption) *pagination.ConversationsPageAutoPager[ConversationMessagesListMessage] {
+	return pagination.NewConversationsPageAutoPager(r.ListMessages(ctx, id, params, opts...))
 }
 
 // Standard API response envelope for all v3 endpoints
@@ -242,8 +275,8 @@ func (r *ConversationMessagesListMessageMessageBodyButton) UnmarshalJSON(data []
 }
 
 type ConversationListParams struct {
-	Page       int64             `query:"page" api:"required" json:"-"`
-	PageSize   int64             `query:"page_size" api:"required" json:"-"`
+	Page       param.Opt[int64]  `query:"page,omitzero" json:"-"`
+	PageSize   param.Opt[int64]  `query:"page_size,omitzero" json:"-"`
 	XProfileID param.Opt[string] `header:"x-profile-id,omitzero" format:"uuid" json:"-"`
 	paramObj
 }
@@ -257,8 +290,8 @@ func (r ConversationListParams) URLQuery() (v url.Values, err error) {
 }
 
 type ConversationListMessagesParams struct {
-	Page       int64             `query:"page" api:"required" json:"-"`
-	PageSize   int64             `query:"page_size" api:"required" json:"-"`
+	Page       param.Opt[int64]  `query:"page,omitzero" json:"-"`
+	PageSize   param.Opt[int64]  `query:"page_size,omitzero" json:"-"`
 	XProfileID param.Opt[string] `header:"x-profile-id,omitzero" format:"uuid" json:"-"`
 	paramObj
 }

conversation.go

@@ -27,8 +27,8 @@ func TestConversationListWithOptionalParams(t *testing.T) {
 		option.WithAPIKey("My API Key"),
 	)
 	_, err := client.Conversations.List(context.TODO(), sentdm.ConversationListParams{
-		Page:       0,
-		PageSize:   0,
+		Page:       sentdm.Int(0),
+		PageSize:   sentdm.Int(0),
 		XProfileID: sentdm.String("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"),
 	})
 	if err != nil {
@@ -57,8 +57,8 @@ func TestConversationListMessagesWithOptionalParams(t *testing.T) {
 		context.TODO(),
 		"08fab313-c9e2-502c-975e-08b0356c432e",
 		sentdm.ConversationListMessagesParams{
-			Page:       0,
-			PageSize:   0,
+			Page:       sentdm.Int(0),
+			PageSize:   sentdm.Int(0),
 			XProfileID: sentdm.String("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"),
 		},
 	)