currencycloud.go

// Package currencycloud provides a production-grade Go client for the
// Currencycloud v2 API (https://developer.currencycloud.com).
//
// This file is the only file in the root package. All implementation lives in
// sub-packages following DDD architecture:
//
//   - domain/*         — entities, value objects, repository interfaces
//   - infrastructure/* — HTTP transport, auth, config, API adapters
//   - internal/*       — private test helpers
//   - tests/*          — unit and integration test suites
//
// Quick start:
//
//	client, err := currencycloud.NewClient("user@example.com", "api-key",
//	    currencycloud.WithEnvironment(currencycloud.Production),
//	)
//	defer client.Logout(context.Background())
//	balance, _ := client.Balances.Get(ctx, "EUR")
//
//	// Sub-account scoping:
//	sub := client.OnBehalfOf("contact-uuid")
//	conv, _ := sub.Conversions.Create(ctx, conversion.CreateParams{...})
package currencycloud

import (
	"context"

	"github.com/iamkanishka/currencycloud-client-go/domain/account"
	"github.com/iamkanishka/currencycloud-client-go/domain/balance"
	"github.com/iamkanishka/currencycloud-client-go/domain/beneficiary"
	"github.com/iamkanishka/currencycloud-client-go/domain/contact"
	"github.com/iamkanishka/currencycloud-client-go/domain/conversion"
	"github.com/iamkanishka/currencycloud-client-go/domain/funding"
	"github.com/iamkanishka/currencycloud-client-go/domain/payment"
	"github.com/iamkanishka/currencycloud-client-go/domain/rate"
	"github.com/iamkanishka/currencycloud-client-go/domain/reference"
	"github.com/iamkanishka/currencycloud-client-go/domain/reporting"
	"github.com/iamkanishka/currencycloud-client-go/domain/shared"
	"github.com/iamkanishka/currencycloud-client-go/domain/transaction"
	"github.com/iamkanishka/currencycloud-client-go/domain/transfer"
	"github.com/iamkanishka/currencycloud-client-go/domain/webhook"
	infraapi "github.com/iamkanishka/currencycloud-client-go/infrastructure/api"
	"github.com/iamkanishka/currencycloud-client-go/infrastructure/auth"
	"github.com/iamkanishka/currencycloud-client-go/infrastructure/config"
	httpinfra "github.com/iamkanishka/currencycloud-client-go/infrastructure/http"
)

// ─── Configuration re-exports ─────────────────────────────────────────────────

// Environment selects the Currencycloud API environment.
type Environment = config.Environment

// Available environments.
const (
	// Demo is the sandbox environment (devapi.currencycloud.com).
	Demo Environment = config.Demo
	// Production is the live environment (api.currencycloud.com).
	Production Environment = config.Production
)

// Option is a functional option accepted by NewClient.
type Option = config.Option

// WithEnvironment sets the API environment. Default: Demo.
var WithEnvironment = config.WithEnvironment

// WithTimeout sets the HTTP request timeout. Default: 30s.
var WithTimeout = config.WithTimeout

// WithConnectTimeout sets the TCP dial timeout. Default: 5s.
var WithConnectTimeout = config.WithConnectTimeout

// WithMaxRetries sets the maximum retry attempts on transient errors. Default: 5.
var WithMaxRetries = config.WithMaxRetries

// WithRetryBaseDelay sets the initial exponential backoff delay. Default: 500ms.
var WithRetryBaseDelay = config.WithRetryBaseDelay

// WithRetryMaxDelay caps the exponential backoff delay. Default: 30s.
var WithRetryMaxDelay = config.WithRetryMaxDelay

// WithTokenRefreshBuffer sets how early to refresh the auth token. Default: 2m.
var WithTokenRefreshBuffer = config.WithTokenRefreshBuffer

// WithUserAgent overrides the HTTP User-Agent header.
var WithUserAgent = config.WithUserAgent

// WithMaxIdleConns sets the HTTP connection pool size. Default: 100.
var WithMaxIdleConns = config.WithMaxIdleConns

// WithBaseURL overrides the API base URL (for local/mock server testing).
var WithBaseURL = config.WithBaseURL

// ─── Domain param type aliases ────────────────────────────────────────────────

// CreateAccountParams holds data for creating a sub-account.
type CreateAccountParams = account.CreateParams

// UpdateAccountParams holds data for updating an account.
type UpdateAccountParams = account.UpdateParams

// FindAccountsParams holds filter criteria for Accounts.Find.
type FindAccountsParams = account.FilterParams

// FindBalancesParams holds filter criteria for Balances.Find.
type FindBalancesParams = balance.FilterParams

