open_payments

# Gleam Open Payments SDK

[![Package Version](https://img.shields.io/hexpm/v/open_payments)](https://hex.pm/packages/open_payments)
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://open-payments.hexdocs.pm/)

[Open Payments](https://openpayments.dev/) SDK for Gleam.

```sh
gleam add open_payments@2
```

```gleam
import gleam/option.{None, Some}
import open_payments/client
import open_payments/grants.{Grant, GrantOptions}
import open_payments/incoming_payment
import open_payments/types.{AccessIncoming, Amount, IncomingCreate}
import open_payments/wallet_address

pub fn main() -> Nil {
  let assert Ok(client) =
    client.create(
      "https://ilp.interledger-test.dev/michaelusd",
      "be52ffa9-b61b-4a8c-8dbe-43b75cda31c9",
      "fixtures/private_key",
    )
  let receiver_address = "https://ilp.interledger-test.dev/michaeleur"

  let assert Ok(receiver_info) = wallet_address.get(receiver_address)

  let incoming_grant_options =
    GrantOptions(
      auth_server_url: receiver_info.auth_server,
      access: [AccessIncoming([IncomingCreate], Some(receiver_address))],
      interact: None,
      client_type: None,
      subject: None,
    )
  let assert Ok(Grant(access_token: incoming_token, ..)) =
    grants.request(client, incoming_grant_options)

  let incoming_payment_options =
    incoming_payment.CreateOptions(
      resource_server: receiver_info.resource_server,
      wallet_address: receiver_address,
      incoming_amount: Some(Amount(
        "10000",
        receiver_info.asset_code,
        receiver_info.asset_scale,
      )),
      expires_at: None,
      metadata: None,
    )
  let assert Ok(payment) =
    incoming_payment.create(
      client,
      incoming_token.value,
      incoming_payment_options,
    )
  echo payment

  Nil
}
```

Note that this example only creates an incoming payment, and no outgoing payment. Check the `test/sdk_example.gleam` file for a full end-to-end example.

Further documentation can be found at <https://open-payments.hexdocs.pm/>.

## Versioning

The Open Payments specification still gains new response fields, so adding a
field to a response type, such as `IncomingPayment`, is a minor version change
and not a breaking one. Fields can be added anywhere in a type.

To keep your code compiling across minor versions, read response fields by name
(`payment.id`), or pattern match on just the fields you need, with labels and
`..`:

```gleam
let IncomingPayment(id:, completed:, ..) = payment
```

A new field breaks positional patterns, patterns that list every field, and code
that builds response types itself, so avoid these. Gleam doesn't allow `..` in a
pattern that already lists every field, so if you need all of them, read them by
name instead.

## Development

```sh
gleam test  # Run the tests
```

Running `gleam run -m sdk_example` executes `test/sdk_example.gleam`, which sends signed
requests against a real Open Payments wallet, so it needs credentials for a
wallet you control:

- Create `fixtures/private_key` (git-ignored, not committed) with the PEM
  private key matching a public key registered on your wallet address.
- In `test/sdk_example.gleam`, update the wallet address and key ID passed to
  `client.create` to match your own wallet address and the ID of the key you
  registered there — the ones currently in the file are specific to the
  original author's test wallet and will fail signature verification for
  anyone else.