fragment-ruby-sdk

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.

See CHANGELOG.md for release notes and upgrade guidance.

Installation

To install the Fragment SDK for Ruby, you'll need to install the gem. Run the following command in your terminal:

gem install fragment-dev

Or if you are using bundler add gem fragment-dev to your Gemfile.

Usage

To use the Fragment SDK in your Ruby application, first require the library:

require 'fragment_client'

Then instantiate a client by calling FragmentClient.new with the necessary credentials. You can generate credentials using the Fragment dashboard.

fragment = FragmentClient.new(
  'your-client-id',
  'your-client-secret',
  api_url: 'api url from dashboard',
  oauth_url: 'auth url from dashboard',
  oauth_scope: 'scope from dashboard'
)

Post a Ledger Entry

To post a Ledger Entry defined in your Schema:

fragment.add_ledger_entry({
  ik: "some-ik",
  ledgerIk: "your-ledger-ik",
  type: "user_funds_account",
  posted: "1968-01-01T16:45:00Z",
  parameters: {
    user_id: "user-1",
    funding_amount: "200",
  }
})

Post a batch of Ledger Entries

To post a batch of Ledger Entries atomically:

fragment.add_ledger_entries(entries: [
  FragmentClient::Entries::UserFundsAccountV1.new(
    ik: "some-ik-1",
    ledger_ik: "your-ledger-ik",
    posted: "1968-01-01T16:45:00Z",
    user_id: "user-1",
    funding_amount: "20000"
  ),
  FragmentClient::Entries::UserFundsAccountV1.new(
    ik: "some-ik-2",
    ledger_ik: "your-ledger-ik",
    posted: "1968-01-01T16:45:00Z",
    user_id: "user-2",
    funding_amount: "20000"
  )
])

Construct the entries in the batch using the typed payloads generated for your Schema, named <EntryType>V<typeVersion> under FragmentClient::Entries.

Payloads can also be registered without constructing a client — no credentials, no network:

FragmentClient::TypedEntries.load('app/graphql/entries.graphql')

Sorbet

The gem ships a Tapioca DSL compiler, so Sorbet can typecheck the payloads even though they are built at load time. Put a TypedEntries.load call somewhere Tapioca loads — a Rails initializer, or sorbet/tapioca/require.rb — then:

bundle exec tapioca dsl

That writes an RBI giving each payload a real signature. srb tc will then reject a wrong parameter type, a missing required parameter, and a parameter your Schema does not declare.

Sync Transactions

To sync transaction using a Custom Link:

fragment.sync_custom_accounts({
  linkId: "custom-link-id",
  accounts: [
    {
      externalId: "operating-account",
      name: "Operating Bank Account",
      currency: {
        code: "USD",
      },
    },
  ]
})

fragment.sync_custom_txs({
  linkId: "custom-link-id",
  txs: [
    {
      externalId: "tx-123",
      description: "Test user funding",
      account: {
        externalId: "operating-account",
        linkId: "custom-link-id",
      },
      amount: "100",
      currency: {
        code: "USD",
      },
      posted: "1968-01-01",
    },
  ]
})

Reconcile a Transaction

To reconcile a transaction:

fragment.reconcile_tx({
  ledgerIk: "your-ledger-ik",
  type: "funding_settlement",
  parameters: {
    user_id: "user-1",
    net_amount: "99",
    fee_amount: "1",
    link_id: "stripe",
    link_account_id: "stripe-balance",
    link_tx_id: "tx_456",
  }
})

Get a Schema

To retrieve a schema by its key and access the specific fields:

schema_response = fragment.get_schema({
  key: "schemaKey",
})
schema_key = schema_response.data.schema.key  # Assuming this remains in camelCase if it's a direct API response attribute

Get a Ledger

To retrieve a ledger and access its details:

ledger_response = fragment.get_ledger({
  ik: "your-ledger-ik",
})
ledger_details = ledger_response.data.ledger

Get a Ledger Entry

To fetch a specific ledger entry and access its data:

ledger_entry_response = fragment.get_ledger_entry({
  ik: "card_swipe_a",
  ledgerIk: "your-ledger-ik",
})
ledger_entry_details = ledger_entry_response.data.ledger_entry

Get a Ledger Account with Balance

To read a Ledger Account's balance:

ledger_account_balance_response = fragment.get_ledger_account_balance({
  ledgerIk: "your-ledger-ik",
  path: "assets/receivables/user:user-1",
})
account_balance = ledger_account_balance_response.data.ledger_account

List Ledger Accounts

To list all ledger accounts in a specific ledger and access the results:

result = fragment.list_ledger_accounts({
  ledgerIk: "your-ledger-ik",
})
ledger_accounts = result.data.ledger.ledger_accounts

Using Custom Queries

While the SDK comes with GraphQL queries out of the box, you may want to customize these queries for your product. To do that:

1. Define your custom GraphQL queries in a .graphql file. For example, in extra.graphql.

2. When creating the client, pass the extra_queries_filenames parameter to specify the paths to your custom GraphQL file:

fragment = FragmentClient.new(
  'your-client-id',
  'your-client-secret',
  api_url: 'api url from dashboard',
  oauth_url: 'auth url from dashboard',
  oauth_scope: 'scope from dashboard',
  extra_queries_filenames: ['path/to/your/extra.graphql']
)

This setup allows you to enhance your SDK usage with tailored queries, ensuring you can handle all your business-specific cases effectively.

Development

Requires Ruby >= 3.2, as the gemspec says; CI covers 3.2, 3.3 and 3.4.

bundle install
bundle exec rake       # the default task
bundle exec rake -T    # everything else

If your locale is not UTF-8, set one. GraphQL::Client.load_schema reads lib/fragment.schema.json, which carries non-ASCII currency names, and raises invalid byte sequence in US-ASCII under a US-ASCII default external encoding.

docs/spec-conformance.md maps this SDK onto the shared typed-batch-entries specification, and records where it deviates and why.