Shopify sync source guide

sources:
  Product:
    description: Shopify Product
    schema: shopify_products

name: shopify_products
display_name: Shopify Products
description: Shopify products with variants, images, collections, and options
fields:
  - name: shopify_product_id
    type: string
    display_name: Product ID
    description: Shopify product ID
    primary: true
  - name: title
    type: string
    display_name: Title
    description: Product title
  - name: body_html
    type: string
    display_name: Description
    description: Product description in HTML format
  - name: vendor
    type: string
    display_name: Vendor
    description: Product vendor
  - name: product_type
    type: string
    display_name: Product Type
    description: Type of product
  - name: handle
    type: string
    display_name: Handle
    description: Product handle (URL slug)
  - name: published_at
    type: string
    display_name: Published At
    description: Date when the product was published
  - name: created_at
    type: string
    display_name: Created At
    description: Date when the product was created
  - name: updated_at
    type: string
    display_name: Updated At
    description: Date when the product was last updated
  - name: tags
    type: "[string]"
    display_name: Tags
    description: Product tags
  - name: status
    type: string
    display_name: Status
    description: Product status (active, archived, draft)
  - name: variants
    type: "[variant]"
    display_name: Variants
    description: Product variants
  - name: images
    type: "[image]"
    display_name: Images
    description: Product images
  - name: collections
    type: "[collection]"
    display_name: Collections
    description: Collections this product belongs to
  - name: options
    type: "[option]"
    display_name: Options
    description: Product options (size, color, etc.)

custom_types:
  - name: variant
    display_name: Variant
    description: Product variant with pricing and inventory
    fields:
      - name: variant_id
        type: string
        display_name: Variant ID
        description: Shopify variant ID
      - name: title
        type: string
        display_name: Title
        description: Variant title
      - name: price
        type: float
        display_name: Price
        description: Variant price
      - name: compare_at_price
        type: float
        display_name: Compare At Price
        description: Original price for sale items
      - name: sku
        type: string
        display_name: SKU
        description: Stock keeping unit
      - name: inventory_quantity
        type: long
        display_name: Inventory Quantity
        description: Current inventory level
      - name: inventory_policy
        type: string
        display_name: Inventory Policy
        description: Whether to allow sales when out of stock
      - name: barcode
        type: string
        display_name: Barcode
        description: Product barcode or UPC
      - name: created_at
        type: string
        display_name: Created At
        description: Date when the variant was created
      - name: updated_at
        type: string
        display_name: Updated At
        description: Date when the variant was last updated
  - name: image
    display_name: Image
    description: Product image
    fields:
      - name: image_id
        type: string
        display_name: Image ID
        description: Shopify image ID
      - name: url
        type: string
        display_name: URL
        description: Image URL
      - name: width
        type: long
        display_name: Width
        description: Image width in pixels
      - name: height
        type: long
        display_name: Height
        description: Image height in pixels
      - name: alt_text
        type: string
        display_name: Alt Text
        description: Image alt text
      - name: position
        type: long
        display_name: Position
        description: Image sort order
  - name: collection
    display_name: Collection
    description: Product collection
    fields:
      - name: collection_id
        type: string
        display_name: Collection ID
        description: Shopify collection ID
      - name: title
        type: string
        display_name: Title
        description: Collection title
  - name: option
    display_name: Option
    description: Product option (e.g., Size, Color)
    fields:
      - name: option_id
        type: string
        display_name: Option ID
        description: Shopify option ID
      - name: name
        type: string
        display_name: Name
        description: Option name
      - name: position
        type: long
        display_name: Position
        description: Option sort order
      - name: values
        type: "[string]"
        display_name: Values
        description: Available option values

