account.go

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

package increase

import (
	"context"
	"errors"
	"fmt"
	"net/http"
	"net/url"
	"slices"
	"time"

	"github.com/Increase/increase-go/internal/apijson"
	"github.com/Increase/increase-go/internal/apiquery"
	"github.com/Increase/increase-go/internal/param"
	"github.com/Increase/increase-go/internal/requestconfig"
	"github.com/Increase/increase-go/option"
	"github.com/Increase/increase-go/packages/pagination"
)

// AccountService contains methods and other services that help with interacting
// with the increase API.
//
// Note, unlike clients, this service does not read variables from the environment
// automatically. You should not instantiate this service directly, and instead use
// the [NewAccountService] method instead.
type AccountService struct {
	Options []option.RequestOption
}

// NewAccountService generates a new service that applies the given options to each
// request. These options are applied after the parent client's options (if there
// is one), and before any request-specific options.
func NewAccountService(opts ...option.RequestOption) (r *AccountService) {
	r = &AccountService{}
	r.Options = opts
	return
}

// Create an Account
func (r *AccountService) New(ctx context.Context, body AccountNewParams, opts ...option.RequestOption) (res *Account, err error) {
	opts = slices.Concat(r.Options, opts)
	path := "accounts"
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
	return res, err
}

// Retrieve an Account
func (r *AccountService) Get(ctx context.Context, accountID string, opts ...option.RequestOption) (res *Account, err error) {
	opts = slices.Concat(r.Options, opts)
	if accountID == "" {
		err = errors.New("missing required account_id parameter")
		return nil, err
	}
	path := fmt.Sprintf("accounts/%s", accountID)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, nil, &res, opts...)
	return res, err
}

// Update an Account
func (r *AccountService) Update(ctx context.Context, accountID string, body AccountUpdateParams, opts ...option.RequestOption) (res *Account, err error) {
	opts = slices.Concat(r.Options, opts)
	if accountID == "" {
		err = errors.New("missing required account_id parameter")
		return nil, err
	}
	path := fmt.Sprintf("accounts/%s", accountID)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPatch, path, body, &res, opts...)
	return res, err
}

// List Accounts
func (r *AccountService) List(ctx context.Context, query AccountListParams, opts ...option.RequestOption) (res *pagination.Page[Account], err error) {
	var raw *http.Response
	opts = slices.Concat(r.Options, opts)
	opts = append([]option.RequestOption{option.WithResponseInto(&raw)}, opts...)
	path := "accounts"
	cfg, err := requestconfig.NewRequestConfig(ctx, http.MethodGet, path, query, &res, opts...)
	if err != nil {
		return nil, err
	}
	err = cfg.Execute()
	if err != nil {
		return nil, err
	}
	res.SetPageConfig(cfg, raw)
	return res, nil
}

// List Accounts
func (r *AccountService) ListAutoPaging(ctx context.Context, query AccountListParams, opts ...option.RequestOption) *pagination.PageAutoPager[Account] {
	return pagination.NewPageAutoPager(r.List(ctx, query, opts...))
}

// Retrieve the current and available balances for an account in minor units of the
// account's currency. Learn more about [account balances](/documentation/balance).
func (r *AccountService) Balance(ctx context.Context, accountID string, query AccountBalanceParams, opts ...option.RequestOption) (res *BalanceLookup, err error) {
	opts = slices.Concat(r.Options, opts)
	if accountID == "" {
		err = errors.New("missing required account_id parameter")
		return nil, err
	}
	path := fmt.Sprintf("accounts/%s/balance", accountID)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, query, &res, opts...)
	return res, err
}

// Close an Account
func (r *AccountService) Close(ctx context.Context, accountID string, opts ...option.RequestOption) (res *Account, err error) {
	opts = slices.Concat(r.Options, opts)
	if accountID == "" {
		err = errors.New("missing required account_id parameter")
		return nil, err
	}
	path := fmt.Sprintf("accounts/%s/close", accountID)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, nil, &res, opts...)
	return res, err
}

