# Shopify auth for this package

Kody does **not** ship a Shopify OAuth integration for this package. That is
intentional. Forkers bring their own Admin credentials.

## Lanes

| Lane | Secrets | How the client authenticates |
|------|---------|------------------------------|
| Client credentials (preferred) | `shopifyClientId`, `shopifyClientSecret` | `POST /admin/oauth/access_token` with `grant_type=client_credentials`, then `X-Shopify-Access-Token` |
| Legacy custom app | `shopifyAdminAccessToken` | `X-Shopify-Access-Token: {{secret:shopifyAdminAccessToken}}` |

If `shopifyAdminAccessToken` exists, it wins. Otherwise both client
credentials secrets are required.

Client-credentials tokens last 24 hours. This package exchanges a fresh
token on each invoke and does not cache it. That keeps the live
`@kody/shopify` package from writing shop tokens into shared storage.

## Shop host

Every Admin call goes to:

```
https://{shop}.myshopify.com/admin/api/{version}/graphql.json
https://{shop}.myshopify.com/admin/api/{version}/{resource}.json
https://{shop}.myshopify.com/admin/oauth/access_token
```

`shop` is normalized from `acme`, `acme.myshopify.com`, or
`https://acme.myshopify.com/admin`. Other hosts are rejected.

You must approve `{shop}.myshopify.com` on the secrets you save. Kody
host approval is per hostname; there is no wildcard for every shop.

## Secret setup URLs

Create secrets in the account UI. Do not paste values into chat.

- https://kody.codes/account/secrets/new?name=shopifyClientId&description=Shopify%20Dev%20Dashboard%20client%20id&scope=user
- https://kody.codes/account/secrets/new?name=shopifyClientSecret&description=Shopify%20Dev%20Dashboard%20client%20secret&scope=user
- https://kody.codes/account/secrets/new?name=shopifyAdminAccessToken&description=Shopify%20Admin%20API%20access%20token&scope=user

## Official Shopify references

- [Create a Dev Dashboard app](https://shopify.dev/docs/apps/build/dev-dashboard/create-apps-using-dev-dashboard)
- [Get API access tokens](https://shopify.dev/docs/apps/build/dev-dashboard/get-api-access-tokens)
- [Access tokens overview](https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens)
- [Access scopes](https://shopify.dev/docs/api/usage/access-scopes)

## What this package will not do

- Register a platform `/connect/oauth?provider=shopify` app
- Ask you to paste a token into an agent chat
- Store exchanged access tokens in `packageStorage()`
- Call Storefront, Customer Account, or Payments Apps APIs (add those in a
  fork if you need them)