sections:
  - key: shopify_credentials
    label: Shopify Credentials
    properties:
      - webhooks_active
      - webhook_error
    elements:
      - key: store_url
        type: text
        label: Shopify Store URL
        required: true
        help: Enter your Shopify store URL (without https://)
      - key: access_token
        type: secret
        label: Access Token
        required: true
        help: Permanent access token from your private app
      - type: instructions
        text: |
          **Webhook status: Active** — Real-time product sync is enabled.
        visible:
          key: shopify_credentials.webhooks_active
          equals: true
      - type: instructions
        text: |
          **Webhook status: Not configured** — Save valid credentials to enable real-time product sync.
        visible:
          operation: all
          comparators:
            - key: shopify_credentials.webhooks_active
              equals: false
            - key: shopify_credentials.webhook_error
              empty: true
      - type: instructions
        text: |
          **Webhook status: Failed** — {{{shopify_credentials.webhook_error}}}
        visible:
          operation: all
          comparators:
            - key: shopify_credentials.webhooks_active
              equals: false
            - key: shopify_credentials.webhook_error
              empty: false

  - key: sync_options
    label: Sync Options
    elements:
      - key: sync_limit
        type: text
        dataType: number
        label: Batch Size
        required: true
        help: Number of products fetched per API request during import (max recommended 250)
      - key: include_archived
        type: toggle
        label: Include Archived Products
        help: If enabled, archived products will also be synced
      - key: include_drafts
        type: toggle
        label: Include Draft Products
        help: If enabled, draft products will also be synced

  - key: import_actions
    label: Import
    elements:
      - type: instructions
        text: |
          Use the button below to run a full import of all Shopify products.
          This will sync every product (including variants, images, collections,
          and options) to all configured data syncs.
      - key: trigger_full_import
        type: button
        label: Run Full Import
        action: trigger_full_import
        help: Triggers a full import of all Shopify products to all configured syncs

jobs:
  import_products:
    entry_point: ImportProducts
    description: Performs a one-time import of all Shopify products

/**
 * Interface representing a Shopify product from GraphQL API
 */
export interface ShopifyGraphQLProduct {
  id: string;
  title: string;
  descriptionHtml: string;
  vendor: string;
  productType: string;
  handle: string;
  publishedAt: string | null;
  createdAt: string;
  updatedAt: string;
  tags: string[];
  status: string;
  variants: {
    edges: Array<{
      node: ShopifyGraphQLVariant;
    }>;
  };
  options: ShopifyGraphQLOption[];
  images: {
    edges: Array<{
      node: ShopifyGraphQLImage;
    }>;
  };
  collections: {
    edges: Array<{
      node: {
        id: string;
        title: string;
      };
    }>;
  };
}

/**
 * Interface representing a Shopify product variant from GraphQL API
 */
export interface ShopifyGraphQLVariant {
  id: string;
  title: string;
  price: string;
  compareAtPrice: string | null;
  sku: string;
  inventoryQuantity: number;
  inventoryPolicy: string;
  barcode: string | null;
  createdAt: string;
  updatedAt: string;
}

/**
 * Interface representing a Shopify product option from GraphQL API
 */
export interface ShopifyGraphQLOption {
  id: string;
  name: string;
  position: number;
  values: string[];
}

/**
 * Interface representing a Shopify product image from GraphQL API
 */
export interface ShopifyGraphQLImage {
  id: string;
  url: string;
  width: number;
  height: number;
  altText: string | null;
}

/**
 * Interface representing a Shopify product from REST API
 */
export interface ShopifyProduct {
  id: number;
  title: string;
  body_html: string;
  vendor: string;
  product_type: string;
  handle: string;
  published_at: string;
  created_at: string;
  updated_at: string;
  tags: string;
  status: string;
  variants: ShopifyVariant[];
  options: ShopifyOption[];
  images: ShopifyImage[];
  image: ShopifyImage | null;
}

/**
 * Interface representing a Shopify product variant from REST API
 */
export interface ShopifyVariant {
  id: number;
  shopify_product_id: number;
  title: string;
  price: string;
  compare_at_price: string | null;
  sku: string;
  inventory_quantity: number;
  inventory_policy: string;
  barcode: string | null;
  created_at: string;
  updated_at: string;
}

/**
 * Interface representing a Shopify product option from REST API
 */
export interface ShopifyOption {
  id: number;
  shopify_product_id: number;
  name: string;
  position: number;
  values: string[];
}

/**
 * Interface representing a Shopify product image from REST API
 */
export interface ShopifyImage {
  id: number;
  shopify_product_id: number;
  position: number;
  src: string;
  width: number;
  height: number;
  alt: string | null;
}

import {
  ShopifyGraphQLProduct,
  ShopifyProduct,
  ShopifyVariant,
  ShopifyOption,
  ShopifyImage
} from '../data/ShopifyProducts';

export interface CollectionInfo {
  collection_id: string;
  title: string;
}

/**
 * Convert a Shopify GraphQL product to a REST-compatible product format
 */
export function convertGraphQLProductToRESTFormat(graphQLProduct: ShopifyGraphQLProduct): ShopifyProduct {
  // Extract the numeric ID from the GraphQL ID (gid://shopify/Product/12345 -> 12345)
  const idMatch = graphQLProduct.id.match(/\/Product\/(\d+)$/);
  const numericId = idMatch ? parseInt(idMatch[1], 10) : 0;

  // Convert variants
  const variants: ShopifyVariant[] = graphQLProduct.variants.edges.map((edge) => {
    const variantIdMatch = edge.node.id.match(/\/ProductVariant\/(\d+)$/);
    const variantNumericId = variantIdMatch ? parseInt(variantIdMatch[1], 10) : 0;

    return {
      id: variantNumericId,
      shopify_product_id: numericId,
      title: edge.node.title,
      price: edge.node.price,
      compare_at_price: edge.node.compareAtPrice || null,
      sku: edge.node.sku,
      inventory_quantity: edge.node.inventoryQuantity,
      inventory_policy: edge.node.inventoryPolicy,
      barcode: edge.node.barcode,
      created_at: edge.node.createdAt,
      updated_at: edge.node.updatedAt
    };
  });

  // Convert options
  const options: ShopifyOption[] = graphQLProduct.options.map((option) => {
    const optionIdMatch = option.id.match(/\/ProductOption\/(\d+)$/);
    const optionNumericId = optionIdMatch ? parseInt(optionIdMatch[1], 10) : 0;

    return {
      id: optionNumericId,
      shopify_product_id: numericId,
      name: option.name,
      position: option.position,
      values: option.values
    };
  });

  // Convert images
  const images: ShopifyImage[] = graphQLProduct.images.edges.map((edge, index) => {
    const imageIdMatch = edge.node.id.match(/\/ProductImage\/(\d+)$/);
    const imageNumericId = imageIdMatch ? parseInt(imageIdMatch[1], 10) : 0;

    return {
      id: imageNumericId,
      shopify_product_id: numericId,
      position: index + 1,
      src: edge.node.url,
      width: edge.node.width,
      height: edge.node.height,
      alt: edge.node.altText
    };
  });

  // Convert tags from array to string
  const tagsString = graphQLProduct.tags.join(', ');

  // Extract collection data (id + title)
  const collections: CollectionInfo[] = graphQLProduct.collections.edges.map((edge) => {
    const collectionIdMatch = edge.node.id.match(/\/Collection\/(\d+)$/);
    const collectionId = collectionIdMatch ? collectionIdMatch[1] : '0';
    return {
      collection_id: collectionId,
      title: edge.node.title
    };
  }).filter((c) => c.collection_id !== '0');

  // Return the converted product
  const convertedProduct = {
    id: numericId,
    title: graphQLProduct.title,
    body_html: graphQLProduct.descriptionHtml,
    vendor: graphQLProduct.vendor,
    product_type: graphQLProduct.productType,
    handle: graphQLProduct.handle,
    published_at: graphQLProduct.publishedAt || '',
    created_at: graphQLProduct.createdAt,
    updated_at: graphQLProduct.updatedAt,
    tags: tagsString,
    status: graphQLProduct.status,
    variants,
    options,
    images,
    image: images.length > 0 ? images[0] : null
  };
  // Add collections as a non-enumerable property to avoid polluting the REST format
  // but make it available to our transformer
  Object.defineProperty(convertedProduct, '_collections', {
    value: collections,
    enumerable: false,
    writable: false
  });

  return convertedProduct;
}

import { logger } from '@zaiusinc/app-sdk';
import {
  ShopifyProduct,
  ShopifyGraphQLProduct
} from '../data/ShopifyProducts';
import {
  convertGraphQLProductToRESTFormat
} from './shopifyConverter';

export interface ShopifyCredentials {
  storeUrl: string;
  accessToken: string;
}

export interface ShopifyWebhook {
  id?: number;
  address: string;
  topic: string;
  format: string;
}

const SHOPIFY_API_VERSION = '2026-01';

export class ShopifyClient {
  private graphqlEndpoint: string;
  private accessToken: string;
  private storeUrl: string;

  public constructor(credentials: ShopifyCredentials) {
    this.storeUrl = credentials.storeUrl;
    this.graphqlEndpoint = `https://${credentials.storeUrl}/admin/api/${SHOPIFY_API_VERSION}/graphql.json`;
    this.accessToken = credentials.accessToken;
  }

  /**
   * Execute a GraphQL query against the Shopify Admin API
   */
  private async executeGraphQL<T>(query: string, variables?: Record<string, any>): Promise<T> {
    try {
      const response = await fetch(this.graphqlEndpoint, {
        method: 'POST',
        headers: {
          'X-Shopify-Access-Token': this.accessToken,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          query,
          variables,
        }),
      });

      if (!response.ok) {
        throw new Error(`Shopify API error: ${response.status} ${response.statusText}`);
      }

      const { data, errors } = await response.json() as { data: any; errors?: any[] };

      if (errors && Array.isArray(errors) && errors.length > 0) {
        const errorMessages = errors.map((e) => (typeof e === 'object' && e !== null && 'message' in e) ?
          String(e.message) : 'Unknown GraphQL error');
        throw new Error(`GraphQL error: ${errorMessages.join(', ')}`);
      }

      return data;
    } catch (error: any) {
      logger.error(`Error executing GraphQL query: ${error.message}`);
      throw error;
    }
  }

  /**
   * Get a paginated list of products using GraphQL
   */
  public async getProducts(limit = 50, cursor?: string): Promise<{
    products: ShopifyProduct[];
    nextPageInfo?: string;
  }> {
    try {
      const query = `
        query GetProducts($first: Int!, $after: String) {
          products(first: $first, after: $after) {
            pageInfo {
              hasNextPage
              endCursor
            }
            edges {
              node {
                id
                title
                descriptionHtml
                vendor
                productType
                handle
                publishedAt
                createdAt
                updatedAt
                tags
                status
                variants(first: 50) {
                  edges {
                    node {
                      id
                      title
                      price
                      compareAtPrice
                      sku
                      inventoryQuantity
                      inventoryPolicy
                      barcode
                      createdAt
                      updatedAt
                    }
                  }
                }
                options {
                  id
                  name
                  position
                  values
                }
                images(first: 20) {
                  edges {
                    node {
                      id
                      url
                      width
                      height
                      altText
                    }
                  }
                }
                collections(first: 20) {
                  edges {
                    node {
                      id
                      title
                    }
                  }
                }
              }
            }
          }
        }
      `;

      const variables = {
        first: limit,
        after: cursor || null,
      };

      const data = await this.executeGraphQL<{
        products: {
          pageInfo: {
            hasNextPage: boolean;
            endCursor: string;
          };
          edges: Array<{
            node: ShopifyGraphQLProduct;
          }>;
        };
      }>(query, variables);

      const products = data.products.edges.map((edge) => convertGraphQLProductToRESTFormat(edge.node));

      const nextPageInfo = data.products.pageInfo.hasNextPage ?
        data.products.pageInfo.endCursor :
        undefined;

      return {
        products,
        nextPageInfo,
      };
    } catch (error: any) {
      logger.error(`Error fetching products from Shopify: ${error.message}`);
      throw error;
    }
  }

  /**
   * Get a single product by ID using GraphQL
   */
  public async getProductById(productId: number): Promise<ShopifyProduct> {
    try {
      const gid = `gid://shopify/Product/${productId}`;
      const query = `
        query GetProduct($id: ID!) {
          product(id: $id) {
            id
            title
            descriptionHtml
            vendor
            productType
            handle
            publishedAt
            createdAt
            updatedAt
            tags
            status
            variants(first: 50) {
              edges {
                node {
                  id
                  title
                  price
                  compareAtPrice
                  sku
                  inventoryQuantity
                  inventoryPolicy
                  barcode
                  createdAt
                  updatedAt
                }
              }
            }
            options {
              id
              name
              position
              values
            }
            images(first: 20) {
              edges {
                node {
                  id
                  url
                  width
                  height
                  altText
                }
              }
            }
            collections(first: 20) {
              edges {
                node {
                  id
                  title
                }
              }
            }
          }
        }
      `;

      const data = await this.executeGraphQL<{
        product: ShopifyGraphQLProduct;
      }>(query, { id: gid });

      if (!data.product) {
        throw new Error(`Product not found: ${productId}`);
      }

      return convertGraphQLProductToRESTFormat(data.product);
    } catch (error: any) {
      logger.error(`Error fetching product ${productId} from Shopify: ${error.message}`);
      throw error;
    }
  }

  /**
   * Get all products in a collection by collection ID using GraphQL
   */
  public async getProductsByCollectionId(collectionId: number): Promise<ShopifyProduct[]> {
    try {
      const gid = `gid://shopify/Collection/${collectionId}`;
      const query = `
        query GetCollectionProducts($id: ID!, $first: Int!, $after: String) {
          collection(id: $id) {
            products(first: $first, after: $after) {
              pageInfo {
                hasNextPage
                endCursor
              }
              edges {
                node {
                  id
                  title
                  descriptionHtml
                  vendor
                  productType
                  handle
                  publishedAt
                  createdAt
                  updatedAt
                  tags
                  status
                  variants(first: 50) {
                    edges {
                      node {
                        id
                        title
                        price
                        compareAtPrice
                        sku
                        inventoryQuantity
                        inventoryPolicy
                        barcode
                        createdAt
                        updatedAt
                      }
                    }
                  }
                  options {
                    id
                    name
                    position
                    values
                  }
                  images(first: 20) {
                    edges {
                      node {
                        id
                        url
                        width
                        height
                        altText
                      }
                    }
                  }
                  collections(first: 20) {
                    edges {
                      node {
                        id
                        title
                      }
                    }
                  }
                }
              }
            }
          }
        }
      `;

      let allProducts: ShopifyProduct[] = [];
      let cursor: string | null = null;

      do {
        const data = await this.executeGraphQL<{
          collection: {
            products: {
              pageInfo: {
                hasNextPage: boolean;
                endCursor: string;
              };
              edges: Array<{
                node: ShopifyGraphQLProduct;
              }>;
            };
          } | null;
        }>(query, { id: gid, first: 50, after: cursor });

        if (!data.collection) {
          logger.warn(`Collection not found: ${collectionId}`);
          return [];
        }

        const edges: Array<{node: ShopifyGraphQLProduct}> = data.collection.products.edges;
        const products = edges.map(
          (edge) => convertGraphQLProductToRESTFormat(edge.node)
        );
        allProducts = [...allProducts, ...products];

        cursor = data.collection.products.pageInfo.hasNextPage
          ? data.collection.products.pageInfo.endCursor
          : null;
      } while (cursor);

      return allProducts;
    } catch (error: any) {
      logger.error(`Error fetching products for collection ${collectionId}: ${error.message}`);
      throw error;
    }
  }

  /**
   * Create a webhook in Shopify
   */
  public async createWebhook(topic: string, address: string): Promise<any> {
    try {
      const restEndpoint = `https://${this.storeUrl}/admin/api/${SHOPIFY_API_VERSION}/webhooks.json`;

      const response = await fetch(restEndpoint, {
        method: 'POST',
        headers: {
          'X-Shopify-Access-Token': this.accessToken,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          webhook: {
            topic,
            address,
            format: 'json',
          },
        }),
      });

      if (!response.ok) {
        const errorText = await response.text();
        throw new Error(`Shopify API error: ${response.status} ${response.statusText} - ${errorText}`);
      }

      const data = await response.json() as any;
      logger.info(`Created webhook for ${topic} pointing to ${address}`);
      return data.webhook;
    } catch (error: any) {
      logger.error(`Error creating webhook: ${error.message}`);
      throw error;
    }
  }

  /**
   * Delete a webhook in Shopify
   */
  public async deleteWebhook(webhookId: number): Promise<boolean> {
    try {
      const restEndpoint = `https://${this.storeUrl}/admin/api/${SHOPIFY_API_VERSION}/webhooks/${webhookId}.json`;

      const response = await fetch(restEndpoint, {
        method: 'DELETE',
        headers: {
          'X-Shopify-Access-Token': this.accessToken,
        },
      });

      if (!response.ok) {
        throw new Error(`Shopify API error: ${response.status} ${response.statusText}`);
      }

      logger.info(`Deleted webhook with ID ${webhookId}`);
      return true;
    } catch (error: any) {
      logger.error(`Error deleting webhook: ${error.message}`);
      return false;
    }
  }

  /**
   * Get all webhooks configured in the Shopify store
   */
  public async getWebhooks(): Promise<ShopifyWebhook[]> {
    try {
      const restEndpoint = `https://${this.storeUrl}/admin/api/${SHOPIFY_API_VERSION}/webhooks.json`;

      const response = await fetch(restEndpoint, {
        method: 'GET',
        headers: {
          'X-Shopify-Access-Token': this.accessToken,
        },
      });

      if (!response.ok) {
        throw new Error(`Shopify API error: ${response.status} ${response.statusText}`);
      }

      const data = await response.json() as any;
      return data.webhooks;
    } catch (error: any) {
      logger.error(`Error fetching webhooks: ${error.message}`);
      return [];
    }
  }

  /**
   * Test the Shopify credentials by making a simple API call
   */
  public async testCredentials(): Promise<boolean> {
    try {
      const restEndpoint = `https://${this.storeUrl}/admin/api/${SHOPIFY_API_VERSION}/webhooks.json`;
      const response = await fetch(restEndpoint, {
        method: 'GET',
        headers: {
          'X-Shopify-Access-Token': this.accessToken,
        },
      });
      return response.ok;
    } catch {
      return false;
    }
  }

  /**
   * Sets up all required webhooks for product synchronization
   */
  public async setupProductWebhooks(webhookUrl: string): Promise<number[]> {
    try {
      if (!webhookUrl) {
        throw new Error('Could not get webhook URL for product_webhook function');
      }

      logger.info(`Setting up webhooks to point to: ${webhookUrl}`);

      const topics = [
        'products/create',
        'products/update',
        'products/delete',
        'collections/update'
      ];

      const webhookPromises = topics.map((topic) => this.createWebhook(topic, webhookUrl));
      const webhooks = await Promise.all(webhookPromises);

      return webhooks.map((webhook) => webhook.id);
    } catch (error: any) {
      logger.error(`Error setting up product webhooks: ${error.message}`);
      throw error;
    }
  }
}

