transactionep

type CreateTransactionEndpoint struct{}

type CreateTransactionRequest struct {
	// ID of the customer the transaction is recorded against.
	CustomerID string `json:"customer_id" validate:"required"`
	// Transaction type code.
	//
	// - `payment`: money received from the customer.
	// - `credit_memo`: a credit issued to the customer.
	// - `adjustment`: a manual correction (also provide `adjustment_type`).
	// - `rebate`: a rebate granted to the customer.
	TransactionTypeCode constants.TransactionType `json:"type" validate:"required"`
	// Transaction amount as a decimal string, in US dollars.
	Amount string `json:"amount" validate:"required"`
	// How the money moved.
	//
	// Typically provided for payment transactions.
	TransactionMethodCode field.Optional[constants.TransactionMethod] `json:"method,omitzero" validate:"omitempty"`
	// The kind of correction this transaction represents (see List Adjustment Types for available values).
	//
	// Typically provided when `type` is `adjustment`.
	AdjustmentTypeCode field.Optional[string] `json:"adjustment_type,omitzero" validate:"omitempty,max=255"`
	// ID of the account user responsible for the transaction.
	//
	// When omitted, the account user making the request is recorded as responsible.
	ResponsibleUserID field.Optional[string] `json:"responsible_user_id,omitzero" validate:"omitempty"`
	// Free-form note attached to the transaction.
	Note field.Optional[string] `json:"note,omitzero"`
}

type DeleteTransactionEndpoint struct{}

type DeleteTransactionRequest struct {
	// Transaction ID.
	TransactionID string `path:"id" validate:"required"`
}

type ListAccountTransactionsEndpoint struct{}

type ListAccountTransactionsRequest struct {
	apiresource.PaginationRequest
	// Customer account ID.
	CustomerAccountID string `path:"account_id" validate:"required"`
	// Filter by allocation status: `allocated` (marked fully applied to invoices) or `unallocated` (still counted as an open credit).
	Status *constants.TransactionAllocationStatus `query:"status"`
	// Filter by transaction type code.
	Type *constants.TransactionType `query:"type"`
}

type ListAdjustmentTypesEndpoint struct{}

type ListAdjustmentTypesRequest struct {
	apiresource.PaginationRequest
}

type ListTransactionMethodsEndpoint struct{}

type ListTransactionMethodsRequest struct {
	apiresource.PaginationRequest
}

type ListTransactionTypesEndpoint struct{}

type ListTransactionTypesRequest struct {
	apiresource.PaginationRequest
}

type ListTransactionsEndpoint struct{}

type ListTransactionsRequest struct {
	apiresource.PaginationRequest
	// Filter by allocation status: `allocated` (marked fully applied to invoices) or `unallocated` (still counted as an open credit).
	Status *constants.TransactionAllocationStatus `query:"status"`
	// Filter by transaction type codes.
	TypeCodes []constants.TransactionType `query:"types"`
	// Filter by adjustment type codes (see List Adjustment Types for available values).
	AdjustmentTypeCodes []string `query:"adjustment_types"`
	// Filter by payment method codes.
	MethodCodes []constants.TransactionMethod `query:"methods"`
	// Filter by customer IDs.
	CustomerIDs []string `query:"customer_ids"`
	// Filter by the account group each customer belongs to.
	CustomerGroupIDs []string `query:"customer_group_ids"`
	// Only include transactions created on or after this date (`YYYY-MM-DD`).
	StartDate *string `query:"starts_at"`
	// Only include transactions created on or before this date (`YYYY-MM-DD`), covering that whole day.
	EndDate *string `query:"ends_at"`
}

type RetrieveTransactionEndpoint struct{}

type RetrieveTransactionRequest struct {
	// Transaction ID.
	TransactionID string `path:"id" validate:"required"`
	// Sub-resources to include in the response.
	Includes []string `include:"true"`
}

type TransactionSvc interface {
	ListTransactions(ctx context.Context, req *ListTransactionsRequest) (*apiresource.List[apiresource.TransactionSummary], *apierror.APIError)
	GetTransaction(ctx context.Context, req *RetrieveTransactionRequest) (*apiresource.TransactionDetail, *apierror.APIError)
	CreateTransaction(ctx context.Context, req *CreateTransactionRequest) (*apiresource.TransactionDetail, *apierror.APIError)
	UpdateTransaction(ctx context.Context, req *UpdateTransactionRequest) (*apiresource.TransactionDetail, *apierror.APIError)
	DeleteTransaction(ctx context.Context, req *DeleteTransactionRequest) (*apiresource.TransactionDetail, *apierror.APIError)
	ListAccountTransactions(ctx context.Context, req *ListAccountTransactionsRequest) (*apiresource.List[apiresource.TransactionDetail], *apierror.APIError)
	ListTransactionTypes(ctx context.Context, req *ListTransactionTypesRequest) (*apiresource.List[apiresource.TransactionType], *apierror.APIError)
	ListTransactionMethods(ctx context.Context, req *ListTransactionMethodsRequest) (*apiresource.List[apiresource.TransactionMethod], *apierror.APIError)
	ListAdjustmentTypes(ctx context.Context, req *ListAdjustmentTypesRequest) (*apiresource.List[apiresource.AdjustmentType], *apierror.APIError)
}

type TransactionSvcConfig struct {
	// CoreClient (required) is the core-service gRPC client.
	CoreClient pb.CoreServiceClient
}

type UpdateTransactionEndpoint struct{}

type UpdateTransactionRequest struct {
	// Transaction ID.
	TransactionID string `path:"id" validate:"required"`
	// New transaction number.
	//
	// Must be unique within the account; the request fails with a conflict error if another transaction already uses it.
	Number field.Optional[string] `json:"number,omitzero" validate:"omitempty,max=255"`
	// Free-form note attached to the transaction.
	Note field.Optional[string] `json:"note,omitzero"`
	// New transaction amount as a decimal string, in US dollars.
	Amount field.Optional[string] `json:"amount,omitzero"`
	// How the money moved.
	TransactionMethodCode field.Optional[constants.TransactionMethod] `json:"method,omitzero" validate:"omitempty"`
	// The kind of correction this transaction represents (see List Adjustment Types for available values).
	AdjustmentTypeCode field.Optional[string] `json:"adjustment_type,omitzero" validate:"omitempty,max=255"`
	// ID of the account user responsible for the transaction.
	//
	// A user ID is also accepted; the value is resolved to an account user in the current account.
	ResponsibleUserID field.Optional[string] `json:"responsible_user_id,omitzero" validate:"omitempty"`
	// Set to true to clear the responsible user.
	//
	// Takes precedence over `responsible_user_id` if both are provided.
	ClearResponsibleUser bool `json:"clear_responsible_user"`
	// Set to true to clear the transaction method.
	//
	// Takes precedence over `method` if both are provided.
	ClearTransactionMethod bool `json:"clear_transaction_method"`
	// Set to true to clear the adjustment type.
	//
	// Takes precedence over `adjustment_type` if both are provided.
	ClearAdjustmentType bool `json:"clear_adjustment_type"`
	// Whether the full transaction amount has been applied to invoices.
	//
	// Set this to correct the flag by hand: editing or deleting individual allocations never recomputes it. While it is `false`, the transaction is returned by List Open Credits.
	IsFullyAllocated field.Optional[bool] `json:"is_fully_allocated,omitzero"`
}