file.go

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

package increase

import (
	"bytes"
	"context"
	"errors"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"net/url"
	"slices"
	"time"

	"github.com/Increase/increase-go/internal/apiform"
	"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"
)

// FileService 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 [NewFileService] method instead.
type FileService struct {
	Options []option.RequestOption
}

// NewFileService 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 NewFileService(opts ...option.RequestOption) (r *FileService) {
	r = &FileService{}
	r.Options = opts
	return
}

// To upload a file to Increase, you'll need to send a request of Content-Type
// `multipart/form-data`. The request should contain the file you would like to
// upload, as well as the parameters for creating a file.
func (r *FileService) New(ctx context.Context, body FileNewParams, opts ...option.RequestOption) (res *File, err error) {
	opts = slices.Concat(r.Options, opts)
	path := "files"
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
	return res, err
}

// Retrieve a File
func (r *FileService) Get(ctx context.Context, fileID string, opts ...option.RequestOption) (res *File, err error) {
	opts = slices.Concat(r.Options, opts)
	if fileID == "" {
		err = errors.New("missing required file_id parameter")
		return nil, err
	}
	path := fmt.Sprintf("files/%s", fileID)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, nil, &res, opts...)
	return res, err
}

// List Files
func (r *FileService) List(ctx context.Context, query FileListParams, opts ...option.RequestOption) (res *pagination.Page[File], err error) {
	var raw *http.Response
	opts = slices.Concat(r.Options, opts)
	opts = append([]option.RequestOption{option.WithResponseInto(&raw)}, opts...)
	path := "files"
	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 Files
func (r *FileService) ListAutoPaging(ctx context.Context, query FileListParams, opts ...option.RequestOption) *pagination.PageAutoPager[File] {
	return pagination.NewPageAutoPager(r.List(ctx, query, opts...))
}

// Files are objects that represent a file hosted on Increase's servers. The file
// may have been uploaded by you (for example, when uploading a check image) or it
// may have been created by Increase (for example, an autogenerated statement PDF).
// If you need to download a File, create a File Link.
type File struct {
	// The File's identifier.
	ID string `json:"id" api:"required"`
	// The time the File was created.
	CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"`
	// A description of the File.
	Description string `json:"description" api:"required,nullable"`
	// Whether the File was generated by Increase or by you and sent to Increase.
	Direction FileDirection `json:"direction" api:"required"`
	// The filename that was provided upon upload or generated by Increase.
	Filename string `json:"filename" api:"required,nullable"`
	// 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 MIME type of the file.
	MimeType string `json:"mime_type" api:"required"`
	// What the File will be used for. We may add additional possible values for this
	// enum over time; your application should be able to handle such additions
	// gracefully.
	Purpose FilePurpose `json:"purpose" api:"required"`
	// A constant representing the object's type. For this resource it will always be
	// `file`.
	Type        FileType               `json:"type" api:"required"`
	ExtraFields map[string]interface{} `json:"-" api:"extrafields"`
	JSON        fileJSON               `json:"-"`
}

// fileJSON contains the JSON metadata for the struct [File]
type fileJSON struct {
	ID             apijson.Field
	CreatedAt      apijson.Field
	Description    apijson.Field
	Direction      apijson.Field
	Filename       apijson.Field
	IdempotencyKey apijson.Field
	MimeType       apijson.Field
	Purpose        apijson.Field
	Type           apijson.Field
	raw            string
	ExtraFields    map[string]apijson.Field
}

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

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

// Whether the File was generated by Increase or by you and sent to Increase.
type FileDirection string

const (
	FileDirectionToIncrease   FileDirection = "to_increase"
	FileDirectionFromIncrease FileDirection = "from_increase"
)

func (r FileDirection) IsKnown() bool {
	switch r {
	case FileDirectionToIncrease, FileDirectionFromIncrease:
		return true
	}
	return false
}

// What the File will be used for. We may add additional possible values for this
// enum over time; your application should be able to handle such additions
// gracefully.
type FilePurpose string

const (
	FilePurposeCardDisputeAttachment                 FilePurpose = "card_dispute_attachment"
	FilePurposeCheckImageFront                       FilePurpose = "check_image_front"
	FilePurposeCheckImageBack                        FilePurpose = "check_image_back"
	FilePurposeProcessedCheckImageFront              FilePurpose = "processed_check_image_front"
	FilePurposeProcessedCheckImageBack               FilePurpose = "processed_check_image_back"
	FilePurposeMailedCheckImage                      FilePurpose = "mailed_check_image"
	FilePurposeCheckAttachment                       FilePurpose = "check_attachment"
	FilePurposeCheckVoucherImage                     FilePurpose = "check_voucher_image"
	FilePurposeCheckSignature                        FilePurpose = "check_signature"
	FilePurposeInboundMailItem                       FilePurpose = "inbound_mail_item"
	FilePurposeForm1099Int                           FilePurpose = "form_1099_int"
	FilePurposeForm1099Misc                          FilePurpose = "form_1099_misc"
	FilePurposeFormSS4                               FilePurpose = "form_ss_4"
	FilePurposeIdentityDocument                      FilePurpose = "identity_document"
	FilePurposeIncreaseStatement                     FilePurpose = "increase_statement"
	FilePurposeLoanApplicationSupplementalDocument   FilePurpose = "loan_application_supplemental_document"
	FilePurposeOther                                 FilePurpose = "other"
	FilePurposeTrustFormationDocument                FilePurpose = "trust_formation_document"
	FilePurposeDigitalWalletArtwork                  FilePurpose = "digital_wallet_artwork"
	FilePurposeDigitalWalletAppIcon                  FilePurpose = "digital_wallet_app_icon"
	FilePurposePhysicalCardFront                     FilePurpose = "physical_card_front"
	FilePurposePhysicalCardBack                      FilePurpose = "physical_card_back"
	FilePurposePhysicalCardCarrier                   FilePurpose = "physical_card_carrier"
	FilePurposeDocumentRequest                       FilePurpose = "document_request"
	FilePurposeEntitySupplementalDocument            FilePurpose = "entity_supplemental_document"
	FilePurposeExport                                FilePurpose = "export"
	FilePurposeFeeStatement                          FilePurpose = "fee_statement"
	FilePurposeUnusualActivityReportAttachment       FilePurpose = "unusual_activity_report_attachment"
	FilePurposeDepositAccountControlAgreement        FilePurpose = "deposit_account_control_agreement"
	FilePurposeProofOfAuthorizationRequestSubmission FilePurpose = "proof_of_authorization_request_submission"
	FilePurposeAccountVerificationLetter             FilePurpose = "account_verification_letter"
	FilePurposeFundingInstructions                   FilePurpose = "funding_instructions"
	FilePurposeHoldHarmlessLetter                    FilePurpose = "hold_harmless_letter"
)

func (r FilePurpose) IsKnown() bool {
	switch r {
	case FilePurposeCardDisputeAttachment, FilePurposeCheckImageFront, FilePurposeCheckImageBack, FilePurposeProcessedCheckImageFront, FilePurposeProcessedCheckImageBack, FilePurposeMailedCheckImage, FilePurposeCheckAttachment, FilePurposeCheckVoucherImage, FilePurposeCheckSignature, FilePurposeInboundMailItem, FilePurposeForm1099Int, FilePurposeForm1099Misc, FilePurposeFormSS4, FilePurposeIdentityDocument, FilePurposeIncreaseStatement, FilePurposeLoanApplicationSupplementalDocument, FilePurposeOther, FilePurposeTrustFormationDocument, FilePurposeDigitalWalletArtwork, FilePurposeDigitalWalletAppIcon, FilePurposePhysicalCardFront, FilePurposePhysicalCardBack, FilePurposePhysicalCardCarrier, FilePurposeDocumentRequest, FilePurposeEntitySupplementalDocument, FilePurposeExport, FilePurposeFeeStatement, FilePurposeUnusualActivityReportAttachment, FilePurposeDepositAccountControlAgreement, FilePurposeProofOfAuthorizationRequestSubmission, FilePurposeAccountVerificationLetter, FilePurposeFundingInstructions, FilePurposeHoldHarmlessLetter:
		return true
	}
	return false
}

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

const (
	FileTypeFile FileType = "file"
)

func (r FileType) IsKnown() bool {
	switch r {
	case FileTypeFile:
		return true
	}
	return false
}

type FileNewParams struct {
	// The file contents. This should follow the specifications of
	// [RFC 7578](https://datatracker.ietf.org/doc/html/rfc7578) which defines file
	// transfers for the multipart/form-data protocol.
	File param.Field[io.Reader] `json:"file" api:"required" format:"binary"`
	// What the File will be used for in Increase's systems.
	Purpose param.Field[FileNewParamsPurpose] `json:"purpose" api:"required"`
	// The description you choose to give the File.
	Description param.Field[string] `json:"description"`
}

func (r FileNewParams) MarshalMultipart() (data []byte, contentType string, err error) {
	buf := bytes.NewBuffer(nil)
	writer := multipart.NewWriter(buf)
	err = apiform.MarshalRoot(r, writer)
	if err != nil {
		writer.Close()
		return nil, "", err
	}
	err = writer.Close()
	if err != nil {
		return nil, "", err
	}
	return buf.Bytes(), writer.FormDataContentType(), nil
}

// What the File will be used for in Increase's systems.
type FileNewParamsPurpose string

const (
	FileNewParamsPurposeCardDisputeAttachment                 FileNewParamsPurpose = "card_dispute_attachment"
	FileNewParamsPurposeCheckImageFront                       FileNewParamsPurpose = "check_image_front"
	FileNewParamsPurposeCheckImageBack                        FileNewParamsPurpose = "check_image_back"
	FileNewParamsPurposeMailedCheckImage                      FileNewParamsPurpose = "mailed_check_image"
	FileNewParamsPurposeCheckAttachment                       FileNewParamsPurpose = "check_attachment"
	FileNewParamsPurposeCheckVoucherImage                     FileNewParamsPurpose = "check_voucher_image"
	FileNewParamsPurposeCheckSignature                        FileNewParamsPurpose = "check_signature"
	FileNewParamsPurposeFormSS4                               FileNewParamsPurpose = "form_ss_4"
	FileNewParamsPurposeIdentityDocument                      FileNewParamsPurpose = "identity_document"
	FileNewParamsPurposeLoanApplicationSupplementalDocument   FileNewParamsPurpose = "loan_application_supplemental_document"
	FileNewParamsPurposeOther                                 FileNewParamsPurpose = "other"
	FileNewParamsPurposeTrustFormationDocument                FileNewParamsPurpose = "trust_formation_document"
	FileNewParamsPurposeDigitalWalletArtwork                  FileNewParamsPurpose = "digital_wallet_artwork"
	FileNewParamsPurposeDigitalWalletAppIcon                  FileNewParamsPurpose = "digital_wallet_app_icon"
	FileNewParamsPurposePhysicalCardFront                     FileNewParamsPurpose = "physical_card_front"
	FileNewParamsPurposePhysicalCardCarrier                   FileNewParamsPurpose = "physical_card_carrier"
	FileNewParamsPurposeDocumentRequest                       FileNewParamsPurpose = "document_request"
	FileNewParamsPurposeEntitySupplementalDocument            FileNewParamsPurpose = "entity_supplemental_document"
	FileNewParamsPurposeUnusualActivityReportAttachment       FileNewParamsPurpose = "unusual_activity_report_attachment"
	FileNewParamsPurposeProofOfAuthorizationRequestSubmission FileNewParamsPurpose = "proof_of_authorization_request_submission"
)

func (r FileNewParamsPurpose) IsKnown() bool {
	switch r {
	case FileNewParamsPurposeCardDisputeAttachment, FileNewParamsPurposeCheckImageFront, FileNewParamsPurposeCheckImageBack, FileNewParamsPurposeMailedCheckImage, FileNewParamsPurposeCheckAttachment, FileNewParamsPurposeCheckVoucherImage, FileNewParamsPurposeCheckSignature, FileNewParamsPurposeFormSS4, FileNewParamsPurposeIdentityDocument, FileNewParamsPurposeLoanApplicationSupplementalDocument, FileNewParamsPurposeOther, FileNewParamsPurposeTrustFormationDocument, FileNewParamsPurposeDigitalWalletArtwork, FileNewParamsPurposeDigitalWalletAppIcon, FileNewParamsPurposePhysicalCardFront, FileNewParamsPurposePhysicalCardCarrier, FileNewParamsPurposeDocumentRequest, FileNewParamsPurposeEntitySupplementalDocument, FileNewParamsPurposeUnusualActivityReportAttachment, FileNewParamsPurposeProofOfAuthorizationRequestSubmission:
		return true
	}
	return false
}

type FileListParams struct {
	CreatedAt param.Field[FileListParamsCreatedAt] `query:"created_at"`
	// Return the page of entries after this one.
	Cursor param.Field[string] `query:"cursor"`
	// 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"`
	// Limit the size of the list that is returned. The default (and maximum) is 100
	// objects.
	Limit   param.Field[int64]                 `query:"limit"`
	Purpose param.Field[FileListParamsPurpose] `query:"purpose"`
}

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

type FileListParamsCreatedAt 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 [FileListParamsCreatedAt]'s query parameters as
// `url.Values`.
func (r FileListParamsCreatedAt) URLQuery() (v url.Values) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatDots,
	})
}

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

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

type FileListParamsPurposeIn string

const (
	FileListParamsPurposeInCardDisputeAttachment                 FileListParamsPurposeIn = "card_dispute_attachment"
	FileListParamsPurposeInCheckImageFront                       FileListParamsPurposeIn = "check_image_front"
	FileListParamsPurposeInCheckImageBack                        FileListParamsPurposeIn = "check_image_back"
	FileListParamsPurposeInProcessedCheckImageFront              FileListParamsPurposeIn = "processed_check_image_front"
	FileListParamsPurposeInProcessedCheckImageBack               FileListParamsPurposeIn = "processed_check_image_back"
	FileListParamsPurposeInMailedCheckImage                      FileListParamsPurposeIn = "mailed_check_image"
	FileListParamsPurposeInCheckAttachment                       FileListParamsPurposeIn = "check_attachment"
	FileListParamsPurposeInCheckVoucherImage                     FileListParamsPurposeIn = "check_voucher_image"
	FileListParamsPurposeInCheckSignature                        FileListParamsPurposeIn = "check_signature"
	FileListParamsPurposeInInboundMailItem                       FileListParamsPurposeIn = "inbound_mail_item"
	FileListParamsPurposeInForm1099Int                           FileListParamsPurposeIn = "form_1099_int"
	FileListParamsPurposeInForm1099Misc                          FileListParamsPurposeIn = "form_1099_misc"
	FileListParamsPurposeInFormSS4                               FileListParamsPurposeIn = "form_ss_4"
	FileListParamsPurposeInIdentityDocument                      FileListParamsPurposeIn = "identity_document"
	FileListParamsPurposeInIncreaseStatement                     FileListParamsPurposeIn = "increase_statement"
	FileListParamsPurposeInLoanApplicationSupplementalDocument   FileListParamsPurposeIn = "loan_application_supplemental_document"
	FileListParamsPurposeInOther                                 FileListParamsPurposeIn = "other"
	FileListParamsPurposeInTrustFormationDocument                FileListParamsPurposeIn = "trust_formation_document"
	FileListParamsPurposeInDigitalWalletArtwork                  FileListParamsPurposeIn = "digital_wallet_artwork"
	FileListParamsPurposeInDigitalWalletAppIcon                  FileListParamsPurposeIn = "digital_wallet_app_icon"
	FileListParamsPurposeInPhysicalCardFront                     FileListParamsPurposeIn = "physical_card_front"
	FileListParamsPurposeInPhysicalCardBack                      FileListParamsPurposeIn = "physical_card_back"
	FileListParamsPurposeInPhysicalCardCarrier                   FileListParamsPurposeIn = "physical_card_carrier"
	FileListParamsPurposeInDocumentRequest                       FileListParamsPurposeIn = "document_request"
	FileListParamsPurposeInEntitySupplementalDocument            FileListParamsPurposeIn = "entity_supplemental_document"
	FileListParamsPurposeInExport                                FileListParamsPurposeIn = "export"
	FileListParamsPurposeInFeeStatement                          FileListParamsPurposeIn = "fee_statement"
	FileListParamsPurposeInUnusualActivityReportAttachment       FileListParamsPurposeIn = "unusual_activity_report_attachment"
	FileListParamsPurposeInDepositAccountControlAgreement        FileListParamsPurposeIn = "deposit_account_control_agreement"
	FileListParamsPurposeInProofOfAuthorizationRequestSubmission FileListParamsPurposeIn = "proof_of_authorization_request_submission"
	FileListParamsPurposeInAccountVerificationLetter             FileListParamsPurposeIn = "account_verification_letter"
	FileListParamsPurposeInFundingInstructions                   FileListParamsPurposeIn = "funding_instructions"
	FileListParamsPurposeInHoldHarmlessLetter                    FileListParamsPurposeIn = "hold_harmless_letter"
)