import { ShopifyProduct } from '../data/ShopifyProducts';
import { CollectionInfo } from './shopifyConverter';

/**
 * Transforms a Shopify product into an Optimizely Hub payload with nested types
 */
export function transformProductToPayload(product: ShopifyProduct) {
  // Split comma-separated tags into array
  const tags = product.tags
    ? product.tags.split(',').map((t) => t.trim()).filter((t) => t.length > 0)
    : [];

  // Transform variants
  const variants = (product.variants || []).map((v) => ({
    variant_id: v.id.toString(),
    title: v.title,
    price: parseFloat(v.price),
    compare_at_price: v.compare_at_price ? parseFloat(v.compare_at_price) : null,
    sku: v.sku,
    inventory_quantity: v.inventory_quantity,
    inventory_policy: v.inventory_policy,
    barcode: v.barcode,
    created_at: v.created_at,
    updated_at: v.updated_at,
  }));

  // Transform images
  const images = (product.images || []).map((img) => ({
    image_id: img.id.toString(),
    url: img.src,
    width: img.width,
    height: img.height,
    alt_text: img.alt,
    position: img.position,
  }));

  // Transform collections from the non-enumerable _collections property
  const collectionData: CollectionInfo[] = (product as any)._collections || [];
  const collections = collectionData.map((c) => ({
    collection_id: c.collection_id,
    title: c.title,
  }));

  // Transform options
  const options = (product.options || []).map((opt) => ({
    option_id: opt.id.toString(),
    name: opt.name,
    position: opt.position,
    values: opt.values,
  }));

  return {
    shopify_product_id: product.id.toString(),
    title: product.title,
    body_html: product.body_html,
    vendor: product.vendor,
    product_type: product.product_type,
    handle: product.handle,
    published_at: product.published_at,
    created_at: product.created_at,
    updated_at: product.updated_at,
    tags,
    status: product.status,
    variants,
    images,
    collections,
    options,
  };
}