// CreateBeneficiaryParams holds data for creating a beneficiary.
type CreateBeneficiaryParams = beneficiary.CreateParams

// FindBeneficiariesParams holds filter criteria for Beneficiaries.Find.
type FindBeneficiariesParams = beneficiary.FilterParams

// VerifyBeneficiaryParams holds data for Confirmation of Payee.
type VerifyBeneficiaryParams = beneficiary.VerifyParams

// CreateContactParams holds data for creating a contact.
type CreateContactParams = contact.CreateParams

// FindContactsParams holds filter criteria for Contacts.Find.
type FindContactsParams = contact.FilterParams

// CreateConversionParams holds data for booking a conversion.
type CreateConversionParams = conversion.CreateParams

// FindConversionsParams holds filter criteria for Conversions.Find.
type FindConversionsParams = conversion.FilterParams

// FindProfitAndLossParams holds filter criteria for Conversions.ProfitAndLoss.
type FindProfitAndLossParams = conversion.ProfitAndLossParams

// CreatePaymentParams holds data for creating a payment.
type CreatePaymentParams = payment.CreateParams

// FindPaymentsParams holds filter criteria for Payments.Find.
type FindPaymentsParams = payment.FilterParams

// GetDeliveryDateParams holds data for Payments.GetDeliveryDate.
type GetDeliveryDateParams = payment.DeliveryDateParams

// BasicRateParams holds parameters for Rates.GetBasic.
type BasicRateParams = rate.BasicParams

// DetailedRateParams holds parameters for Rates.GetDetailed.
type DetailedRateParams = rate.DetailedParams

// BeneficiaryRequiredDetailsParams holds parameters for Reference.GetBeneficiaryRequiredDetails.
type BeneficiaryRequiredDetailsParams = reference.BeneficiaryRequiredDetailsParams

// ConversionDatesParams holds parameters for Reference.GetConversionDates.
type ConversionDatesParams = reference.ConversionDatesParams

// PaymentDatesParams holds parameters for Reference.GetPaymentDates.
type PaymentDatesParams = reference.PaymentDatesParams

// PayerRequiredDetailsParams holds parameters for Reference.GetPayerRequiredDetails.
type PayerRequiredDetailsParams = reference.PayerRequiredDetailsParams

// BankDetailsParams holds parameters for Reference.GetBankDetails.
type BankDetailsParams = reference.BankDetailsParams

// CreateTransferParams holds data for creating a transfer.
type CreateTransferParams = transfer.CreateParams

// FindTransfersParams holds filter criteria for Transfers.Find.
type FindTransfersParams = transfer.FilterParams

// FindTransactionsParams holds filter criteria for Transactions.Find.
type FindTransactionsParams = transaction.FilterParams

// FindFundingAccountsParams holds filter criteria for Funding.FindFundingAccounts.
type FindFundingAccountsParams = funding.FilterParams

// ─── Error type aliases ───────────────────────────────────────────────────────

// APIError is the base error embedded in all concrete API error types.
type APIError = shared.APIError

// FieldError is a per-field validation error returned by the API.
type FieldError = shared.FieldError

// AuthenticationError is returned on HTTP 401.
type AuthenticationError = shared.AuthenticationError

// ForbiddenError is returned on HTTP 403.
type ForbiddenError = shared.ForbiddenError

// BadRequestError is returned on HTTP 400.
type BadRequestError = shared.BadRequestError

// NotFoundError is returned on HTTP 404.
type NotFoundError = shared.NotFoundError

// TooManyRequestsError is returned on HTTP 429. Check RetryAfter.
type TooManyRequestsError = shared.TooManyRequestsError

// InternalServerError is returned on HTTP 5xx.
type InternalServerError = shared.InternalServerError

// NetworkError is returned on transport failures.
type NetworkError = shared.NetworkError

// UnexpectedError wraps any HTTP status not covered by the concrete types above.
type UnexpectedError = shared.UnexpectedError

// IsRetryable reports whether err is a transient error worth retrying.
var IsRetryable = shared.IsRetryable

// ─── Webhook helpers ──────────────────────────────────────────────────────────

// ErrInvalidSignature is returned by VerifyWebhook when the HMAC does not match.
var ErrInvalidSignature = webhook.ErrInvalidSignature

// ErrTimestampTooOld is returned by VerifyWebhook when the timestamp exceeds MaxAge.
var ErrTimestampTooOld = webhook.ErrTimestampTooOld

// ErrMissingHeaders is returned by VerifyWebhook when required headers are absent.
var ErrMissingHeaders = webhook.ErrMissingHeaders

// VerifyWebhook verifies the HMAC-SHA256 signature of an incoming webhook delivery.
var VerifyWebhook = webhook.Verify

// ComputeWebhookSignature computes the expected HMAC-SHA256 signature for a payload.
var ComputeWebhookSignature = webhook.ComputeSignature

// ParseWebhookPayload decodes a raw webhook body into a Payload struct.
var ParseWebhookPayload = webhook.Parse

// ─── HTTP param helpers ───────────────────────────────────────────────────────

// Params builds url.Values from alternating key/value string pairs,
// skipping pairs where the value is empty.
var Params = httpinfra.Params

// ParamsFromMap builds url.Values from a string map, skipping empty values.
var ParamsFromMap = httpinfra.FromMap

// ─── Client ───────────────────────────────────────────────────────────────────

// Client is the main API client. It is goroutine-safe and should be shared.
// All service groups expose domain repository interfaces directly, so callers
// can substitute mock implementations in tests.
type Client struct {
	// Accounts manages house and sub-accounts.
	Accounts account.Repository
	// Balances queries currency balances.
	Balances balance.Repository
	// Beneficiaries manages payment recipients.
	Beneficiaries beneficiary.Repository
	// Contacts manages account contacts.
	Contacts contact.Repository
	// Conversions manages FX trades.
	Conversions conversion.Repository
	// Funding provides inbound fund / SSI information.
	Funding funding.Repository
	// Payments manages outbound payments.
	Payments payment.Repository
	// Payers retrieves sender details for inbound payments.
	Payers *infraapi.PayerAdapter
	// Rates queries FX rates.
	Rates rate.Repository
	// Reference provides static lookup data.
	Reference reference.Repository
	// Reporting generates async conversion and payment reports.
	Reporting reporting.Repository
	// Transactions queries the unified ledger.
	Transactions transaction.Repository
	// Transfers moves funds between accounts.
	Transfers transfer.Repository
	// Withdrawals manages ACH pull-of-funds from linked US bank accounts.
	Withdrawals *infraapi.WithdrawalAdapter

	sess      *auth.Session
	cfg       *config.Config
	transport *httpinfra.Transport
}

// NewClient creates a Client from the given credentials and options.
// Authentication is lazy — the first API call triggers login.
//
//	client, err := currencycloud.NewClient(
//	    "user@example.com", "api-key",
//	    currencycloud.WithEnvironment(currencycloud.Production),
//	    currencycloud.WithTimeout(20*time.Second),
//	)
func NewClient(loginID, apiKey string, opts ...Option) (*Client, error) {
	cfg, err := config.New(loginID, apiKey, opts...)
	if err != nil {
		return nil, err
	}
	t := httpinfra.New(cfg)
	s := auth.New(cfg, t)
	return buildClient(cfg, t, s, ""), nil
}

// MustNewClient is like NewClient but panics on invalid configuration.
func MustNewClient(loginID, apiKey string, opts ...Option) *Client {
	c, err := NewClient(loginID, apiKey, opts...)
	if err != nil {
		panic(err)
	}
	return c
}

// OnBehalfOf returns a new Client scoped to the given contact UUID.
// The underlying session and transport are shared with the parent client.
func (c *Client) OnBehalfOf(contactID string) *Client {
	return buildClient(c.cfg, c.transport, c.sess, contactID)
}

// Logout closes the server-side session. Call via defer after NewClient.
func (c *Client) Logout(ctx context.Context) error {
	return c.sess.Logout(ctx)
}

func buildClient(cfg *config.Config, t *httpinfra.Transport, s *auth.Session, obo string) *Client {
	b := infraapi.NewBase(t, s, cfg, obo)
	return &Client{
		Accounts:      infraapi.NewAccountAdapter(b),
		Balances:      infraapi.NewBalanceAdapter(b),
		Beneficiaries: infraapi.NewBeneficiaryAdapter(b),
		Contacts:      infraapi.NewContactAdapter(b),
		Conversions:   infraapi.NewConversionAdapter(b),
		Funding:       infraapi.NewFundingAdapter(b),
		Payments:      infraapi.NewPaymentAdapter(b),
		Payers:        infraapi.NewPayerAdapter(b),
		Rates:         infraapi.NewRateAdapter(b),
		Reference:     infraapi.NewReferenceAdapter(b),
		Reporting:     infraapi.NewReportingAdapter(b),
		Transactions:  infraapi.NewTransactionAdapter(b),
		Transfers:     infraapi.NewTransferAdapter(b),
		Withdrawals:   infraapi.NewWithdrawalAdapter(b),
		sess:          s,
		cfg:           cfg,
		transport:     t,
	}
}