robacarp / elixir-plaid

Simply beautiful elixir library for the Plaid API

Plaid Elixir Library

Simply Beautiful Elixir library for the Plaid API.

Motivation & Principles

1. Provide FANTASTIC documentation
2. Full plaid API coverage
3. Use the plaid API versioning plan
4. Return well-defined structs, always

Example Usage

# get auth data
Plaid.Auth.get("access-prod-123xxx", client_id: "123", secret: "abc")

# get item details
Plaid.Item.get("access-prod-123xxx", client_id: "123", secret: "abc", env: :production)

# refresh transactions
Plaid.Transactions.refresh("access-prod-123xxx", client_id: "123", secret: "abc", env: :development)

# get categories
Plaid.Categories.get(env: :production)

API

• Plaid.Accounts
• Plaid.AssetReport
• Plaid.Auth
• Plaid.Categories
• Plaid.Employer
• Plaid.Identity
• Plaid.Institution
• Plaid.Investments
• Plaid.Item
• Plaid.Liabilities
• Plaid.LinkToken
• Plaid.PaymentInitiation
• Plaid.Processor
• Plaid.Sandbox
• Plaid.Transactions
• Plaid.Webhooks

Full Documentation on HexDocs.

Configuration

Each function takes a Plaid.config keyword list as it's trailing argument. Authenticated requests require a client_id and secert at minimum for authentication with the plaid API.

Key	Value
:client_id	Your plaid client id. (required for authenticated requests)
:secret	Your plaid secret. (required for authenticated requests)
:env	Either :production, :development, or :sandbox. (defaults to :sandbox)
:http_client	Any module that implements the Plaid.Client behaviour. (defaults to Plaid.Client.HTTPoison)
:test_api_host	Any base URL e.g. http://localhost:2100/.

The choice to avoid using application configuration is due to the anti-pattern documented by elixir of libraries using application configuration. Passing configuration to each function avoids the library touching any global state, as well as making function calls objectively more "functional".

Likely you will need to pass keys dynamically anyway for development/production, overwriting the need for global application config. Therefore using patterns like those outlined in this blog post and using a test mocking library like Mox help aid in making code more clear.

Installation

Add elixir_plaid to your list of dependencies in mix.exs:

def deps do
  [
    {:elixir_plaid, "~> 1.0.0"}

    # optional, but recommended http client
    {:httpoison, "~> 1.7"}
  ]
end

Versioning

Each major version of elixir_plaid targets a specific version of the Plaid API:

API version	package version
2020-09-14 (latest)	1.x.x

For information about what has changed between API versions, head to the version changelog.

API Coverage

✅ - Full Coverage

🏗 - In Progress

🗺 - On the Roadmap

API	Status
Account	✅
Assets	✅
Auth	✅
Balance	✅
Bank Transfers (beta)	🗺
Deposit Switch (beta)	🗺
Employer	🏗
Identity	✅
Institution	✅
Investments	✅
Item	✅
Liabilities	✅
Payment Initiation (UK and Europe)	✅
Processor	✅
Sandbox	🏗
Token	✅
Transactions	✅
Webhooks	🏗

Contributing

Bug reports and pull requests are welcome on GitHub. See contributing guidelines for more details.

License

The package is available as open source under the terms of the MIT License.