import {
  Job,
  JobStatus,
  logger,
  notifications,
  sources,
  storage,
  ValueHash,
} from '@zaiusinc/app-sdk';
import { ShopifyClient } from '../lib/ShopifyClient';
import { transformProductToPayload } from '../lib/transformProductToPayload';

interface ImportJobStatus extends JobStatus {
  state: {
    currentPage: string | null;
    processedCount: number;
    failedProducts: Array<{id: number; error: string}>;
    retries: number;
  };
}

/**
 * Historical import job to sync all products from Shopify
 */
export class ImportProducts extends Job {
  private shopifyClient!: ShopifyClient;
  private includeArchived!: boolean;
  private includeDrafts!: boolean;

  /**
   * Prepares to run the import job by setting up the Shopify client
   */
  public async prepare(
    params: ValueHash,
    status?: ImportJobStatus
  ): Promise<ImportJobStatus> {
    logger.info('Preparing Shopify product import job');

    const settings: Record<string, string> = await storage.settings.get('shopify_credentials');
    const syncOptions: Record<string, string | number | boolean> = await storage.settings.get('sync_options');

    if (!settings.store_url || !settings.access_token) {
      logger.error('Shopify credentials are not fully configured');

      await notifications.error(
        'Shopify Sync',
        'Import Failed',
        'Shopify credentials are not fully configured. Please complete the Shopify Credentials section in app settings.'
      );

      return {
        state: {
          currentPage: null,
          processedCount: 0,
          failedProducts: [],
          retries: 0
        },
        complete: true
      };
    }

    this.shopifyClient = new ShopifyClient({
      storeUrl: settings.store_url,
      accessToken: settings.access_token
    });

    this.includeArchived = syncOptions.include_archived === true;
    this.includeDrafts = syncOptions.include_drafts === true;

    logger.info(
      `Shopify sync config - include archived: ${this.includeArchived}, ` +
      `include drafts: ${this.includeDrafts}`
    );

    if (status) {
      logger.info(`Resuming previous import job. Processed so far: ${status.state.processedCount}`);
      return status;
    }

    return {
      state: {
        currentPage: null,
        processedCount: 0,
        failedProducts: [],
        retries: 0
      },
      complete: false
    };
  }

