# `Shopifex.ManagedInstall.Callbacks`
[🔗](https://github.com/ericdude4/shopifex/blob/main/lib/shopifex/managed_install/callbacks.ex#L1)

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

| Hook                | First install | Token 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}`.

# `after_exchange`

```elixir
@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`

```elixir
@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`

```elixir
@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`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
