fragment-go

Fragment is the Ledger API for engineers that move money. Stop wrangling payment tables, debugging balance errors, and hacking together data pipelines. Start shipping the features that make a difference.

Installation

This library requires Go 1.20+.

go get -u github.com/fragment-dev/fragment-go

Usage

To start issuing queries, you'll first need to create an auth.AuthenticatedContext. You can generate credentials using the Fragment dashboard.

import (
  "context"
  "fmt"
  "os"
  
  "github.com/fragment-dev/fragment-go/auth"
  "github.com/fragment-dev/fragment-go/queries"
)

func main() {
  // Create an authenticated context
  authenticatedContext, err := auth.GetAuthenticatedContext(
    context.Background(),
    &auth.GetTokenParams{
      ClientId:     "Client ID from Dashboard",
      ClientSecret: "Client Secret from Dashboard",
      Scope:        "OAuth Scope from Dashboard",
      AuthUrl:      "OAuth URL from Dashboard",
      ApiUrl:       "API URL from Dashboard",
    },
  )
  
  if err != nil {
    fmt.Println(err)
    os.Exit(1)
  }
  
  fmt.Println("Successfully Authenticated!")
  
  // Use one of the predefined queries available
  response, _ := queries.GetLedger(authenticatedContext, "your-ledger-ik")
  if response.Ledger != nil {
    fmt.Println("Retrieved Ledger " + response.Ledger.GetName())
  }
}

Read the Examples section to learn how to post a Ledger Entry and read balances.

We appreciate feedback; please open an issue with questions, bugs, or suggestions.

Using custom queries

While the SDK comes with predefined GraphQL queries, you may want to customize these queries for your product. In order to do that, run:

go run github.com/fragment-dev/fragment-go \
  --input <path-to-your-graphql-queries-file.graphql>
  --output <path-to-the-output.go>
  --package <package-name>

An end-to-end example

Say you're developing within the main package of your product and you have the following custom GraphQL query saved to queries.graphql.

query GetLatestSchema($key: SafeString!) {
  schema(schema: { key: $key }) {
    key
    name
    version {
      created
      version
      json
    }
  }
}

Run the SDK codegen to generate the code for your GraphQL query.

go run github.com/fragment-dev/fragment-go \
  --input queries.graphql
  --output queries.go
  --package main

This should generate a queries.go file in your current working directory. You can then issue the above GraphQL request by calling GetLatestSchema:

package main

import (
	"fmt"
)

func main() {
	response, _ := GetLatestSchema(
		authenticatedContext,
		"your-schema-key",
	)

	fmt.Println("Latest version of Schema is: ", response.Schema.GetVersion().Version)
	// Alternatively
	fmt.Println("Latest version of Schema is: ", response.Schema.Version.Version)
}

Examples

Post a Ledger Entry

To post a Ledger Entry defined in your schema:

package main

import (
	"encoding/json"
	"fmt"

	"github.com/fragment-dev/fragment-go/queries"
)

type UserFundsAccountParameters struct {
	FundingAmount string `json:"funding_amount"`
	UserId        string `json:"user_id"`
}

func main() {
	serializedParams, _ := json.Marshal(&UserFundsAccountParameters{
		FundingAmount: "100",
		UserId:        "user-1",
	})

	var posted string = "1968-01-01T16:45:00Z"
	response, _ := queries.AddLedgerEntry(
		authenticatedContext,
		"some-ik",
		"your-ledger-ik",
		"user_funds_account",
		&posted,
		json.RawMessage(&serializedParams),
		[]queries.LedgerEntryTagInput{},
		[]queries.LedgerEntryGroupInput{},
	)

	switch r := (response.AddLedgerEntry).(type) {
	case *queries.AddLedgerEntryAddLedgerEntryAddLedgerEntryResult:
		fmt.Println("Posted Entry with IK: ", v.Entry.Ik)
		break
	case *queries.AddLedgerEntryAddLedgerEntryInternalError:
	case *queries.AddLedgerEntryAddLedgerEntryBadRequestError:
		fmt.Println("Received error: ", v.Message)
		break
	}
}

Read a Ledger Account's balance

To read a Ledger Account's balance:

package main

import (
	"fmt"

	"github.com/fragment-dev/fragment-go/queries"
)

func main() {
	response, _ := queries.GetLedgerAccountBalance(
		authenticatedContext,
		"liabilities/user:user-1/available",
		"your-ledger-ik",
		&queries.CurrencyMatchInput{queries.CurrencyCodeUsd, nil},
		nil,
		nil,
	)

	fmt.Println("Latest balance of account is: ", response.LedgerAccount.OwnBalance)
}