// Accounts are your bank accounts with Increase. They store money, receive
// transfers, and send payments. They earn interest and have depository insurance.
type Account struct {
	// The Account identifier.
	ID string `json:"id" api:"required"`
	// The account revenue rate currently being earned on the account, as a string
	// containing a decimal number. For example, a 1% account revenue rate would be
	// represented as "0.01". Account revenue is a type of non-interest income accrued
	// on the account.
	AccountRevenueRate string `json:"account_revenue_rate" api:"required,nullable"`
	// The bank the Account is with.
	Bank AccountBank `json:"bank" api:"required"`
	// The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) time at which the Account
	// was closed.
	ClosedAt time.Time `json:"closed_at" api:"required,nullable" format:"date-time"`
	// The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) time at which the Account
	// was created.
	CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"`
	// The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the Account
	// currency.
	Currency AccountCurrency `json:"currency" api:"required"`
	// The identifier for the Entity the Account belongs to.
	EntityID string `json:"entity_id" api:"required"`
	// Whether the Account is funded by a loan or by deposits.
	Funding AccountFunding `json:"funding" api:"required"`
	// The idempotency key you chose for this object. This value is unique across
	// Increase and is used to ensure that a request is only processed once. Learn more
	// about [idempotency](https://increase.com/documentation/idempotency-keys).
	IdempotencyKey string `json:"idempotency_key" api:"required,nullable"`
	// The identifier of an Entity that, while not owning the Account, is associated
	// with its activity.
	InformationalEntityID string `json:"informational_entity_id" api:"required,nullable"`
	// The interest rate currently being earned on the account, as a string containing
	// a decimal number. For example, a 1% interest rate would be represented as
	// "0.01".
	InterestRate string `json:"interest_rate" api:"required"`
	// The Account's loan-related information, if the Account is a loan account.
	Loan AccountLoan `json:"loan" api:"required,nullable"`
	// The name you choose for the Account.
	Name string `json:"name" api:"required"`
	// The identifier of the Program determining the compliance and commercial terms of
	// this Account.
	ProgramID string `json:"program_id" api:"required"`
	// The status of the Account.
	Status AccountStatus `json:"status" api:"required"`
	// A constant representing the object's type. For this resource it will always be
	// `account`.
	Type        AccountType            `json:"type" api:"required"`
	ExtraFields map[string]interface{} `json:"-" api:"extrafields"`
	JSON        accountJSON            `json:"-"`
}

// accountJSON contains the JSON metadata for the struct [Account]
type accountJSON struct {
	ID                    apijson.Field
	AccountRevenueRate    apijson.Field
	Bank                  apijson.Field
	ClosedAt              apijson.Field
	CreatedAt             apijson.Field
	Currency              apijson.Field
	EntityID              apijson.Field
	Funding               apijson.Field
	IdempotencyKey        apijson.Field
	InformationalEntityID apijson.Field
	InterestRate          apijson.Field
	Loan                  apijson.Field
	Name                  apijson.Field
	ProgramID             apijson.Field
	Status                apijson.Field
	Type                  apijson.Field
	raw                   string
	ExtraFields           map[string]apijson.Field
}

func (r *Account) UnmarshalJSON(data []byte) (err error) {
	return apijson.UnmarshalRoot(data, r)
}

func (r accountJSON) RawJSON() string {
	return r.raw
}

// The bank the Account is with.
type AccountBank string

const (
	AccountBankCoreBank          AccountBank = "core_bank"
	AccountBankFirstInternetBank AccountBank = "first_internet_bank"
	AccountBankGrasshopperBank   AccountBank = "grasshopper_bank"
)

func (r AccountBank) IsKnown() bool {
	switch r {
	case AccountBankCoreBank, AccountBankFirstInternetBank, AccountBankGrasshopperBank:
		return true
	}
	return false
}

// The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the Account
// currency.
type AccountCurrency string

const (
	AccountCurrencyUsd AccountCurrency = "USD"
)

func (r AccountCurrency) IsKnown() bool {
	switch r {
	case AccountCurrencyUsd:
		return true
	}
	return false
}

// Whether the Account is funded by a loan or by deposits.
type AccountFunding string

const (
	AccountFundingLoan     AccountFunding = "loan"
	AccountFundingDeposits AccountFunding = "deposits"
)