  /**
   * Performs the import job, processing one batch of products at a time
   */
  public async perform(
    status: ImportJobStatus
  ): Promise<ImportJobStatus> {
    const state = status.state;

    try {
      logger.info(`Fetching products from Shopify${state.currentPage ? ' (continued)' : ''}`);

      const result = await this.shopifyClient.getProducts(
        50,
        state.currentPage || undefined
      );

      let products = result.products;
      if (!this.includeArchived || !this.includeDrafts) {
        products = products.filter((product) => {
          if (!this.includeArchived && product.status === 'archived') {
            return false;
          }
          if (!this.includeDrafts && product.status === 'draft') {
            return false;
          }
          return true;
        });
      }

      for (const product of products) {
        logger.debug(`Processing product: ${product.id} - ${product.title}`);
        const productPayload = transformProductToPayload(product);
        await sources.emit('Product', {data: productPayload as any});
      }

      state.processedCount += products.length;
      logger.info(`Processed ${state.processedCount} products so far`);

      state.currentPage = result.nextPageInfo || null;

      if (!state.currentPage) {
        logger.info(`Completed importing ${state.processedCount} products from Shopify`);
        await notifications.success(
          'Shopify Sync',
          'Import Completed Successfully',
          `Imported ${state.processedCount} products from Shopify to Optimizely Hub.`
        );

        status.complete = true;
      }

      return status;
    } catch (error: any) {
      logger.error(`Shopify import error: ${error.message}`);

      if (state.retries >= 5) {
        await notifications.error(
          'Shopify Sync',
          'Import Failed',
          `Error importing products from Shopify: ${error.message}. Maximum retries exceeded.`
        );

        status.complete = true;
      } else {
        state.retries++;
        logger.info(`Retry ${state.retries}/5 after error. Waiting before retry...`);

        await new Promise((resolve) => setTimeout(resolve, state.retries * 5000));
      }

      return status;
    }
  }
}

