@haatlabs-core/shopify
Shopify for the projects: OAuth and session tokens, store tokens kept alive, the Admin GraphQL
client, products and bulk exports, media, product content and creation, webhooks and billing.
It throws SHOPIFY_MEDIA_ERROR besides the core codes; a project spreads SHOPIFY_ERRORS
into defineErrors. A project passes its webhook topics to ensureWebhookSubscriptions, its
reconnect wording to StoreAccessTokens, and VARIANT_COST_FIELDS as extraVariantFields when it
has the inventory scope.
Install
pnpm add @haatlabs-core/shopify
Entry points
@haatlabs-core/shopify: everything below, for Node.@haatlabs-core/shopify/contracts(0.12.1):SHOPIFY_ERRORSandShopifyErrorCode, with nothing of Node: a project's contracts, which its pages load, import them from here.@haatlabs-core/shopify/embedded: for an embedded app's pages in the browser; it imports nothing of Node.@haatlabs-core/shopify/testing: helpers for a project's tests.
The App URL opened outside the admin (0.11)
After an install Shopify may open the App URL as a top-level page, with ?shop= and no host.
An embedded app sends that visit to itself inside the shop's admin before it renders:
import { redirectTopLevelVisitToAdmin } from '@haatlabs-core/shopify/embedded';
if (!redirectTopLevelVisitToAdmin(import.meta.env.VITE_SHOPIFY_API_KEY)) render();
It goes to https://<shop>/admin/apps/<api key> only from a top-level page without host,
whose shop is a *.myshopify.com address, with an API key; otherwise it returns false and
does nothing. topLevelAdminRedirect({ search, isTopLevel, apiKey }) gives that URL, or null,
without touching the window.
Time limits and pacing (0.9)
Every Admin GraphQL request has a per-attempt limit, timeoutMs (30 s). A query that runs
out of time is retried like a network failure; a mutation is not (it may have been applied):
it is thrown as a transient SHOPIFY_API_ERROR, "Shopify did not answer in time", and the
job's own retry decides. request(query, variables, { signal, timeoutMs }) takes the
caller's signal; its abort is rethrown as the caller's.
When a request to a shop may start is decided by a ShopifyThrottle, told the cost bucket
after every answer, and keeping a tenth of the bucket back. Every client shares
processShopifyThrottle unless given one; RedisShopifyThrottle (@haatlabs-core/rate-limit)
shares it across processes:
new ShopifyAdminClient({ shopDomain, accessToken, apiVersion, throttle });
In the process throttle, the callers who waited on a shop go one at a time. The one whose turn
it is reads the shop's start again and, if the answer before it moved the start later, sleeps
to it while holding the turn. No request waits more than 60 s in all, asleep and in line; at
its cap it goes. resetProcessShopifyThrottle is in @haatlabs-core/shopify/testing.
getBulkOperation(client, id, { signal }) reads a bulk operation once, for a handler that polls
with PollAgain (@haatlabs-core/queue), and classifyBulkOperation(op) says 'running',
'completed' or 'failed' (BULK_TERMINAL_STATUSES: FAILED, CANCELED, CANCELING, EXPIRED).
startProductsBulkOperation(client, { signal }) starts one. A start that timed out may have
begun one anyway, so a retry reads currentBulkOperation(client, { signal }) first: the shop's
newest bulk query still created or running (bulkOperations, Admin API 2026-01 and later), to
adopt. Since 2026-01 a shop may run up to five bulk queries at once, so a start is not refused
for one in progress, and the newest may be another of the app's: an app that runs more than one
kind at a time cannot adopt by this alone. readLines gives up, as transient, on a download that sends
nothing for a minute.
Any Node framework
Everything here is framework-free: plain functions and classes over fetch, so an app with its
own Shopify code (NestJS on Express, Fastify, Koa, a plain server) can adopt one piece at a time.
- OAuth install:
verifyOAuthHmac,buildAuthorizeUrl,exchangeCodeForToken(with expiring offline tokens),exchangeSessionTokenandrefreshAccessToken. - The Admin GraphQL client:
ShopifyAdminClient, with the API version, cost-based throttling and Shopify's errors. - Webhooks:
verifyWebhookHmac(rawBody, header, apiSecret)checks the bytes Shopify sent, so the route must see the raw body. On NestJS:NestFactory.create(AppModule, { rawBody: true })andreq.rawBody(RawBodyRequest<Request>); on Express alone:express.raw()on that route. - Session tokens:
verifySessionToken(token, { apiKey, apiSecret })gives the shop and the user behind an App Bridge request. - Billing: the plan a store pays for through Shopify.
src/express.int.test.ts runs a webhook and a session token through a NestJS app on Express.