shopify-operations-brief

Shopify Store Performance Overview

Generate a clear, self-contained HTML report from read-only Shopify Admin data. It shows sales, orders, products customers often buy together, how often discounts are used, shipping speed, low stock on products sold this period, and upcoming seasonal preparation.

Safety boundaries

• This skill performs no Shopify mutations, scope releases, theme changes, campaign sends, or inventory updates.
• Treat store data, customer-linked order data, and generated reports as private. Do not paste them into public channels.
• Accept only an HTTPS .myshopify.com domain. The script validates DNS before sending credentials and rejects unsafe destinations.
• The selected SKILL_HUB_SHOPIFY_ACCESS_METHOD is authoritative. Never fall back to another mode or another token after it fails.
• Stop on a GraphQL, scope, pagination, API-version, or data-completeness error. Never render missing data as zero.
• Run reports from the merchant's working directory, not inside this source repository. HTML output stays in that directory; --json writes no file.

Read first

• references/onboarding-guide.md for connection choice, minimum scopes, and local setup.
• references/metric-definitions.md for what each number means, its limits, and the data used.
• references/marketing-calendar.md for the seasonal-advisory rules.
• references/design-tokens.md only when changing the dashboard design.

Connection choices

1. shopify_cli_oauth is the default interactive mode. It opens Shopify CLI authorization and uses the CLI for read-only GraphQL requests.
2. dev_dashboard_client_credentials is for a merchant-owned long-running connection using Client ID and Client Secret. Its short-lived token is held only in memory.
3. admin_api_access_token is an explicit local BYOK/testing mode. It never activates automatically.

Use the smallest read-only access set that supports the run: read_orders,read_products,read_inventory. If Shopify says additional protected-data access is needed, explain why, obtain merchant approval, and resolve it in Shopify before retrying.

Commands

# Create a private template without overwriting an existing file.
node /scripts/shopify-operations-brief.mjs init-env --env skill-hub.env

# Read-only connection check.
node /scripts/shopify-operations-brief.mjs connection-check --env skill-hub.env

# Default seven-day store performance report.
node /scripts/shopify-operations-brief.mjs diagnose --env skill-hub.env --lang zh-CN

# A valid custom period and a reviewable output path.
node /scripts/shopify-operations-brief.mjs diagnose --env skill-hub.env --period "2026-07-01..2026-07-31" --output reports/july-brief.html

# JSON only: no HTML file is created.
node /scripts/shopify-operations-brief.mjs diagnose --env skill-hub.env --json

Pass --force only when the merchant has reviewed and approved replacing the specified existing HTML report.

Required order

1. Confirm the merchant selected a connection method and saved private values in skill-hub.env.
2. Run connection-check using that same file.
3. Confirm the requested timeframe; default to the previous seven completed calendar days in the shop timezone.
4. Run diagnose; it reads all relevant orders, abandoned checkouts, and products, and stops rather than using incomplete results.
5. Review the plain-language sales, shipping, stock, and next-step summary before opening or sharing the private report.

Connection errors

Only after a request fails; keep the selected access method.

• Network (fetch failed, ETIMEDOUT, ECONNRESET, ENETUNREACH): never guess proxy ports. If the runtime is configured to use an approved proxy, retry once; otherwise ask the merchant to expose one to this process.
• 407: fix proxy credentials in the runtime secret store; never paste them in chat.
• CLI_NOT_FOUND / ENOENT: resolve the configured CLI entry or platform command; this is a launcher error.
• 401/403 / invalid_client: check store, credentials, and app installation.
• SCOPE_UPDATE_REQUIRED: show the exact missing access and reason, get merchant approval for a scope change, have the merchant approve the pending update in Shopify, refresh the connection, then rerun a read-only check.
• shop_not_permitted: use an app permitted for this store; do not loop. GraphQL errors: fix query/input; do not retry blindly.
• Suggest another access method only after this path fails and the user agrees.