import {
  Lifecycle as AppLifecycle,
  AuthorizationGrantResult,
  jobs,
  LifecycleResult,
  LifecycleSettingsResult,
  logger,
  Request,
  storage, SubmittedFormData
} from '@zaiusinc/app-sdk';
import { ShopifyClient } from '../lib/ShopifyClient';

export class Lifecycle extends AppLifecycle {
  public async onInstall(): Promise<LifecycleResult> {
    try {
      logger.info('Performing Install');
      return {success: true};
    } catch (error: any) {
      logger.error('Error during installation:', error);
      return {success: false, retryable: true, message: `Error during installation: ${error}`};
    }
  }

  public async onSettingsForm(
    section: string, action: string, formData: SubmittedFormData
  ): Promise<LifecycleSettingsResult> {
    const result = new LifecycleSettingsResult();
    try {
      if (action === 'trigger_full_import') {
        return this.handleTriggerFullImport(result);
      }

      if (section === 'shopify_credentials') {
        return this.handleShopifyCredentials(formData, result);
      }

      await storage.settings.put(section, formData);
      return result;
    } catch {
      return result.addToast('danger', 'Sorry, an unexpected error occurred. Please try again in a moment.');
    }
  }

  private async handleTriggerFullImport(
    result: LifecycleSettingsResult
  ): Promise<LifecycleSettingsResult> {
    const settings: Record<string, string> = await storage.settings.get('shopify_credentials');
    if (!settings.store_url || !settings.access_token) {
      return result.addToast('danger', 'Please configure your Shopify credentials before running an import.');
    }

    await jobs.trigger('import_products', {});
    return result.addToast(
      'success', 'Full product import has been triggered. You will be notified when it completes.'
    );
  }

  private async handleShopifyCredentials(
    formData: SubmittedFormData, result: LifecycleSettingsResult
  ): Promise<LifecycleSettingsResult> {
    const storeUrl = formData.store_url as string;
    const accessToken = formData.access_token as string;

    if (!storeUrl || !accessToken) {
      return result.addToast('danger', 'Please provide both a store URL and access token.');
    }

    const client = new ShopifyClient({storeUrl, accessToken});
    const isValid = await client.testCredentials();

    if (!isValid) {
      return result.addToast('danger', 'Invalid Shopify credentials. Please check your store URL and access token.');
    }

    await storage.settings.put('shopify_credentials', formData);
    return result.addToast('success', 'Shopify credentials saved and verified successfully.');
  }

  public async onAuthorizationRequest(
    _section: string, _formData: SubmittedFormData
  ): Promise<LifecycleSettingsResult> {
    const result = new LifecycleSettingsResult();
    return result.addToast('danger', 'Sorry, OAuth is not supported.');
  }

  public async onAuthorizationGrant(_request: Request): Promise<AuthorizationGrantResult> {
    return new AuthorizationGrantResult('').addToast('danger', 'Sorry, OAuth is not supported.');
  }

  public async onUpgrade(_fromVersion: string): Promise<LifecycleResult> {
    return {success: true};
  }

  public async onFinalizeUpgrade(_fromVersion: string): Promise<LifecycleResult> {
    return {success: true};
  }

  public async onAfterUpgrade(): Promise<LifecycleResult> {
    return {success: true};
  }

  public async onUninstall(): Promise<LifecycleResult> {
    return {success: true};
  }
}

functions:
  product_webhook:
    entry_point: ProductWebhook
    description: Receives Shopify product webhooks for real-time sync

meta:
  app_id: ocp_sync_source_reference_app
  display_name: Shopify Source Sync Reference App
  version: 1.0.0-dev.1
  vendor: optimizely
  summary: Shopify Source Sync Reference App
  support_url: https://support.optimizely.com
  contact_email: [email protected]
  categories:
    - Commerce Platform
  availability:
    - all

