# @kody/shopify

## Intent

Give agents a fork-ready Shopify Admin API toolkit — GraphQL-first shop,
product, order, customer, inventory, collection, fulfillment, draft-order,
webhook, and metafield helpers — without a Kody Shopify OAuth integration.
Transport is one compact authenticated client against
`https://{shop}.myshopify.com/admin`. Use `./graphql` or `./request` for any
unwrapped Admin path.

This listing is meant to be forked. The live `@kody/shopify` package does not
talk to a shared store. After you fork, save your own shop credentials and
call the helpers in your account.

## What it does

- Read a shop profile, catalog, orders, or customers from Admin GraphQL
- Preview or apply catalog, inventory, fulfillment, draft-order, webhook, or
  metafield writes (`dryRun` defaults on)
- Call an unwrapped Admin GraphQL operation or legacy REST resource
- Start a private Shopify workflow by forking this package instead of
  scaffolding from zero

Do **not** use this package to invent a platform Shopify OAuth app. Auth is
secret-backed on purpose.

## Prerequisites / setup

You need a shop handle plus **one** credential lane. There is no saved Kody
`shopify` integration.

### 1. Shop handle

Pass `shop: "your-store"` (the `*.myshopify.com` subdomain) on each call.
After you fork, you can persist a default with `./config`.

Approve outbound host `{your-store}.myshopify.com` in the account secrets UI.
Admin API traffic is shop-hosted; there is no single shared API hostname.

### 2a. Preferred — Dev Dashboard client credentials

Shopify's current custom-app path issues a **Client ID** and **Client secret**.
You exchange those for a 24-hour Admin access token. This package does that
per invoke and never stores the access token.

1. Create and install a Dev Dashboard app on your shop.
   Docs: https://shopify.dev/docs/apps/build/dev-dashboard/create-apps-using-dev-dashboard
2. Copy Client ID and Client secret from **Settings**.
3. Save them as user secrets (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&allowedHosts=&scope=user

Then approve host `{your-store}.myshopify.com` on those secrets.

Token exchange docs:
https://shopify.dev/docs/apps/build/dev-dashboard/get-api-access-tokens

### 2b. Legacy — Admin API access token

Some older custom apps still show a static Admin API access token (`shpat_…`).
Save that as `shopifyAdminAccessToken`. If this secret exists, it wins over
client credentials.

- https://kody.codes/account/secrets/new?name=shopifyAdminAccessToken&description=Shopify%20Admin%20API%20access%20token&scope=user

### Access scopes

Grant only what you will call. Typical starting set:

- `read_products` / `write_products`
- `read_orders` / `write_orders` (protected customer data may need extra Shopify approval)
- `read_customers` / `write_customers`
- `read_inventory` / `write_inventory`
- `read_locations`
- `read_fulfillments` / `write_fulfillments`
- `read_draft_orders` / `write_draft_orders`
- `read_content` or the webhook topics you subscribe to

Default API version is **`2026-07`**. Override per call with `apiVersion` or
store a fork-local default.

Agents: see [`AGENTS.md`](./AGENTS.md) for import paths, smoke checks, and
mutation snippets.

## Done when

- Shop handle is known; host `{shop}.myshopify.com` is approved
- Client credentials (`shopifyClientId` + `shopifyClientSecret`) or legacy
  `shopifyAdminAccessToken` are saved (never paste values into chat)
- Smoke test reads `shop { name }` for that store
- Writes preview with default `dryRun` and only run live after you confirm the
  exact shop and mutation

## Forking

Community listings are snapshots. Fork this listing into your account, review
the source, publish your copy, then save secrets. Do not treat the live
`@kody/shopify` `packageStorage()` as yours — platform packages share the
Kody-scope bucket.

See [CONTRIBUTING.md](./CONTRIBUTING.md) for the clone-edit-publish loop and
how to add another domain module.

One-click listing URL after publish: `https://kody.codes/@kody/shopify`

## Branding

The community icon is [The Shopping Bag](https://www.shopify.com/brand-assets),
Shopify's official brandmark, taken from the public brand-assets kit
(`shopify-shopping-bag.zip` → `shopify_glyph.svg`). Paths are unmodified.
Shopify® and The Shopping Bag are trademarks of Shopify Inc.
This package is not affiliated with or endorsed by Shopify Inc.

## Docs

- [Admin GraphQL API](https://shopify.dev/docs/api/admin-graphql)
- [Admin REST API (legacy)](https://shopify.dev/docs/api/admin-rest)
- [Client credentials](https://shopify.dev/docs/apps/build/dev-dashboard/get-api-access-tokens)
- [Access scopes](https://shopify.dev/docs/api/usage/access-scopes)
- [API versioning](https://shopify.dev/docs/api/usage/versioning)
- [Auth notes in this repo](./docs/auth.md)
- [Domain map and extension tips](./docs/domains.md)