@dscodotco/theme-cli/docs/api/theme-api.md

A CLI tool for developing Shopify themes

# ThemeAPI Reference

The `ThemeAPI` class provides a high-level interface for interacting with Shopify themes, managing metadata, and handling page operations.

## Installation

```typescript
import { ThemeAPI } from '@dscodotco/theme-cli';
import { Shopify } from 'shopify-api-node';
import { ThemeManager } from './theme-manager';

const shopify = new Shopify({
  shopName: 'your-store',
  accessToken: 'your-access-token'
});

const themeManager = new ThemeManager({
  credentials: {
    storeName: 'your-store',
    apiKey: 'your-api-key',
    password: 'your-password'
  },
  themeId: 123456789
});

const themeAPI = new ThemeAPI(shopify, themeManager, './my-theme');
```

## Core Methods

### Theme Metadata

```typescript
// Get complete theme metadata
const metadata = await themeAPI.getMetadata();
console.log('Theme sections:', metadata.sections);
console.log('Theme templates:', metadata.templates);

// Get all available pages
const pages = await themeAPI.getPages();
console.log('Available pages:', pages);

// Get specific page metadata
const homePageMeta = await themeAPI.getPageMetadata('/');
console.log('Home page template:', homePageMeta.template);
```

### Template Management

```typescript
// Get template dependencies
const templateDeps = await themeAPI.getTemplateDependencies('product');
console.log('Sections used:', templateDeps.sections);
console.log('Snippets used:', templateDeps.snippets);

// Find pages using specific template
const customPages = await themeAPI.findPagesByTemplate('custom-template');
console.log('Pages using custom template:', customPages);
```

### Theme Analysis

```typescript
// Build dependency graph
const graph = await themeAPI.buildDependencyGraph();
console.log('Template dependencies:', graph);

// Find unused sections
const unusedSections = await themeAPI.findUnusedSections();
console.log('Unused sections:', unusedSections);

// Generate theme report
const report = await themeAPI.generateThemeReport();
console.log('Theme structure:', report);
```

## Advanced Usage

### File Watching

```typescript
// Watch for theme changes
themeAPI.watchTheme((event, path) => {
  console.log(`File ${path} was ${event}`);
  themeAPI.invalidateCache(); // Clear cached metadata
});
```

### Custom Template Analysis

```typescript
// Analyze template structure
const analysis = await themeAPI.analyzeTemplate('product', {
  includeSections: true,
  includeSnippets: true,
  includeAssets: true
});

console.log('Template structure:', analysis);
```

### Page Operations

```typescript
// List all dynamic pages
const dynamicPages = await themeAPI.getDynamicPages();
console.log('Dynamic pages:', dynamicPages);

// Get page by handle
const productPage = await themeAPI.getPageByHandle('products/example-product');
console.log('Product page:', productPage);
```

## Error Handling

```typescript
try {
  const metadata = await themeAPI.getMetadata();
} catch (error) {
  if (error.code === 'THEME_NOT_FOUND') {
    console.error('Theme not found:', error.message);
  } else if (error.code === 'API_ERROR') {
    console.error('API error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}
```

## Best Practices

1. **Cache Management**
   - Use `invalidateCache()` when files change
   - Implement appropriate caching strategies for production

2. **Error Handling**
   - Always wrap API calls in try/catch blocks
   - Handle specific error types appropriately

3. **Resource Management**
   - Close file watchers when no longer needed
   - Clean up temporary files and resources

4. **Performance**
   - Use batch operations when possible
   - Implement pagination for large datasets

## TypeScript Interfaces

```typescript
interface ThemeMetadata {
  sections: string[];
  templates: {
    [key: string]: {
      type: string;
      sections: string[];
      snippets: string[];
    };
  };
  assets: string[];
}

interface PageMetadata {
  path: string;
  template: string;
  type: 'static' | 'dynamic';
  handle?: string;
  sections: string[];
}

interface TemplateDependencies {
  sections: string[];
  snippets: string[];
  assets: string[];
}
```

## Events

The ThemeAPI emits several events that you can listen to:

```typescript
themeAPI.on('fileChange', (path) => {
  console.log('File changed:', path);
});

themeAPI.on('cacheInvalidated', () => {
  console.log('Cache was invalidated');
});

themeAPI.on('error', (error) => {
  console.error('Error occurred:', error);
});
```