runtime: node22

sources:
  Product:
    description: Shopify Product
    schema: shopify_products

functions:
  product_webhook:
    entry_point: ProductWebhook
    description: Receives Shopify product webhooks for real-time sync

jobs:
  import_products:
    entry_point: ImportProducts
    description: Performs a one-time import of all Shopify products

import { Function, Request, Response, sources, storage, logger } from '@zaiusinc/app-sdk';
import { ShopifyProduct } from '../data/ShopifyProducts';
import { ShopifyClient } from '../lib/ShopifyClient';
import { transformProductToPayload } from '../lib/transformProductToPayload';

export class ProductWebhook extends Function {
  public constructor(request: Request) {
    super(request);
  }

  public async perform(): Promise<Response> {
    try {
      logger.info('[ProductWebhook] Processing incoming Shopify product');

      // Get the product data from the request body
      const shopifyProduct = this.request.bodyJSON as ShopifyProduct;

      if (!shopifyProduct || !shopifyProduct.id) {
        logger.error('Invalid product data received');
        return new Response(400, 'Invalid product data. Missing required fields.');
      }

      const topic = this.request.headers.get('x-shopify-topic');

      // Handle collection updates — re-fetch all products in the collection and emit them
      if (topic === 'collections/update') {
        const collectionId = shopifyProduct.id;
        logger.info(`[ProductWebhook] Processing collection update for collection ${collectionId}`);

        const settings: Record<string, string> = await storage.settings.get('shopify_credentials');
        if (!settings?.store_url || !settings?.access_token) {
          logger.error('[ProductWebhook] Missing credentials for collection update');
          return new Response(500, {success: false, error: 'Missing Shopify credentials'});
        }

        const shopifyClient = new ShopifyClient({
          storeUrl: settings.store_url,
          accessToken: settings.access_token
        });
        const products = await shopifyClient.getProductsByCollectionId(collectionId);

        for (const product of products) {
          const productPayload = transformProductToPayload(product);
          await sources.emit('Product', {data: productPayload as any});
        }

        logger.info(`[ProductWebhook] Emitted ${products.length} products from collection ${collectionId}`);
        return new Response(200, {
          success: true,
          message: `Processed collection update, emitted ${products.length} products`,
          collection_id: collectionId
        });
      }

      // Handle product deletions — product no longer exists in Shopify, so emit with _isDeleted flag
      if (topic === 'products/delete') {
        logger.info(`[ProductWebhook] Processing product deletion for product ${shopifyProduct.id}`);
        await sources.emit('Product', {data: {shopify_product_id: shopifyProduct.id.toString(), _isDeleted: true}});
        return new Response(200, {
          success: true,
          message: 'Successfully processed product deletion',
          shopify_product_id: shopifyProduct.id
        });
      }

      // Re-fetch product via GraphQL to include collection data not present in webhook payloads
      let productForTransform: ShopifyProduct = shopifyProduct;
      try {
        const settings: Record<string, string> = await storage.settings.get('shopify_credentials');
        if (settings?.store_url && settings?.access_token) {
          const shopifyClient = new ShopifyClient({
            storeUrl: settings.store_url,
            accessToken: settings.access_token
          });
          productForTransform = await shopifyClient.getProductById(shopifyProduct.id);
          logger.info(`[ProductWebhook] Re-fetched product ${shopifyProduct.id} with collection data`);
        } else {
          logger.warn('[ProductWebhook] Missing credentials, using raw webhook data');
        }
      } catch (error: any) {
        const pid = shopifyProduct.id;
        logger.warn(`[ProductWebhook] Failed to re-fetch product ${pid}, using raw webhook data: ${error.message}`);
      }

      // Transform the product data to Hub object format
      const payload = transformProductToPayload(productForTransform);

      logger.debug('Emitting transformed product payload', payload);
      await sources.emit('Product', {data: payload as any});

      return new Response(200, {
        success: true,
        message: `Successfully processed product: ${shopifyProduct.title}`,
        shopify_product_id: shopifyProduct.id
      });
    } catch (error: any) {
      logger.error(`Error processing Shopify product: ${error.message}`);
      return new Response(500, {
        success: false,
        error: `An error occurred while processing the product: ${error.message}`
      });
    }
  }
}

await sources.emit('Product', {data: {shopify_product_id: id.toString(), _isDeleted: true}});

import { logger } from '@zaiusinc/app-sdk';
import { ShopifyClient, ShopifyCredentials } from './ShopifyClient';

export class ShopifyWebhookManager {
  private credentials: ShopifyCredentials;

  public constructor(credentials: ShopifyCredentials) {
    this.credentials = credentials;
  }

  public async createWebhooks(webhookUrl: string, client?: ShopifyClient): Promise<void> {
    if (!webhookUrl) {
      throw new Error('Webhook URL is not configured');
    }

    const shopifyClient = client || new ShopifyClient(this.credentials);
    await shopifyClient.setupProductWebhooks(webhookUrl);
  }

  public async deleteWebhooks(webhookUrl: string, client?: ShopifyClient): Promise<void> {
    const shopifyClient = client || new ShopifyClient(this.credentials);
    const webhooks = await shopifyClient.getWebhooks();
    const matching = webhooks.filter((webhook) => webhook.address === webhookUrl);

    if (matching.length === 0) {
      return;
    }

    const failedDeletions: number[] = [];
    for (const webhook of matching) {
      try {
        await shopifyClient.deleteWebhook(webhook.id!);
      } catch (err: any) {
        logger.error(`Failed to delete webhook ${webhook.id}: ${err?.message}`);
        failedDeletions.push(webhook.id!);
      }
    }

    if (failedDeletions.length > 0) {
      throw new Error(`Failed to delete webhooks: ${failedDeletions.join(', ')}`);
    }

    logger.info('Webhook deletion completed successfully');
  }
}

