@kody/shopify

docs/domains.md

74 lines · 2.8 KB · Markdown

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:

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

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

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

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

Adding another domain

See 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.