PostSync - Type-safe API Clients from Postman Collections

Why Choose PostSync?

Type Safety

Full TypeScript support with auto-generated interfaces for endpoints and responses, catching errors before runtime.

Auto-Sync

Update your Postman collection and your API client updates automatically - no manual code changes required.

Lightweight

Zero dependencies and tree-shakable codebase ensures minimal impact on your bundle size.

SSR Compatible

Works seamlessly in server-side rendering environments like Next.js and Remix.

Customizable

Configure headers, timeouts, and error handling to match your project's requirements.

Framework Agnostic

Use with any JavaScript or TypeScript project, from React to Node.js and beyond.

Installation & Setup

Getting Started

1. Install the package

npm install postsync

2. Export your Postman collection

Export your collection as JSON from Postman and save it in your project.

PostSync supports Postman Collection Format v2.0 and v2.1

3. Initialize your API client

import { createApiClient } from 'postsync';
import postmanCollection from './postman-collection.json';

export const api = createApiClient(postmanCollection, {
  baseUrl: 'https://api.example.com'
});

DEVELOPER EXPERIENCE

How to Use PostSync

Our intuitive API makes integrating with your Postman collections straightforward and type-safe. Here's how to get the most out of PostSync in your projects.

// Initialize your API client
import { createApiClient } from 'postsync';
import postmanCollection from './collection.json';

const api = createApiClient(postmanCollection, {
  baseUrl: 'https://api.example.com'
});

// GET request with path parameters
const user = await api.users.get.getUserById({
  pathParams: { id: '123' }
});

// POST request with JSON body
const newPost = await api.posts.post.createPost({
  body: {
    title: 'New Post',
    content: 'Post content'
  }
});

// GET request with query parameters
const filteredProducts = await api.products.get.searchProducts({
  queryParams: {
    category: 'electronics',
    sort: 'price'
  }
});

Intuitive API Structure

PostSync organizes your endpoints logically by resource, HTTP method, and operation name:

api.resourceGroup.httpMethod.endpointName(options)

Available Request Options:

pathParams: URL path parameters
queryParams: URL query string parameters
body: Request body (auto-serialized)
headers: Request-specific headers

Response Handling

try {
  const response = await api.users.get.getUserById({
    pathParams: { id: '123' }
  });

  // Access the response data
  if (response.ok) {
    console.log(response.data); // Typed response data
    console.log(response.status); // HTTP status code
    console.log(response.headers); // Response headers
  }
} catch (error) {
  console.error('Error:', error.message);
  console.error('Status:', error.status);
  console.error('Data:', error.data);
}

Custom Configuration

const api = createApiClient(postmanCollection, {
  // Base URL for all requests
  baseUrl: 'https://api.example.com',
  
  // Default headers sent with every request
  headers: {
    'Authorization': 'Bearer token123',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  
  // Request timeout in milliseconds
  timeoutMs: 10000,
  
  // Retry configuration (optional)
  retryConfig: {
    maxRetries: 3,
    retryDelay: 1000,
    retryableStatusCodes: [408, 429, 500, 502, 503, 504]
  }
});

Advanced Features

TypeScript Integration

Get full IntelliSense support and type checking for all your API calls and responses.

SSR Compatibility

Use PostSync in server environments like Next.js with our SSR-friendly implementation.

Request Interceptors

Add custom logic to modify requests before they're sent or process responses.