import {
  Lifecycle as AppLifecycle,
  AuthorizationGrantResult,
  functions,
  jobs,
  LifecycleResult,
  LifecycleSettingsResult,
  logger,
  Request,
  storage, SubmittedFormData
} from '@zaiusinc/app-sdk';
import { ShopifyClient } from '../lib/ShopifyClient';
import { ShopifyWebhookManager } from '../lib/ShopifyWebhookManager';

export class Lifecycle extends AppLifecycle {
  public async onInstall(): Promise<LifecycleResult> {
    try {
      logger.info('Performing Install');
      return {success: true};
    } catch (error: any) {
      logger.error('Error during installation:', error);
      return {success: false, retryable: true, message: `Error during installation: ${error}`};
    }
  }

  public async onSettingsForm(
    section: string, action: string, formData: SubmittedFormData
  ): Promise<LifecycleSettingsResult> {
    const result = new LifecycleSettingsResult();
    try {
      if (action === 'trigger_full_import') {
        return this.handleTriggerFullImport(result);
      }

      if (section === 'shopify_credentials') {
        return this.handleShopifyCredentials(formData, result);
      }

      await storage.settings.put(section, formData);
      return result;
    } catch {
      return result.addToast('danger', 'Sorry, an unexpected error occurred. Please try again in a moment.');
    }
  }

  private async handleTriggerFullImport(
    result: LifecycleSettingsResult
  ): Promise<LifecycleSettingsResult> {
    const settings: Record<string, string> = await storage.settings.get('shopify_credentials');
    if (!settings.store_url || !settings.access_token) {
      return result.addToast('danger', 'Please configure your Shopify credentials before running an import.');
    }

    await jobs.trigger('import_products', {});
    return result.addToast(
      'success', 'Full product import has been triggered. You will be notified when it completes.'
    );
  }

  private async handleShopifyCredentials(
    formData: SubmittedFormData, result: LifecycleSettingsResult
  ): Promise<LifecycleSettingsResult> {
    const storeUrl = formData.store_url as string;
    const accessToken = formData.access_token as string;

    if (!storeUrl || !accessToken) {
      return result.addToast('danger', 'Please provide both a store URL and access token.');
    }

    const client = new ShopifyClient({storeUrl, accessToken});
    const isValid = await client.testCredentials();

    if (!isValid) {
      return result.addToast('danger', 'Invalid Shopify credentials. Please check your store URL and access token.');
    }

    await storage.settings.put('shopify_credentials', formData);

    try {
      const endpoints = await functions.getEndpoints();
      const webhookUrl = endpoints['product_webhook'];

      const webhookManager = new ShopifyWebhookManager({storeUrl, accessToken});
      try {
        await webhookManager.deleteWebhooks(webhookUrl, client);
      } catch {
        // Ignore deletion errors for old webhooks
      }
      await webhookManager.createWebhooks(webhookUrl, client);
      await storage.settings.patch('shopify_credentials', {webhooks_active: true, webhook_error: ''});

      return result.addToast(
        'success',
        `Connected to Shopify store: ${storeUrl}. Webhooks configured for real-time sync.`
      );
    } catch (webhookError: any) {
      logger.error(`Error setting up webhooks: ${webhookError.message}`);
      await storage.settings.patch('shopify_credentials', {
        webhooks_active: false,
        webhook_error: webhookError.message
      });
      return result.addToast(
        'success',
        `Connected to Shopify store: ${storeUrl}, but webhook setup failed: ${webhookError.message}`
      );
    }
  }

  public async onAuthorizationRequest(
    _section: string, _formData: SubmittedFormData
  ): Promise<LifecycleSettingsResult> {
    const result = new LifecycleSettingsResult();
    return result.addToast('danger', 'Sorry, OAuth is not supported.');
  }

  public async onAuthorizationGrant(_request: Request): Promise<AuthorizationGrantResult> {
    return new AuthorizationGrantResult('').addToast('danger', 'Sorry, OAuth is not supported.');
  }

  public async onUpgrade(_fromVersion: string): Promise<LifecycleResult> {
    return {success: true};
  }

  public async onFinalizeUpgrade(_fromVersion: string): Promise<LifecycleResult> {
    return {success: true};
  }

  public async onAfterUpgrade(): Promise<LifecycleResult> {
    return {success: true};
  }

  public async onUninstall(): Promise<LifecycleResult> {
    try {
      logger.info('Uninstalling app, cleaning up webhooks...');

      const settings: Record<string, string> = await storage.settings.get('shopify_credentials');
      if (settings?.store_url && settings?.access_token) {
        const endpoints = await functions.getEndpoints();
        const webhookUrl = endpoints['product_webhook'];

        const webhookManager = new ShopifyWebhookManager({
          storeUrl: settings.store_url,
          accessToken: settings.access_token
        });
        await webhookManager.deleteWebhooks(webhookUrl);
        await storage.settings.patch('shopify_credentials', {webhooks_active: false});
      }

      return {success: true};
    } catch (error: any) {
      logger.error(`Error during uninstall: ${error.message}`);
      return {success: true, message: `Warning: Unable to clean up all webhooks: ${error.message}`};
    }
  }
}