Knock

Knock API access for applications written in Elixir.

Documentation

See the package documentation as well as API documentation for usage examples.

Installation

Add the package to your mix.exs file as follows:

def deps do
  [
    {:knock, "~> 0.4"}
  ]
end

Configuration

Start by defining an Elixir module for your Knock instance:

defmodule MyApp.Knock do
  use Knock, otp_app: :my_app
end

To use the library you must provide a secret API key, provided in the Knock dashboard.

You can set it as an environment variable:

KNOCK_API_KEY="sk_12345"

Or you can specify it manually in your configuration:

config :my_app, MyApp.Knock,
  api_key: "sk_12345"

Or you can pass it through when creating a client instance:

knock_client = MyApp.Knock.client(api_key: "sk_12345")

Usage

Identifying users

MyApp.Knock.client()
|> Knock.Users.identify("jhammond", %{
  "name" => "John Hammond",
  "email" => "jhammond@ingen.net",
})

Retrieving users

MyApp.Knock.client()
|> Knock.Users.get_user("jhammond")

Sending notifies

MyApp.Knock.client()
|> Knock.notify("dinosaurs-loose", %{
  # user id of who performed the action
  "actor" => "dnedry",
  # list of user ids for who should receive the notif
  "recipients" => ["jhammond", "agrant", "imalcolm", "esattler"],
  # an optional cancellation key
  "cancellation_key" => alert.id,
  # an optional tenant
  "tenant" => "jurassic-park",
  # data payload to send through
  "data" => %{
    "type" => "trex",
    "priority" => 1,
  },
})

User preferences

client = MyApp.Knock.client()

# Set preference set for user
Knock.Users.set_preferences(client, "jhammond", %{channel_types: %{email: true}})

# Set granular channel type preferences
Knock.Users.set_channel_type_preferences(client, "jhammond", :email, true)

# Set granular workflow preferences
Knock.Users.set_workflow_preferences(client, "jhammond", "dinosaurs-loose", %{
  channel_types: %{email: true}
})

# Retrieve preferences
Knock.Users.get_preferences(client, "jhammond")

Getting and setting channel data

client = MyApp.Knock.client()

# Set channel data for an APNS
Knock.Users.set_channel_data(client, "jhammond", KNOCK_APNS_CHANNEL_ID, %{
  tokens: [apns_token],
})

# Get channel data for the APNS channel
Knock.Users.get_channel_data(client, "jhammond", KNOCK_APNS_CHANNEL_ID)

Canceling notifies

MyApp.Knock.client()
|> Knock.Workflows.cancel("dinosaurs-loose", alert.id, %{
  # optional list of user ids for who should have their notify canceled
  "recipients" => ["jhammond", "agrant", "imalcolm", "esattler"],
})

Signing JWTs

You can use the excellent joken package to sign JWTs easily. You will need to generate an environment specific signing key, which you can find in the Knock dashboard.

If you're using a signing token you will need to pass this to your client to perform authentication. You can read more about clientside authentication here.

priv = System.get_env("KNOCK_SIGNING_KEY")
now = DateTime.utc_now()

claims = %{
  # The user id to sign this key for
  "sub" => user_id,
  # When the token was issued
  "iat" => DateTime.to_unix(now),
  # When the token expires (1 hour)
  "exp" => DateTime.add(now, 3600, :seconds) |> DateTime.to_unix()
}


signer = Joken.Signer.create("RS256", %{"pem" => priv})
{:ok, token, _} = Joken.generate_and_sign(%{}, claims, signer)

matt-glover/knock-elixir