func (r AccountFunding) IsKnown() bool {
	switch r {
	case AccountFundingLoan, AccountFundingDeposits:
		return true
	}
	return false
}

// The Account's loan-related information, if the Account is a loan account.
type AccountLoan struct {
	// The maximum amount of money that can be borrowed on the Account.
	CreditLimit int64 `json:"credit_limit" api:"required"`
	// The number of days after the statement date that the Account can be past due
	// before being considered delinquent.
	GracePeriodDays int64 `json:"grace_period_days" api:"required"`
	// The date on which the loan matures.
	MaturityDate time.Time `json:"maturity_date" api:"required,nullable" format:"date"`
	// The day of the month on which the loan statement is generated.
	StatementDayOfMonth int64 `json:"statement_day_of_month" api:"required"`
	// The type of payment for the loan.
	StatementPaymentType AccountLoanStatementPaymentType `json:"statement_payment_type" api:"required"`
	JSON                 accountLoanJSON                 `json:"-"`
}

// accountLoanJSON contains the JSON metadata for the struct [AccountLoan]
type accountLoanJSON struct {
	CreditLimit          apijson.Field
	GracePeriodDays      apijson.Field
	MaturityDate         apijson.Field
	StatementDayOfMonth  apijson.Field
	StatementPaymentType apijson.Field
	raw                  string
	ExtraFields          map[string]apijson.Field
}

func (r *AccountLoan) UnmarshalJSON(data []byte) (err error) {
	return apijson.UnmarshalRoot(data, r)
}

func (r accountLoanJSON) RawJSON() string {
	return r.raw
}

// The type of payment for the loan.
type AccountLoanStatementPaymentType string

const (
	AccountLoanStatementPaymentTypeBalance               AccountLoanStatementPaymentType = "balance"
	AccountLoanStatementPaymentTypeInterestUntilMaturity AccountLoanStatementPaymentType = "interest_until_maturity"
)

func (r AccountLoanStatementPaymentType) IsKnown() bool {
	switch r {
	case AccountLoanStatementPaymentTypeBalance, AccountLoanStatementPaymentTypeInterestUntilMaturity:
		return true
	}
	return false
}

// The status of the Account.
type AccountStatus string

const (
	AccountStatusClosed AccountStatus = "closed"
	AccountStatusOpen   AccountStatus = "open"
)

func (r AccountStatus) IsKnown() bool {
	switch r {
	case AccountStatusClosed, AccountStatusOpen:
		return true
	}
	return false
}

// A constant representing the object's type. For this resource it will always be
// `account`.
type AccountType string

const (
	AccountTypeAccount AccountType = "account"
)

func (r AccountType) IsKnown() bool {
	switch r {
	case AccountTypeAccount:
		return true
	}
	return false
}

// Represents a request to lookup the balance of an Account at a given point in
// time.
type BalanceLookup struct {
	// The identifier for the account for which the balance was queried.
	AccountID string `json:"account_id" api:"required"`
	// The Account's available balance, representing the current balance less any open
	// Pending Transactions on the Account.
	AvailableBalance int64 `json:"available_balance" api:"required"`
	// The Account's current balance, representing the sum of all posted Transactions
	// on the Account.
	CurrentBalance int64 `json:"current_balance" api:"required"`
	// The loan balances for the Account.
	Loan BalanceLookupLoan `json:"loan" api:"required,nullable"`
	// A constant representing the object's type. For this resource it will always be
	// `balance_lookup`.
	Type BalanceLookupType `json:"type" api:"required"`
	JSON balanceLookupJSON `json:"-"`
}

// balanceLookupJSON contains the JSON metadata for the struct [BalanceLookup]
type balanceLookupJSON struct {
	AccountID        apijson.Field
	AvailableBalance apijson.Field
	CurrentBalance   apijson.Field
	Loan             apijson.Field
	Type             apijson.Field
	raw              string
	ExtraFields      map[string]apijson.Field
}

func (r *BalanceLookup) UnmarshalJSON(data []byte) (err error) {
	return apijson.UnmarshalRoot(data, r)
}

func (r balanceLookupJSON) RawJSON() string {
	return r.raw
}