func (r FileListParamsPurposeIn) IsKnown() bool {
	switch r {
	case FileListParamsPurposeInCardDisputeAttachment, FileListParamsPurposeInCheckImageFront, FileListParamsPurposeInCheckImageBack, FileListParamsPurposeInProcessedCheckImageFront, FileListParamsPurposeInProcessedCheckImageBack, FileListParamsPurposeInMailedCheckImage, FileListParamsPurposeInCheckAttachment, FileListParamsPurposeInCheckVoucherImage, FileListParamsPurposeInCheckSignature, FileListParamsPurposeInInboundMailItem, FileListParamsPurposeInForm1099Int, FileListParamsPurposeInForm1099Misc, FileListParamsPurposeInFormSS4, FileListParamsPurposeInIdentityDocument, FileListParamsPurposeInIncreaseStatement, FileListParamsPurposeInLoanApplicationSupplementalDocument, FileListParamsPurposeInOther, FileListParamsPurposeInTrustFormationDocument, FileListParamsPurposeInDigitalWalletArtwork, FileListParamsPurposeInDigitalWalletAppIcon, FileListParamsPurposeInPhysicalCardFront, FileListParamsPurposeInPhysicalCardBack, FileListParamsPurposeInPhysicalCardCarrier, FileListParamsPurposeInDocumentRequest, FileListParamsPurposeInEntitySupplementalDocument, FileListParamsPurposeInExport, FileListParamsPurposeInFeeStatement, FileListParamsPurposeInUnusualActivityReportAttachment, FileListParamsPurposeInDepositAccountControlAgreement, FileListParamsPurposeInProofOfAuthorizationRequestSubmission, FileListParamsPurposeInAccountVerificationLetter, FileListParamsPurposeInFundingInstructions, FileListParamsPurposeInHoldHarmlessLetter:
		return true
	}
	return false
}