# Domain map

Helpers are thin GraphQL wrappers. Each module accepts `shop` and
`apiVersion`, projects a slim object, and keeps writes behind `dryRun`.

## Read helpers

| Need | Export | Notes |
|------|--------|--------|
| Is auth working? | `./smoke-test` | Local checks always; live shop read when configured |
| Shop profile | `./shop` `getShop` | Name, plan, currency, primary domain |
| Catalog | `./products` `listProducts` / `getProduct` | Shopify search query supported |
| Orders | `./orders` `listOrders` / `getOrder` | Newest first |
| Customers | `./customers` `listCustomers` / `getCustomer` | Search by email or name |
| Locations / on-hand | `./inventory` | Levels use the `available` quantity name |
| Collections | `./collections` | Includes a small product page on `getCollection` |
| Fulfillment orders | `./fulfillments` `listFulfillmentOrders` | Per order |
| Drafts | `./draft-orders` | Open quotes / invoices |
| Webhook list | `./webhooks` `listWebhooks` | Current app subscriptions |
| Metafields | `./metafields` `listMetafields` | Owner type + id |

## Write helpers (dry-run by default)

| Need | Export | Mutation |
|------|--------|----------|
| New / updated product | `./products` | `productCreate`, `productUpdate` |
| New customer | `./customers` | `customerCreate` |
| Inventory delta | `./inventory` `adjustInventory` | `inventoryAdjustQuantities` (`@idempotent` required on 2026-04+) |
| Mark shipped | `./fulfillments` `createFulfillment` | `fulfillmentCreate` |
| Draft invoice | `./draft-orders` `createDraftOrder` | `draftOrderCreate` |
| Subscribe / remove webhook | `./webhooks` | `webhookSubscriptionCreate` / `Delete` |
| Set metafield | `./metafields` `setMetafield` | `metafieldsSet` |

Pass `dryRun: false` only after a human confirms the shop and payload.

## Escape hatches

Anything not wrapped belongs on `./graphql` (preferred) or `./request`
(legacy REST). Examples:

```ts
import { shopifyGraphql } from 'kody:@kody/shopify/graphql'

await shopifyGraphql({
	shop: 'acme',
	query: `query {
		automaticDiscountNodes(first: 10) {
			nodes { id automaticDiscount { ... on DiscountAutomaticBasic { title } } }
		}
	}`,
})
```

```ts
import { shopifyRequest } from 'kody:@kody/shopify/request'

await shopifyRequest({
	shop: 'acme',
	path: '/gift_cards.json',
	query: { limit: 5 },
})
```

## Adding another domain

See [CONTRIBUTING.md](../CONTRIBUTING.md). Start with `src/orders.ts` as
the template. Keep `src/lib/client.ts` as the only authenticated transport.

## API version

Default `2026-07`. Shopify releases Admin versions in January, April, July,
and October. When you bump the default, update `DEFAULT_API_VERSION` in
`src/lib/shop.ts`, the README, and this file in the same commit. Re-read
the GraphQL reference for renamed fields before wrapping new mutations.