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

Handles Shopify's managed app installation flow via token exchange, and keeps
the embedded session's offline access token fresh.

With managed installation (the default for new Shopify apps), Shopify sends an
`id_token` JWT on every page load instead of going through the traditional
OAuth authorization code exchange. This plug:

1. Verifies the `id_token` with `Shopifex.SessionToken` (strict HS256).
2. If the shop doesn't exist, exchanges the `id_token` for an **expiring**
   offline access token (RFC 8693) and persists the full token lifecycle
   (`access_token`, `token_expires_at`, `refresh_token`,
   `refresh_token_expires_at`).
3. If the shop exists but its stored access token is within ~10 minutes of
   expiry (`token_expires_at`) or already expired — or its stored scopes lack
   any scope in `config :shopifex, :scopes` (a merchant approved a scope
   update) — it re-exchanges, which also persists Shopify's current grant.
4. Otherwise it builds the session from the stored shop directly.

New installs are persisted through the configurable
`Shopifex.ManagedInstall.Callbacks` hooks (`insert_shop/1`, `after_install/1`,
`after_exchange/2`), so apps can customise shop creation and side effects
without re-implementing token exchange.

## Concurrency

Concurrent embedded loads of the same shop (two tabs, a reload during a slow
exchange, several app-load requests fanned out by the admin) are serialized
per shop through `Shopifex.TokenRefreshLease` — the same lease
`Shopifex.Auth.refresh/1` takes — so exactly one of them exchanges the
`id_token`. The others poll the shop row and build their session from the
pair the exchange persisted, without contacting Shopify; a first install
inserts the row once. The `shopifex_token_refresh_leases` table is therefore
required by this plug, not only by background refresh (see
`docs/upgrading.md`). A load that cannot obtain or observe the lease within
`config :shopifex, :token_refresh_wait_timeout_ms` (15s by default) logs a
warning and exchanges without it. A re-exchange of an existing shop is
written with the same locked compare `Shopifex.Auth.refresh/1` uses, so a
pair that a refresh or another exchange persisted meanwhile is kept rather
than overwritten. The lease is held until the exchange, its persistence, the
webhook reconcile and the `Shopifex.ManagedInstall.Callbacks` hooks have
run, so a hook that calls `Shopifex.Auth.refresh/1` for the same shop
synchronously waits out the lease deadline and gets
`{:error, :refresh_in_progress}`; run such work asynchronously.

Webhooks are reconciled via `Shopifex.Shops.configure_webhooks/1` on first
install **and on every re-exchange** (idempotent self-heal — see that function).
Reconciliation issues one `webhookSubscriptions` query (plus a create per missing
topic) per re-exchange, i.e. at most once per shop per ~50 min of activity; it
does **not** run on the hot per-load path that builds the session from a fresh
shop directly.

If no recognised `id_token` is present, this plug is a no-op — the request
falls through to the legacy OAuth flow (`Shopifex.Plug.ShopifySession`).

> **No cookieless `auth_token` redirect bridge.** App Bridge supplies a fresh
> `id_token` on every embedded load, so there is no need to bridge auth across a
> cookieless redirect — this plug deliberately ships no `Phoenix.Token` redirect
> branch. If your app issues its own signed-token redirect, keep that as a custom
> plug clause; the library will not handle it.

## Usage

Add this plug to your router pipeline **before** `Shopifex.Plug.ShopifySession`:

    pipeline :managed_install do
      plug Shopifex.Plug.ManagedInstall
    end

    scope "/auth" do
      pipe_through [:shopifex_browser, :managed_install, :shopify_session]
      get "/", MyAppWeb.AuthController, :auth
    end

## Configuration

    config :shopifex,
      api_key: "your_api_key",
      secret: "your_api_secret"

Install-time side effects (profile fetch, analytics, snapshots) are
app-specific and belong in your `AuthController` / shop-creation path, not in
this plug.

# `call`

# `init`

---

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