Shopify SDK Patterns

// codegen.ts — project root config
import { shopifyApiProject, ApiType } from "@shopify/api-codegen-preset";

export default {
  schema: "https://shopify.dev/admin-graphql-direct-proxy",
  documents: ["src/**/*.{ts,tsx}"],
  projects: {
    default: shopifyApiProject({
      apiType: ApiType.Admin,
      apiVersion: "2025-04", // Update quarterly
      outputDir: "./src/types",
    }),
  },
};

// src/operations/products.ts — typed query with codegen output
import type { ProductsQuery } from "../types/admin.generated";

const PRODUCTS_QUERY = `#graphql
  query Products($first: Int!, $after: String) {
    products(first: $first, after: $after) {
      edges {
        node { id title status totalInventory }
      }
      pageInfo { hasNextPage endCursor }
    }
  }
` as const;

// Return type is fully inferred from codegen
export async function getProducts(shop: string): Promise<ProductsQuery> {
  return shopifyQuery<ProductsQuery>(shop, PRODUCTS_QUERY, { first: 50 });
}

// src/shopify/bulk.ts
const BULK_QUERY = `
  mutation bulkOperationRunQuery($query: String!) {
    bulkOperationRunQuery(query: $query) {
      bulkOperation { id status }
      userErrors { field message }
    }
  }
`;

const POLL_QUERY = `{
  currentBulkOperation {
    id status errorCode objectCount url
  }
}`;

export async function runBulkOperation(
  shop: string,
  query: string
): Promise<string> {
  // Start the bulk operation
  const { bulkOperationRunQuery } = await shopifyQuery(shop, BULK_QUERY, { query });
  if (bulkOperationRunQuery.userErrors?.length) {
    throw new Error(bulkOperationRunQuery.userErrors[0].message);
  }

  // Poll until complete (typically 1-10 minutes for large datasets)
  let result;
  do {
    await new Promise((r) => setTimeout(r, 5000)); // 5s interval
    result = (await shopifyQuery(shop, POLL_QUERY)).currentBulkOperation;
  } while (result.status === "RUNNING" || result.status === "CREATED");

  if (result.status !== "COMPLETED") {
    throw new Error(`Bulk operation failed: ${result.errorCode}`);
  }

  return result.url; // JSONL download URL
}

// Usage: export all products
const url = await runBulkOperation(shop, `{
  products { edges { node { id title status variants { edges { node { sku price } } } } } }
}`);
const response = await fetch(url);
const jsonl = await response.text();
const products = jsonl.trim().split("\n").map(JSON.parse);

// src/shopify/webhooks.ts
const REGISTER_WEBHOOK = `
  mutation webhookSubscriptionCreate(
    $topic: WebhookSubscriptionTopic!,
    $webhookSubscription: WebhookSubscriptionInput!
  ) {
    webhookSubscriptionCreate(topic: $topic, webhookSubscription: $webhookSubscription) {
      webhookSubscription { id topic }
      userErrors { field message }
    }
  }
`;

interface WebhookConfig {
  topic: string;
  callbackUrl: string;
  format?: "JSON" | "XML";
}

export async function registerWebhooks(
  shop: string,
  webhooks: WebhookConfig[]
): Promise<{ registered: string[]; errors: string[] }> {
  const registered: string[] = [];
  const errors: string[] = [];

  for (const wh of webhooks) {
    const result = await shopifyQuery(shop, REGISTER_WEBHOOK, {
      topic: wh.topic,
      webhookSubscription: {
        callbackUrl: wh.callbackUrl,
        format: wh.format ?? "JSON",
      },
    });

    const userErrors = result.webhookSubscriptionCreate.userErrors;
    if (userErrors?.length) {
      errors.push(`${wh.topic}: ${userErrors[0].message}`);
    } else {
      registered.push(wh.topic);
    }
  }

  return { registered, errors };
}