@tailor-platform/shopify

@tailor-platform/shopify

A drop-in replacement for @shopify/admin-api-client that uses Tailor Platform integration tokens instead of Shopify offline tokens.

Installation

npm install @tailor-platform/shopify
# or
yarn add @tailor-platform/shopify
# or
pnpm add @tailor-platform/shopify

Usage

Basic Usage

import { createAdminApiClient, ApiVersion } from '@tailor-platform/shopify';

const client = createAdminApiClient({
  storeDomain: 'your-shop.myshopify.com',
  apiVersion: ApiVersion.October25, // or ApiVersion.Unstable
  accessToken: 'tst_YOUR_INTEGRATION_TOKEN', // Integration token from Tailor Platform
});

// Make GraphQL requests
const { data, errors } = await client.request(
  `
  query getProduct($id: ID!) {
    product(id: $id) {
      title
      handle
      description
    }
  }
`,
  {
    variables: {
      id: 'gid://shopify/Product/123456789',
    },
  }
);

Type-Safe Usage

The SDK provides full TypeScript support with automatic type inference:

import {
  createAdminApiClient,
  ApiVersion,
  gql,
} from '@tailor-platform/shopify';

// Define your types
interface ProductData {
  product: {
    id: string;
    title: string;
    handle: string;
    description: string;
  };
}

interface ProductVariables {
  id: string;
}

const client = createAdminApiClient({
  storeDomain: 'your-shop.myshopify.com',
  apiVersion: ApiVersion.October25,
  accessToken: 'tst_YOUR_INTEGRATION_TOKEN',
});

// Type-safe query with gql template tag
const productQuery = gql<ProductData, ProductVariables>`
  query getProduct($id: ID!) {
    product(id: $id) {
      id
      title
      handle
      description
    }
  }
`;

// TypeScript automatically infers types from the gql tag
const { data, errors } = await client.request(productQuery, {
  variables: {
    id: 'gid://shopify/Product/123456789',
  },
});

// data is fully typed as ProductData
if (data?.product) {
  console.log(data.product.title); // TypeScript knows this is a string
}

// Alternative: Use types explicitly without gql
const { data } = await client.request<ProductData, ProductVariables>(
  `query getProduct($id: ID!) { ... }`,
  { variables: { id: 'gid://shopify/Product/123456789' } }
);

Working with Mutations

interface CreateProductData {
  productCreate: {
    product: {
      id: string;
      title: string;
    };
    userErrors: Array<{
      field: string[];
      message: string;
    }>;
  };
}

interface CreateProductVariables {
  input: {
    title: string;
    descriptionHtml?: string;
    vendor?: string;
  };
}

const createProductMutation = gql<CreateProductData, CreateProductVariables>`
  mutation createProduct($input: ProductInput!) {
    productCreate(input: $input) {
      product {
        id
        title
      }
      userErrors {
        field
        message
      }
    }
  }
`;

// Type inference works automatically - no need to specify types again
const { data } = await client.request(createProductMutation, {
  variables: {
    input: {
      title: 'New Product',
      descriptionHtml: '<p>Description</p>',
    },
  },
});

// Handle user errors
if (data?.productCreate.userErrors.length > 0) {
  console.error('Failed to create product:', data.productCreate.userErrors);
}

API Versions

The SDK exports constants for all available Shopify API versions:

import { ApiVersion, LATEST_API_VERSION } from '@tailor-platform/shopify';

// Use a specific version
const client = createAdminApiClient({
  storeDomain: 'your-shop.myshopify.com',
  apiVersion: ApiVersion.January25,
  accessToken: 'tst_YOUR_TOKEN',
});

// Use the latest stable version
const client2 = createAdminApiClient({
  storeDomain: 'your-shop.myshopify.com',
  apiVersion: LATEST_API_VERSION, // Currently October25
  accessToken: 'tst_YOUR_TOKEN',
});

// Use unstable version for testing new features
const client3 = createAdminApiClient({
  storeDomain: 'your-shop.myshopify.com',
  apiVersion: ApiVersion.Unstable,
  accessToken: 'tst_YOUR_TOKEN',
});

Type Safety Features

Typed GraphQL Documents

The gql template tag creates typed documents that carry type information:

const query = gql<ResponseType, VariablesType>`...`;
// Types flow automatically to client.request()

Benefits

• Auto-completion: Full IntelliSense support for response data
• Type checking: Catch errors at compile time, not runtime
• Type inference: No need to specify types twice
• Better DX: See available fields and their types while coding