// The loan balances for the Account.
type BalanceLookupLoan struct {
	// The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) time at which the loan
	// payment is due.
	DueAt time.Time `json:"due_at" api:"required,nullable" format:"date-time"`
	// The total amount due on the loan.
	DueBalance int64 `json:"due_balance" api:"required"`
	// The amount past due on the loan.
	PastDueBalance int64                 `json:"past_due_balance" api:"required"`
	JSON           balanceLookupLoanJSON `json:"-"`
}

// balanceLookupLoanJSON contains the JSON metadata for the struct
// [BalanceLookupLoan]
type balanceLookupLoanJSON struct {
	DueAt          apijson.Field
	DueBalance     apijson.Field
	PastDueBalance apijson.Field
	raw            string
	ExtraFields    map[string]apijson.Field
}

func (r *BalanceLookupLoan) UnmarshalJSON(data []byte) (err error) {
	return apijson.UnmarshalRoot(data, r)
}

func (r balanceLookupLoanJSON) RawJSON() string {
	return r.raw
}

// A constant representing the object's type. For this resource it will always be
// `balance_lookup`.
type BalanceLookupType string

const (
	BalanceLookupTypeBalanceLookup BalanceLookupType = "balance_lookup"
)

func (r BalanceLookupType) IsKnown() bool {
	switch r {
	case BalanceLookupTypeBalanceLookup:
		return true
	}
	return false
}

type AccountNewParams struct {
	// The name you choose for the Account.
	Name param.Field[string] `json:"name" api:"required"`
	// The identifier for the Entity that will own the Account.
	EntityID param.Field[string] `json:"entity_id"`
	// Whether the Account is funded by a loan or by deposits.
	Funding param.Field[AccountNewParamsFunding] `json:"funding"`
	// The identifier of an Entity that, while not owning the Account, is associated
	// with its activity. This is generally the beneficiary of the funds.
	InformationalEntityID param.Field[string] `json:"informational_entity_id"`
	// The loan details for the account.
	Loan param.Field[AccountNewParamsLoan] `json:"loan"`
	// The identifier for the Program that this Account falls under. Required if you
	// operate more than one Program.
	ProgramID param.Field[string] `json:"program_id"`
}

func (r AccountNewParams) MarshalJSON() (data []byte, err error) {
	return apijson.MarshalRoot(r)
}

// Whether the Account is funded by a loan or by deposits.
type AccountNewParamsFunding string

const (
	AccountNewParamsFundingLoan     AccountNewParamsFunding = "loan"
	AccountNewParamsFundingDeposits AccountNewParamsFunding = "deposits"
)

func (r AccountNewParamsFunding) IsKnown() bool {
	switch r {
	case AccountNewParamsFundingLoan, AccountNewParamsFundingDeposits:
		return true
	}
	return false
}

// The loan details for the account.
type AccountNewParamsLoan struct {
	// The maximum amount of money that can be drawn from the Account.
	CreditLimit param.Field[int64] `json:"credit_limit" api:"required"`
	// The number of days after the statement date that the Account can be past due
	// before being considered delinquent.
	GracePeriodDays param.Field[int64] `json:"grace_period_days" api:"required"`
	// The day of the month on which the loan statement is generated.
	StatementDayOfMonth param.Field[int64] `json:"statement_day_of_month" api:"required"`
	// The type of statement payment for the account.
	StatementPaymentType param.Field[AccountNewParamsLoanStatementPaymentType] `json:"statement_payment_type" api:"required"`
	// The date on which the loan matures.
	MaturityDate param.Field[time.Time] `json:"maturity_date" format:"date"`
}

func (r AccountNewParamsLoan) MarshalJSON() (data []byte, err error) {
	return apijson.MarshalRoot(r)
}

// The type of statement payment for the account.
type AccountNewParamsLoanStatementPaymentType string

const (
	AccountNewParamsLoanStatementPaymentTypeBalance               AccountNewParamsLoanStatementPaymentType = "balance"
	AccountNewParamsLoanStatementPaymentTypeInterestUntilMaturity AccountNewParamsLoanStatementPaymentType = "interest_until_maturity"
)

