Shopifex.ManagedInstall.Callbacks behaviour (Shopifex v3.0.0)

Copy Markdown View Source

Extensibility hooks for the managed-installation flow (Shopifex.Plug.ManagedInstall).

Managed installation runs inside a plug, before any controller, so it cannot use ShopifexWeb.AuthController's insert_shop/1 and after_install/3 callbacks (those only apply to the legacy OAuth controller flow). Instead, configure a callback module here to customise how a newly token-exchanged shop is persisted and what side effects run on first install:

config :shopifex,
  managed_install_callbacks: MyApp.ManagedInstallCallbacks

defmodule MyApp.ManagedInstallCallbacks do
  use Shopifex.ManagedInstall.Callbacks

  @impl true
  def insert_shop(attrs) do
    # enforce single-tenant, attach defaults, etc.
    Shopifex.Shops.create_shop(attrs)
  end

  @impl true
  def after_install(shop) do
    # fetch shop profile, send yourself an email, take a baseline snapshot…
    :ok
  end
end

All callbacks are optional — use Shopifex.ManagedInstall.Callbacks provides defaults (insert_shop/1 delegates to Shopifex.Shops.create_shop/1, after_install/1 and after_exchange/2 are no-ops). The plug always configures webhooks itself on first install. On re-exchange it reconciles webhooks too, but only when config :shopifex, :configure_webhooks_on_exchange? is not set to false (default true); either way, :webhook_topics set to [] disables registration entirely.

When each hook runs

HookFirst installToken re-exchange (refresh)
insert_shop/1✅— (updates the row in place)
after_install/1✅—
after_exchange/2✅✅

Use after_exchange/2 for side effects that must run on refreshes too (it receives new?); use after_install/1 for one-time install work.

Callbacks run synchronously inside the plug, in the merchant's request and while the per-shop Shopifex.TokenRefreshLease is still held. Anything slow (a profile fetch, snapshot, external sync) will block the page load — spawn your own supervised Task for it. The library does not wrap callbacks in a Task. Do not call Shopifex.Auth.refresh/1 for the same shop from a hook: it would wait out the lease deadline and return {:error, :refresh_in_progress}.

Summary

Callbacks

Run app-specific side effects after every successful token exchange — both first install (new? is true) and a refresh re-exchange (new? is false). Defaults to a no-op. Use this for work that must also happen on refreshes (e.g. re-sync external state), where after_install/1 would only fire once.

Run app-specific side effects after a shop is installed for the first time (after persistence and webhook configuration). Defaults to a no-op.

Persist a brand-new shop from the token-exchange attributes and return the shop record. Defaults to Shopifex.Shops.create_shop/1.

Callbacks

after_exchange(shop, new?)

@callback after_exchange(shop :: Shopifex.Plug.shop(), new? :: boolean()) :: any()

Run app-specific side effects after every successful token exchange — both first install (new? is true) and a refresh re-exchange (new? is false). Defaults to a no-op. Use this for work that must also happen on refreshes (e.g. re-sync external state), where after_install/1 would only fire once.

after_install(shop)

@callback after_install(shop :: Shopifex.Plug.shop()) :: any()

Run app-specific side effects after a shop is installed for the first time (after persistence and webhook configuration). Defaults to a no-op.

insert_shop(attrs)

@callback insert_shop(attrs :: map()) :: Shopifex.Plug.shop()

Persist a brand-new shop from the token-exchange attributes and return the shop record. Defaults to Shopifex.Shops.create_shop/1.