API Compatibility

This SDK provides the same interface as @shopify/admin-api-client, making it a drop-in replacement. Simply replace your import statement and use your Tailor Platform integration token instead of a Shopify offline token.

Response Types

All GraphQL responses follow this structure:

interface GraphQLResponse<TData> {
  data?: TData;
  errors?: GraphQLError[];
  extensions?: {
    cost?: {
      requestedQueryCost: number;
      actualQueryCost: number;
      throttleStatus: {
        maximumAvailable: number;
        currentlyAvailable: number;
        restoreRate: number;
      };
    };
    [key: string]: unknown;
  };
}

interface GraphQLError {
  message: string;
  extensions?: Record<string, unknown>;
  path?: (string | number)[];
  locations?: Array<{
    line: number;
    column: number;
  }>;
}

Error Handling

The SDK provides custom error types for better error handling:

import {
  ShopifyApiError,
  NetworkError,
  ConfigurationError,
} from '@tailor-platform/shopify';

try {
  const { data } = await client.request(query);
} catch (error) {
  if (error instanceof ShopifyApiError) {
    // Handle Shopify API errors
    console.error('Shopify API error:', error.errors);
  } else if (error instanceof NetworkError) {
    // Handle network errors
    console.error('Network error:', error.statusCode);
  } else if (error instanceof ConfigurationError) {
    // Handle configuration errors
    console.error('Configuration error:', error.message);
  }
}

Webhook Management

The SDK provides webhook support with Tailor Platform's managed webhook system, offering automatic registration, reliable delivery, and retry logic.

Creating Webhooks

const CREATE_WEBHOOK = gql`
  mutation webhookSubscriptionCreate(
    $topic: WebhookSubscriptionTopic!
    $webhookSubscription: WebhookSubscriptionInput!
  ) {
    webhookSubscriptionCreate(
      topic: $topic
      webhookSubscription: $webhookSubscription
    ) {
      webhookSubscription {
        id
        topic
        callbackUrl
      }
      userErrors {
        field
        message
      }
    }
  }
`;

const { data } = await client.request(CREATE_WEBHOOK, {
  variables: {
    topic: 'ORDERS_CREATE',
    webhookSubscription: {
      callbackUrl: 'https://your-app.com/webhooks/orders',
    },
  },
});

Webhook Topics

The SDK exports webhook topic utilities:

import {
  getWebhookEventName,
  getWebhookTopicEnum,
} from '@tailor-platform/shopify';

// Convert between GraphQL enum and event names
getWebhookEventName('ORDERS_CREATE'); // 'orders/create'
getWebhookTopicEnum('orders/create'); // 'ORDERS_CREATE'

Other Webhook Operations

// List webhooks
const LIST_WEBHOOKS = gql`
  query webhookSubscriptions($first: Int!) {
    webhookSubscriptions(first: $first) {
      edges {
        node {
          id
          topic
          callbackUrl
        }
      }
    }
  }
`;

// Update webhook
const UPDATE_WEBHOOK = gql`
  mutation webhookSubscriptionUpdate(
    $id: ID!
    $webhookSubscription: WebhookSubscriptionInput!
  ) {
    webhookSubscriptionUpdate(
      id: $id
      webhookSubscription: $webhookSubscription
    ) {
      webhookSubscription {
        id
        callbackUrl
      }
      userErrors {
        field
        message
      }
    }
  }
`;

// Delete webhook
const DELETE_WEBHOOK = gql`
  mutation webhookSubscriptionDelete($id: ID!) {
    webhookSubscriptionDelete(id: $id) {
      deletedWebhookSubscriptionId
      userErrors {
        field
        message
      }
    }
  }
`;

Webhook Reliability

Tailor Platform automatically:

• Registers webhooks with Shopify
• Retries failed deliveries with exponential backoff
• Pauses webhooks after 10 consecutive failures
• Provides monitoring through the dashboard

Common Webhook Topics

• Orders: ORDERS_CREATE, ORDERS_UPDATED, ORDERS_PAID, ORDERS_FULFILLED
• Products: PRODUCTS_CREATE, PRODUCTS_UPDATE, PRODUCTS_DELETE
• Customers: CUSTOMERS_CREATE, CUSTOMERS_UPDATE, CUSTOMERS_DELETE
• Inventory: INVENTORY_ITEMS_CREATE, INVENTORY_LEVELS_UPDATE

For a complete list, see the Shopify documentation.