func (r AccountNewParamsLoanStatementPaymentType) IsKnown() bool {
	switch r {
	case AccountNewParamsLoanStatementPaymentTypeBalance, AccountNewParamsLoanStatementPaymentTypeInterestUntilMaturity:
		return true
	}
	return false
}

type AccountUpdateParams struct {
	// The loan details for the account.
	Loan param.Field[AccountUpdateParamsLoan] `json:"loan"`
	// The new name of the Account.
	Name param.Field[string] `json:"name"`
}

func (r AccountUpdateParams) MarshalJSON() (data []byte, err error) {
	return apijson.MarshalRoot(r)
}

// The loan details for the account.
type AccountUpdateParamsLoan struct {
	// The maximum amount of money that can be drawn from the Account.
	CreditLimit param.Field[int64] `json:"credit_limit" api:"required"`
}

func (r AccountUpdateParamsLoan) MarshalJSON() (data []byte, err error) {
	return apijson.MarshalRoot(r)
}

type AccountListParams struct {
	CreatedAt param.Field[AccountListParamsCreatedAt] `query:"created_at"`
	// Return the page of entries after this one.
	Cursor param.Field[string] `query:"cursor"`
	// Filter Accounts for those belonging to the specified Entity.
	EntityID param.Field[string] `query:"entity_id"`
	// Filter records to the one with the specified `idempotency_key` you chose for
	// that object. This value is unique across Increase and is used to ensure that a
	// request is only processed once. Learn more about
	// [idempotency](https://increase.com/documentation/idempotency-keys).
	IdempotencyKey param.Field[string] `query:"idempotency_key"`
	// Filter Accounts for those belonging to the specified Entity as informational.
	InformationalEntityID param.Field[string] `query:"informational_entity_id"`
	// Limit the size of the list that is returned. The default (and maximum) is 100
	// objects.
	Limit param.Field[int64] `query:"limit"`
	// Filter Accounts for those in a specific Program.
	ProgramID param.Field[string]                  `query:"program_id"`
	Status    param.Field[AccountListParamsStatus] `query:"status"`
}

// URLQuery serializes [AccountListParams]'s query parameters as `url.Values`.
func (r AccountListParams) URLQuery() (v url.Values) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatDots,
	})
}

type AccountListParamsCreatedAt struct {
	// Return results after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
	// timestamp.
	After param.Field[time.Time] `query:"after" format:"date-time"`
	// Return results before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
	// timestamp.
	Before param.Field[time.Time] `query:"before" format:"date-time"`
	// Return results on or after this
	// [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
	OnOrAfter param.Field[time.Time] `query:"on_or_after" format:"date-time"`
	// Return results on or before this
	// [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
	OnOrBefore param.Field[time.Time] `query:"on_or_before" format:"date-time"`
}

// URLQuery serializes [AccountListParamsCreatedAt]'s query parameters as
// `url.Values`.
func (r AccountListParamsCreatedAt) URLQuery() (v url.Values) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatDots,
	})
}

type AccountListParamsStatus struct {
	// Filter Accounts for those with the specified status. For GET requests, this
	// should be encoded as a comma-delimited string, such as `?in=one,two,three`.
	In param.Field[[]AccountListParamsStatusIn] `query:"in"`
}

// URLQuery serializes [AccountListParamsStatus]'s query parameters as
// `url.Values`.
func (r AccountListParamsStatus) URLQuery() (v url.Values) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatDots,
	})
}

type AccountListParamsStatusIn string

const (
	AccountListParamsStatusInClosed AccountListParamsStatusIn = "closed"
	AccountListParamsStatusInOpen   AccountListParamsStatusIn = "open"
)

func (r AccountListParamsStatusIn) IsKnown() bool {
	switch r {
	case AccountListParamsStatusInClosed, AccountListParamsStatusInOpen:
		return true
	}
	return false
}

type AccountBalanceParams struct {
	// The moment to query the balance at. If not set, returns the current balances.
	AtTime param.Field[time.Time] `query:"at_time" format:"date-time"`
}

// URLQuery serializes [AccountBalanceParams]'s query parameters as `url.Values`.
func (r AccountBalanceParams) URLQuery() (v url.Values) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatDots,
	})
}