Quickstart

The FRAGMENT development workflow is a four-step process:

  1. Design your Schema
  2. Generate an SDK
  3. Deploy your Ledger
  4. Integrate the API

Design your Schema

A Schema customizes a FRAGMENT Ledger for a specific use-case. Download this toy Schema to begin the quickstart:

quickstart-schema.json
↓
{
  "key": "quickstart-schema",
  "chartOfAccounts": {
    "defaultConsistencyConfig": {
      "totalBalanceUpdates": "strong"
    },
    "defaultCurrencyMode": "multi",
    "accounts": [
      {
        "key": "assets",
        "type": "asset"
      },
      {
        "key": "liabilities",
        "type": "liability"
      },
      {
        "key": "income",
        "type": "income"
      },
      {
        "key": "expense",
        "type": "expense"
      }
    ]
  },
  "ledgerEntries": {
    "types": [
      {
        "type": "simple-entry",
        "lines": [
          {
            "key": "line-WPZ6bsw08YyW",
            "account": {
              "path": "assets"
            },
            "currency": {
              "code": "USD"
            },
            "amount": "{{gross_amount}}"
          },
          {
            "key": "line-m4spJaQWFqnw",
            "account": {
              "path": "liabilities"
            },
            "currency": {
              "code": "USD"
            },
            "amount": "{{gross_amount}}-{{fee_revenue}}"
          },
          {
            "key": "line-bvZiWSE69k4m",
            "account": {
              "path": "income"
            },
            "currency": {
              "code": "USD"
            },
            "amount": "{{fee_revenue}}"
          }
        ]
      }
    ]
  },
  "scenes": [
    {
      "name": "Simple Scenario",
      "events": [
        {
          "eventType": "entry",
          "entry": {
            "type": "simple-entry",
            "typeVersion": 1,
            "parameters": {
              "fee_revenue": "250",
              "gross_amount": "10000"
            }
          }
        }
      ]
    }
  ]
}
 

Generate an SDK

Generate a strongly-typed SDK specific to your Schema using the FRAGMENT CLI.

  1. Install the CLI via NPM or Homebrew:

    npm
    npm install -g @fragment-dev/cli
    homebrew
    brew tap fragment-dev/tap &&\
  brew install fragment-dev/tap/fragment-cli

  2. Authenticate the CLI against your FRAGMENT workspace:

    fragment login

  3. Generate an SDK for your language:

    fragment gen-graphql \
  --path=quickstart-schema.jsonc \
  --output=queries.graphql &&\
npm install --save @fragment-dev/node-client &&\
npx fragment-node-client-codegen \
  --input=queries.graphql \
  --outputFilename=fragment-client.ts

  4. Create an API client in the dashboard.

  5. Initialize your FRAGMENT client using the generated SDK and API client credentials:

    import {
  createFragmentClient
} from '@fragment-dev/node-client';
import {
  getSdk
} from './fragment-client';

const fragment = createFragmentClient({
  params: {
    clientId: "<Client ID>",
    clientSecret: "<Client Secret>",
    apiUrl: "<API URL>",
    authUrl: "<OAuth URL>",
    scope: "<OAuth Scope>",
  },
  getSdk,
});

Deploy your Ledger

To deploy your Ledger:

  1. Store the Schema
  2. Create a Ledger from the Schema
import { readFileSync } from 'node:fs';

// Load the Schema you downloaded with `fragment get-schema`.
const schema = JSON.parse(
  readFileSync('quickstart-schema.jsonc', 'utf8')
);

const { storeSchema } = await fragment.storeSchema({
  schema,
})

const { createLedger } = await fragment.createLedger({
  ik: `test-ledger`,
  ledger: {
    name: `quickstart ledger`,
  },
  schemaKey: schema.key,
})

Integrate the API

Begin integrating the API into your product by:

  1. Posting a Ledger Entry
  2. Reading a Ledger Account's balance
import { ReadBalanceConsistencyMode } from '@fragment-dev/node-client/types';
// Post the `simple-entry` Ledger Entry type
// with the required parameters
const { addLedgerEntry } = await fragment.PostSimpleEntry({
  ik: `quickstart-entry`,
  // The Ledger the Ledger Entry should post to.
  ledgerIk: `test-ledger`,
  gross_amount: '10000', // $100.00
  fee_revenue: '250', // $2.50
})

const { ledgerAccount } = await fragment.getLedgerAccountBalance({
  ledgerIk: `test-ledger`,
  path: `income`,
  balanceConsistencyMode: ReadBalanceConsistencyMode.Strong,
})

console.log(ledgerAccount.balance);

Next Steps