client

package module
v0.0.0-...-edbf9a4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 18, 2025 License: MIT Imports: 13 Imported by: 3

README ΒΆ

github.com/formancehq/stack/ledger/client

Developer-friendly & type-safe Go SDK specifically catered to leverage github.com/formancehq/stack/ledger/client API.

πŸ— Welcome to your new SDK! πŸ—

It has been generated successfully based on your OpenAPI spec. However, it is not yet ready for production use. Here are some next steps:

Summary

Table of Contents

SDK Installation

To add the SDK as a dependency to your project:

go get github.com/formancehq/ledger/pkg/client

SDK Example Usage

Example
package main

import (
	"context"
	"github.com/formancehq/ledger/pkg/client"
	"github.com/formancehq/ledger/pkg/client/models/components"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithSecurity(components.Security{
			ClientID:     client.String(os.Getenv("FORMANCE_CLIENT_ID")),
			ClientSecret: client.String(os.Getenv("FORMANCE_CLIENT_SECRET")),
		}),
	)

	res, err := s.Ledger.GetInfo(ctx)
	if err != nil {
		log.Fatal(err)
	}
	if res.V2ConfigInfoResponse != nil {
		// handle response
	}
}

Available Resources and Operations

Available methods
Ledger
Ledger.V1
Ledger.V2

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retry.Config object to the call by using the WithRetries option:

package main

import (
	"context"
	"github.com/formancehq/ledger/pkg/client"
	"github.com/formancehq/ledger/pkg/client/models/components"
	"github.com/formancehq/ledger/pkg/client/retry"
	"log"
	"models/operations"
	"os"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithSecurity(components.Security{
			ClientID:     client.String(os.Getenv("FORMANCE_CLIENT_ID")),
			ClientSecret: client.String(os.Getenv("FORMANCE_CLIENT_SECRET")),
		}),
	)

	res, err := s.Ledger.GetInfo(ctx, operations.WithRetries(
		retry.Config{
			Strategy: "backoff",
			Backoff: &retry.BackoffStrategy{
				InitialInterval: 1,
				MaxInterval:     50,
				Exponent:        1.1,
				MaxElapsedTime:  100,
			},
			RetryConnectionErrors: false,
		}))
	if err != nil {
		log.Fatal(err)
	}
	if res.V2ConfigInfoResponse != nil {
		// handle response
	}
}

If you'd like to override the default retry strategy for all operations that support retries, you can use the WithRetryConfig option at SDK initialization:

package main

import (
	"context"
	"github.com/formancehq/ledger/pkg/client"
	"github.com/formancehq/ledger/pkg/client/models/components"
	"github.com/formancehq/ledger/pkg/client/retry"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithRetryConfig(
			retry.Config{
				Strategy: "backoff",
				Backoff: &retry.BackoffStrategy{
					InitialInterval: 1,
					MaxInterval:     50,
					Exponent:        1.1,
					MaxElapsedTime:  100,
				},
				RetryConnectionErrors: false,
			}),
		client.WithSecurity(components.Security{
			ClientID:     client.String(os.Getenv("FORMANCE_CLIENT_ID")),
			ClientSecret: client.String(os.Getenv("FORMANCE_CLIENT_SECRET")),
		}),
	)

	res, err := s.Ledger.GetInfo(ctx)
	if err != nil {
		log.Fatal(err)
	}
	if res.V2ConfigInfoResponse != nil {
		// handle response
	}
}

Error Handling

Handling errors in this SDK should largely match your expectations. All operations return a response object or an error, they will never return both.

By Default, an API error will return sdkerrors.SDKError. When custom error responses are specified for an operation, the SDK may also return their associated error. You can refer to respective Errors tables in SDK docs for more details on possible error types for each operation.

For example, the GetInfo function may return the following errors:

Error Type Status Code Content Type
sdkerrors.V2ErrorResponse default application/json
sdkerrors.SDKError 4XX, 5XX */*
Example
package main

import (
	"context"
	"errors"
	"github.com/formancehq/ledger/pkg/client"
	"github.com/formancehq/ledger/pkg/client/models/components"
	"github.com/formancehq/ledger/pkg/client/models/sdkerrors"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithSecurity(components.Security{
			ClientID:     client.String(os.Getenv("FORMANCE_CLIENT_ID")),
			ClientSecret: client.String(os.Getenv("FORMANCE_CLIENT_SECRET")),
		}),
	)

	res, err := s.Ledger.GetInfo(ctx)
	if err != nil {

		var e *sdkerrors.V2ErrorResponse
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}

		var e *sdkerrors.SDKError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}
	}
}

Server Selection

Override Server URL Per-Client

The default server can be overridden globally using the WithServerURL(serverURL string) option when initializing the SDK client instance. For example:

package main

import (
	"context"
	"github.com/formancehq/ledger/pkg/client"
	"github.com/formancehq/ledger/pkg/client/models/components"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithServerURL("http://localhost:8080/"),
		client.WithSecurity(components.Security{
			ClientID:     client.String(os.Getenv("FORMANCE_CLIENT_ID")),
			ClientSecret: client.String(os.Getenv("FORMANCE_CLIENT_SECRET")),
		}),
	)

	res, err := s.Ledger.GetInfo(ctx)
	if err != nil {
		log.Fatal(err)
	}
	if res.V2ConfigInfoResponse != nil {
		// handle response
	}
}

Custom HTTP Client

The Go SDK makes API calls that wrap an internal HTTP client. The requirements for the HTTP client are very simple. It must match this interface:

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

The built-in net/http client satisfies this interface and a default client based on the built-in is provided by default. To replace this default with a client of your own, you can implement this interface yourself or provide your own client configured as desired. Here's a simple example, which adds a client with a 30 second timeout.

import (
	"net/http"
	"time"
	"github.com/myorg/your-go-sdk"
)

var (
	httpClient = &http.Client{Timeout: 30 * time.Second}
	sdkClient  = sdk.New(sdk.WithClient(httpClient))
)

This can be a convenient way to configure timeouts, cookies, proxies, custom headers, and other low-level configuration.

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

Name Type Scheme Environment Variable
ClientID
ClientSecret
oauth2 OAuth2 Client Credentials Flow FORMANCE_CLIENT_ID
FORMANCE_CLIENT_SECRET
FORMANCE_TOKEN_URL

You can configure it using the WithSecurity option when initializing the SDK client instance. For example:

package main

import (
	"context"
	"github.com/formancehq/ledger/pkg/client"
	"github.com/formancehq/ledger/pkg/client/models/components"
	"log"
	"os"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithSecurity(components.Security{
			ClientID:     client.String(os.Getenv("FORMANCE_CLIENT_ID")),
			ClientSecret: client.String(os.Getenv("FORMANCE_CLIENT_SECRET")),
		}),
	)

	res, err := s.Ledger.GetInfo(ctx)
	if err != nil {
		log.Fatal(err)
	}
	if res.V2ConfigInfoResponse != nil {
		// handle response
	}
}

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

SDK Created by Speakeasy

Documentation ΒΆ

Index ΒΆ

Constants ΒΆ

This section is empty.

Variables ΒΆ

View Source
var ServerList = []string{
	"http://localhost:8080/",
}

ServerList contains the list of servers available to the SDK

Functions ΒΆ

func Bool ΒΆ

func Bool(b bool) *bool

Bool provides a helper function to return a pointer to a bool

func Float32 ΒΆ

func Float32(f float32) *float32

Float32 provides a helper function to return a pointer to a float32

func Float64 ΒΆ

func Float64(f float64) *float64

Float64 provides a helper function to return a pointer to a float64

func Int ΒΆ

func Int(i int) *int

Int provides a helper function to return a pointer to an int

func Int64 ΒΆ

func Int64(i int64) *int64

Int64 provides a helper function to return a pointer to an int64

func Pointer ΒΆ

func Pointer[T any](v T) *T

Pointer provides a helper function to return a pointer to a type

func String ΒΆ

func String(s string) *string

String provides a helper function to return a pointer to a string

Types ΒΆ

type Formance ΒΆ

type Formance struct {
	SDKVersion string
	Ledger     *Ledger
	// contains filtered or unexported fields
}

func New ΒΆ

func New(opts ...SDKOption) *Formance

New creates a new instance of the SDK with the provided options

type HTTPClient ΒΆ

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPClient provides an interface for supplying the SDK with a custom HTTP client

type Ledger ΒΆ

type Ledger struct {
	V1 *V1
	V2 *V2
	// contains filtered or unexported fields
}

func (*Ledger) GetInfo ΒΆ

GetInfo - Show server information

func (*Ledger) GetMetrics ΒΆ

func (s *Ledger) GetMetrics(ctx context.Context, opts ...operations.Option) (*operations.GetMetricsResponse, error)

GetMetrics - Read in memory metrics

type SDKOption ΒΆ

type SDKOption func(*Formance)

func WithClient ΒΆ

func WithClient(client HTTPClient) SDKOption

WithClient allows the overriding of the default HTTP client used by the SDK

func WithRetryConfig ΒΆ

func WithRetryConfig(retryConfig retry.Config) SDKOption

func WithSecurity ΒΆ

func WithSecurity(security components.Security) SDKOption

WithSecurity configures the SDK to use the provided security details

func WithSecuritySource ΒΆ

func WithSecuritySource(security func(context.Context) (components.Security, error)) SDKOption

WithSecuritySource configures the SDK to invoke the Security Source function on each method call to determine authentication

func WithServerIndex ΒΆ

func WithServerIndex(serverIndex int) SDKOption

WithServerIndex allows the overriding of the default server by index

func WithServerURL ΒΆ

func WithServerURL(serverURL string) SDKOption

WithServerURL allows the overriding of the default server URL

func WithTemplatedServerURL ΒΆ

func WithTemplatedServerURL(serverURL string, params map[string]string) SDKOption

WithTemplatedServerURL allows the overriding of the default server URL with a templated URL populated with the provided parameters

func WithTimeout ΒΆ

func WithTimeout(timeout time.Duration) SDKOption

WithTimeout Optional request timeout applied to each operation

type V1 ΒΆ

type V1 struct {
	// contains filtered or unexported fields
}

func (*V1) AddMetadataOnTransaction ΒΆ

AddMetadataOnTransaction - Set the metadata of a transaction by its ID

func (*V1) AddMetadataToAccount ΒΆ

AddMetadataToAccount - Add metadata to an account

func (*V1) CountAccounts ΒΆ

CountAccounts - Count the accounts from a ledger

func (*V1) CountTransactions ΒΆ

CountTransactions - Count the transactions from a ledger

func (*V1) CreateTransaction ΒΆ

CreateTransaction - Create a new transaction to a ledger

func (*V1) CreateTransactions ΒΆ

CreateTransactions - Create a new batch of transactions to a ledger

func (*V1) GetAccount ΒΆ

GetAccount - Get account by its address

func (*V1) GetBalances ΒΆ

GetBalances - Get the balances from a ledger's account

func (*V1) GetBalancesAggregated ΒΆ

GetBalancesAggregated - Get the aggregated balances from selected accounts

func (*V1) GetInfo ΒΆ

func (s *V1) GetInfo(ctx context.Context, opts ...operations.Option) (*operations.GetInfoResponse, error)

GetInfo - Show server information

func (*V1) GetLedgerInfo ΒΆ

GetLedgerInfo - Get information about a ledger

func (*V1) GetMapping ΒΆ

GetMapping - Get the mapping of a ledger

func (*V1) GetTransaction ΒΆ

GetTransaction - Get transaction from a ledger by its ID

func (*V1) ListAccounts ΒΆ

ListAccounts - List accounts from a ledger List accounts from a ledger, sorted by address in descending order.

func (*V1) ListLogs ΒΆ

ListLogs - List the logs from a ledger List the logs from a ledger, sorted by ID in descending order.

func (*V1) ListTransactions ΒΆ

ListTransactions - List transactions from a ledger List transactions from a ledger, sorted by txid in descending order.

func (*V1) ReadStats ΒΆ

ReadStats - Get statistics from a ledger Get statistics from a ledger. (aggregate metrics on accounts and transactions)

func (*V1) RevertTransaction ΒΆ

RevertTransaction - Revert a ledger transaction by its ID

func (*V1) RunScript deprecated

RunScript - Execute a Numscript This route is deprecated, and has been merged into `POST /{ledger}/transactions`.

Deprecated: This will be removed in a future release, please migrate away from it as soon as possible.

func (*V1) UpdateMapping ΒΆ

UpdateMapping - Update the mapping of a ledger

type V2 ΒΆ

type V2 struct {
	// contains filtered or unexported fields
}

func (*V2) AddMetadataOnTransaction ΒΆ

AddMetadataOnTransaction - Set the metadata of a transaction by its ID

func (*V2) AddMetadataToAccount ΒΆ

AddMetadataToAccount - Add metadata to an account

func (*V2) CountAccounts ΒΆ

CountAccounts - Count the accounts from a ledger

func (*V2) CountTransactions ΒΆ

CountTransactions - Count the transactions from a ledger

func (*V2) CreateBulk ΒΆ

CreateBulk - Bulk request

func (*V2) CreateExporter ΒΆ

CreateExporter - Create exporter

func (*V2) CreateLedger ΒΆ

CreateLedger - Create a ledger

func (*V2) CreatePipeline ΒΆ

CreatePipeline - Create pipeline

func (*V2) CreateTransaction ΒΆ

CreateTransaction - Create a new transaction to a ledger

func (*V2) DeleteAccountMetadata ΒΆ

DeleteAccountMetadata - Delete metadata by key Delete metadata by key

func (*V2) DeleteExporter ΒΆ

DeleteExporter - Delete exporter

func (*V2) DeleteLedgerMetadata ΒΆ

DeleteLedgerMetadata - Delete ledger metadata by key

func (*V2) DeletePipeline ΒΆ

DeletePipeline - Delete pipeline

func (*V2) DeleteTransactionMetadata ΒΆ

DeleteTransactionMetadata - Delete metadata by key Delete metadata by key

func (*V2) ExportLogs ΒΆ

ExportLogs - Export logs

func (*V2) GetAccount ΒΆ

GetAccount - Get account by its address

func (*V2) GetBalancesAggregated ΒΆ

GetBalancesAggregated - Get the aggregated balances from selected accounts

func (*V2) GetExporterState ΒΆ

GetExporterState - Get exporter state

func (*V2) GetLedger ΒΆ

GetLedger - Get a ledger

func (*V2) GetLedgerInfo ΒΆ

GetLedgerInfo - Get information about a ledger

func (*V2) GetPipelineState ΒΆ

GetPipelineState - Get pipeline state

func (*V2) GetTransaction ΒΆ

GetTransaction - Get transaction from a ledger by its ID

func (*V2) GetVolumesWithBalances ΒΆ

GetVolumesWithBalances - Get list of volumes with balances for (account/asset)

func (*V2) ListAccounts ΒΆ

ListAccounts - List accounts from a ledger List accounts from a ledger, sorted by address in descending order.

func (*V2) ListExporters ΒΆ

func (s *V2) ListExporters(ctx context.Context, opts ...operations.Option) (*operations.V2ListExportersResponse, error)

ListExporters - List exporters

func (*V2) ListLedgers ΒΆ

ListLedgers - List ledgers

func (*V2) ListLogs ΒΆ

ListLogs - List the logs from a ledger List the logs from a ledger, sorted by ID in descending order.

func (*V2) ListPipelines ΒΆ

ListPipelines - List pipelines

func (*V2) ListTransactions ΒΆ

ListTransactions - List transactions from a ledger List transactions from a ledger, sorted by id in descending order.

func (*V2) ReadStats ΒΆ

ReadStats - Get statistics from a ledger Get statistics from a ledger. (aggregate metrics on accounts and transactions)

func (*V2) ResetPipeline ΒΆ

ResetPipeline - Reset pipeline

func (*V2) RevertTransaction ΒΆ

RevertTransaction - Revert a ledger transaction by its ID

func (*V2) StartPipeline ΒΆ

StartPipeline - Start pipeline

func (*V2) StopPipeline ΒΆ

StopPipeline - Stop pipeline

func (*V2) UpdateLedgerMetadata ΒΆ

UpdateLedgerMetadata - Update ledger metadata

Directories ΒΆ

Path Synopsis
internal
models

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL