Packages

hipcall_sms

0.3.0
0.3.0 0.2.0

SMS SDK for different providers

HexDocs

Current section

2 Versions

Jump to
Readme
2 Versions
3 Dependencies
Dependants
Files
Activity
Hide whitespace

Compare versions

10 files changed
+390 additions
-10 deletions
  @@ -1,5 +1,9 @@
1 1 # Changelog
2 2
3 + ## v0.3.0 (2025-06-06)
4 +
5 + - Add `get_balance` function.
6 +
3 7 ## v0.2.0 (2025-06-06)
4 8
5 9 - Add Telnyx
  @@ -13,7 +13,7 @@ by adding `hipcall_sms` to your list of dependencies in `mix.exs`:
13 13 ```elixir
14 14 def deps do
15 15 [
16 - {:hipcall_sms, "~> 0.1.0"}
16 + {:hipcall_sms, "~> 0.2.0"}
17 17 ]
18 18 end
19 19 ```
  @@ -2,7 +2,7 @@
2 2 [{<<"GitHub">>,<<"https://github.com/hipcall/hipcall_sms">>},
3 3 {<<"Website">>,<<"https://www.hipcall.com/en/">>}]}.
4 4 {<<"name">>,<<"hipcall_sms">>}.
5 - {<<"version">>,<<"0.2.0">>}.
5 + {<<"version">>,<<"0.3.0">>}.
6 6 {<<"description">>,<<"SMS SDK for different providers">>}.
7 7 {<<"elixir">>,<<"~> 1.16">>}.
8 8 {<<"app">>,<<"hipcall_sms">>}.
  @@ -25,13 +25,15 @@
25 25 {<<"repository">>,<<"hexpm">>}]]}.
26 26 {<<"files">>,
27 27 [<<"lib">>,<<"lib/hipcall_sms.ex">>,<<"lib/hipcall_sms">>,
28 - <<"lib/hipcall_sms/http_client.ex">>,<<"lib/hipcall_sms/adapters">>,
28 + <<"lib/hipcall_sms/application.ex">>,<<"lib/hipcall_sms/adapter.ex">>,
29 + <<"lib/hipcall_sms/http_client">>,
30 + <<"lib/hipcall_sms/http_client/finch_client.ex">>,
31 + <<"lib/hipcall_sms/adapters">>,
29 32 <<"lib/hipcall_sms/adapters/iletimerkezi.ex">>,
30 33 <<"lib/hipcall_sms/adapters/telnyx.ex">>,
34 + <<"lib/hipcall_sms/adapters/test.ex">>,
31 35 <<"lib/hipcall_sms/adapters/twilio.ex">>,
32 - <<"lib/hipcall_sms/adapters/test.ex">>,<<"lib/hipcall_sms/adapter.ex">>,
33 - <<"lib/hipcall_sms/sms.ex">>,<<"lib/hipcall_sms/http_client">>,
34 - <<"lib/hipcall_sms/http_client/finch_client.ex">>,
35 - <<"lib/hipcall_sms/application.ex">>,<<".formatter.exs">>,<<"mix.exs">>,
36 - <<"README.md">>,<<"LICENSE.md">>,<<"CHANGELOG.md">>]}.
36 + <<"lib/hipcall_sms/http_client.ex">>,<<"lib/hipcall_sms/sms.ex">>,
37 + <<".formatter.exs">>,<<"mix.exs">>,<<"README.md">>,<<"LICENSE.md">>,
38 + <<"CHANGELOG.md">>]}.
37 39 {<<"build_tools">>,[<<"mix">>]}.
  @@ -41,6 +41,10 @@ defmodule HipcallSMS do
41 41
42 42 # Quick send
43 43 HipcallSMS.send_sms("+15551234567", "+15555555555", "Hello!")
44 +
45 + # Check account balance
46 + {:ok, balance} = HipcallSMS.get_balance()
47 + IO.puts("Current balance: " <> balance.balance <> " " <> balance.currency)
44 48 """
45 49
46 50 alias HipcallSMS.{SMS, Adapter}
  @@ -56,7 +60,7 @@ defmodule HipcallSMS do
56 60 ## Examples
57 61
58 62 iex> HipcallSMS.version()
59 - "0.2.0"
63 + "0.3.0"
60 64
61 65 """
62 66 @spec version() :: String.t()
  @@ -191,6 +195,67 @@ defmodule HipcallSMS do
191 195 deliver(sms, config)
192 196 end
193 197
198 + @doc """
199 + Gets the account balance from the configured SMS provider.
200 +
201 + This function retrieves the current account balance information from the provider's API.
202 + The response format may vary between providers but will be normalized to include
203 + common balance information.
204 +
205 + ## Parameters
206 +
207 + - `config` - Optional keyword list to override adapter configuration
208 +
209 + ## Returns
210 +
211 + - `{:ok, balance_info}` - Success with balance information map
212 + - `{:error, reason}` - Failure with error details
213 +
214 + ## Examples
215 +
216 + # Get balance with application config
217 + {:ok, balance} = HipcallSMS.get_balance()
218 +
219 + # With Telnyx configuration override
220 + config = [
221 + adapter: HipcallSMS.Adapters.Telnyx,
222 + api_key: "your_api_key"
223 + ]
224 + {:ok, balance} = HipcallSMS.get_balance(config)
225 + # => {:ok, %{balance: "300.00", currency: "USD", credit_limit: "100.00", ...}}
226 +
227 + # With Iletimerkezi configuration override
228 + config = [
229 + adapter: HipcallSMS.Adapters.Iletimerkezi,
230 + key: "your_key",
231 + hash: "your_hash"
232 + ]
233 + {:ok, balance} = HipcallSMS.get_balance(config)
234 + # => {:ok, %{balance: "0", sms_balance: "18343", currency: "TRY", ...}}
235 +
236 + ## Error Handling
237 +
238 + case HipcallSMS.get_balance() do
239 + {:ok, balance} ->
240 + IO.puts("Current balance: " <> balance.balance <> " " <> balance.currency)
241 + {:error, %{status: 401}} ->
242 + IO.puts("Authentication failed")
243 + {:error, %{status: 400, body: body}} ->
244 + IO.puts("Bad request: " <> inspect(body))
245 + {:error, reason} ->
246 + IO.puts("Failed to get balance: " <> inspect(reason))
247 + end
248 +
249 + """
250 + @spec get_balance(config()) :: {:ok, map()} | {:error, map()}
251 + def get_balance(config \\ []) do
252 + adapter = config[:adapter] || get_adapter()
253 + merged_config = merge_config(adapter, config)
254 +
255 + adapter.validate_config(merged_config)
256 + adapter.get_balance(merged_config)
257 + end
258 +
194 259 defp get_adapter do
195 260 Application.get_env(:hipcall_sms, :adapter) ||
196 261 raise ArgumentError, "No adapter configured. Please set :adapter in your config."
  @@ -124,6 +124,36 @@ defmodule HipcallSMS.Adapter do
124 124 """
125 125 @callback deliver(sms(), config()) :: delivery_result()
126 126
127 + @doc """
128 + Gets the account balance from the SMS provider.
129 +
130 + This callback retrieves the current account balance information from the provider's API.
131 + The response format may vary between providers but should include balance information.
132 +
133 + ## Parameters
134 +
135 + - `config` - Configuration keyword list with provider-specific settings
136 +
137 + ## Returns
138 +
139 + - `{:ok, balance_info}` - Success with balance information map
140 + - `{:error, reason}` - Failure with error details
141 +
142 + ## Examples
143 +
144 + # Get balance with application config
145 + {:ok, balance} = MyAdapter.get_balance([])
146 +
147 + # Get balance with runtime config override
148 + config_override = [
149 + adapter: HipcallSMS.Adapters.Telnyx,
150 + api_key: "runtime_api_key"
151 + ]
152 + {:ok, balance} = MyAdapter.get_balance(config_override)
153 +
154 + """
155 + @callback get_balance(config()) :: {:ok, map()} | {:error, map()}
156 +
127 157 @doc """
128 158 Validates the adapter configuration.
Loading more files…