Zapier Store API Client

A typesafe TypeScript client for the Zapier Store API. This client provides a clean, intuitive interface for storing and retrieving JSON-serializable data with full TypeScript support.

Features

• 🚀 Fully TypeScript - Complete type safety with comprehensive interfaces
• 🔐 Flexible Authentication - Support for both query parameter and header-based secrets
• 🔄 Automatic Retries - Built-in retry logic with exponential backoff
• ⏱️ Configurable Timeouts - Customizable request timeouts
• 🧪 Comprehensive Testing - Full test coverage with Jest
• 📚 Well Documented - JSDoc comments and examples for all methods
• 🎯 Convenience Methods - Helper methods for common operations

Installation

npm install zapier-store-client

Quick Start

import { ZapierStoreClient } from 'zapier-store-client';

// Create a client instance
const client = new ZapierStoreClient();

// Set your secret (get this from Zapier)
const auth = { type: 'query' as const, secret: 'your-secret-here' };

// Store some data
await client.setRecords(auth, {
  user: 'john',
  count: 42,
  preferences: { theme: 'dark' }
});

// Retrieve data
const records = await client.getRecords(auth);
console.log(records.data); // { user: 'john', count: 42, preferences: { theme: 'dark' } }

// Get specific keys
const userData = await client.getRecords(auth, ['user', 'count']);
console.log(userData.data); // { user: 'john', count: 42 }

// Increment a counter
await client.increment(auth, 'count', 1);

// Work with lists
await client.pushToList(auth, 'items', 'new-item');
await client.popFromList(auth, 'items');

API Reference

Constructor

new ZapierStoreClient(config?: ZapierStoreConfig)

Configuration Options:

• baseUrl - API base URL (default: https://store.zapier.com)
• timeout - Request timeout in milliseconds (default: 30000)
• retries - Number of retry attempts (default: 3)
• retryDelay - Base delay between retries in milliseconds (default: 1000)

Authentication

The client supports two authentication methods:

// Query parameter authentication
const authQuery = { type: 'query' as const, secret: 'your-secret' };

// Header-based authentication
const authHeader = { type: 'header' as const, secret: 'your-secret' };

Core Methods

getRecords(auth, keys?)

Retrieve all records or specific keys.

// Get all records
const allRecords = await client.getRecords(auth);

// Get specific keys
const specificRecords = await client.getRecords(auth, ['key1', 'key2']);

setRecords(auth, data)

Store new records.

await client.setRecords(auth, {
  key1: 'value1',
  key2: { nested: 'data' },
  key3: [1, 2, 3]
});

patchRecords(auth, patchRequest)

Update records using PATCH operations.

// Increment a value
await client.patchRecords(auth, {
  action: 'increment_by',
  data: { key: 'counter', amount: 5 }
});

// Push to a list
await client.patchRecords(auth, {
  action: 'list_push',
  data: { key: 'items', value: 'new-item' }
});

deleteRecords(auth, key?)

Delete all records or a specific key.

// Delete all records
await client.deleteRecords(auth);

// Delete specific key
await client.deleteRecords(auth, 'key1');

Convenience Methods

increment(auth, key, amount?)

Increment a numeric value (defaults to 1).

await client.increment(auth, 'counter', 5);
await client.increment(auth, 'counter'); // increments by 1

pushToList(auth, key, value)

Push a value to a list.

await client.pushToList(auth, 'items', 'new-item');

popFromList(auth, key)

Pop a value from a list.

await client.popFromList(auth, 'items');

Supported PATCH Actions

The client supports all PATCH actions from the Zapier Store API:

• increment_by - Increment a numeric value
• set_value_if - Set a value if a condition is met
• remove_child_value - Remove a nested property
• set_child_value - Set a nested property
• list_push - Add an item to a list
• list_pop - Remove an item from a list

Error Handling

The client includes comprehensive error handling:

try {
  const records = await client.getRecords(auth);
} catch (error) {
  if (error instanceof Error) {
    console.error('API Error:', error.message);
  }
}

Common Error Scenarios:

• 403 Forbidden - Invalid secret or rate limit exceeded
• 400 Bad Request - Invalid request format
• Network Errors - Automatically retried with exponential backoff
• Timeouts - Configurable request timeouts

Rate Limiting & Retries

The client automatically handles transient failures:

• Retry Logic - Configurable retry attempts with exponential backoff
• Smart Retries - Client errors (4xx) are not retried
• Rate Limiting - Respects API rate limits and returns appropriate errors

TypeScript Support

Full TypeScript support with strict type checking:

import { 
  ZapierStoreClient, 
  AuthMethod, 
  PatchRequest,
  IncrementByData 
} from 'zapier-store-client';

// Type-safe authentication
const auth: AuthMethod = { type: 'query', secret: 'secret' };

// Type-safe patch requests
const incrementRequest: PatchRequest = {
  action: 'increment_by',
  data: { key: 'counter', amount: 1 } as IncrementByData
};

Examples

User Session Management

const client = new ZapierStoreClient();
const auth = { type: 'query', secret: 'session-secret' };

// Store user session
await client.setRecords(auth, {
  userId: '12345',
  lastLogin: new Date().toISOString(),
  preferences: { theme: 'dark', language: 'en' }
});

// Update last activity
await client.increment(auth, 'activityCount');

// Add to login history
await client.pushToList(auth, 'loginHistory', new Date().toISOString());

Counter Management

const client = new ZapierStoreClient();
const auth = { type: 'header', secret: 'counter-secret' };

// Initialize counter
await client.setRecords(auth, { pageViews: 0 });

// Increment on page view
await client.increment(auth, 'pageViews');

// Get current count
const { data } = await client.getRecords(auth, ['pageViews']);
console.log(`Page views: ${data.pageViews}`);

Feature Flags

const client = new ZapierStoreClient();
const auth = { type: 'query', secret: 'feature-secret' };

// Set feature flags
await client.setRecords(auth, {
  newUI: true,
  betaFeatures: ['chat', 'analytics'],
  userTier: 'premium'
});

// Conditional feature access
const { data } = await client.getRecords(auth, ['newUI', 'userTier']);
if (data.newUI && data.userTier === 'premium') {
  // Enable premium features
}

Development

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Building

# Build the project
npm run build

# Clean build artifacts
npm run clean

Linting

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

API Limits

The Zapier Store API has the following limits:

• Secret length: Up to 36 characters
• Key length: Up to 32 characters
• Value size: Under 2500 bytes
• Records per secret: Up to 500 values
• Inactive data: Pruned after 2 months

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Documentation: Zapier Store API
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Changelog

1.0.0

• Initial release
• Full TypeScript support
• All Zapier Store API endpoints
• Comprehensive error handling
• Automatic retry logic
• Convenience methods for common operations