Skip to main content

JavaScript/TypeScript SDK

The official NowPost JavaScript/TypeScript SDK provides a convenient way to interact with the NowPost API from your Node.js or browser applications.

Installation​

Install the SDK using your preferred package manager:

npm install @nowpost/nowpost-ts
pnpm add @nowpost/nowpost-ts
yarn add @nowpost/nowpost-ts

Requirements​

  • Node.js 16 or higher
  • TypeScript 5.0+ (for TypeScript projects)

Quick Start​

Basic Setup​

import { NowPost, Configuration } from '@nowpost/nowpost-ts';

// Initialize the configuration
const configuration = new Configuration({
  basePath: 'https://api.nowpost.com',
});

// Create the NowPost client
const nowpost = new NowPost(configuration);

With API Authentication (for protected endpoints)​

import { NowPost, Configuration } from '@nowpost/nowpost-ts';

const configuration = new Configuration({
  basePath: 'https://api.nowpost.com',
  apiKey: 'your-api-key-here', // Your NowPost API key
});

const nowpost = new NowPost(configuration);

Available APIs​

Currently, the SDK provides access to the following APIs:

PUDO Points API​

The PUDO Points API allows you to retrieve information about pickup and drop-off points.

Get Published PUDO Points​

// Basic usage - get all published PUDO points
const response = await nowpost.pudoPoints.publicPudoPointsGet();
const pudoPoints = response.data.data?.data || [];

console.log(`Found ${pudoPoints.length} PUDO points`);

With Pagination​

// Get PUDO points with pagination
const response = await nowpost.pudoPoints.publicPudoPointsGet(
  1,    // page number
  20    // page size
);

const { data: pudoPoints, pagination } = response.data.data;
console.log(`Page ${pagination.page} of ${pagination.totalPages}`);
console.log(`Total PUDO points: ${pagination.totalCount}`);

Search and Filter​

// Search for PUDO points
const response = await nowpost.pudoPoints.publicPudoPointsGet(
  1,              // page
  10,             // pageSize
  'pharmacy',     // search term
  'name',         // sortBy
  'asc'           // sortOrder
);
// Find PUDO points near a specific location
const response = await nowpost.pudoPoints.publicPudoPointsGet(
  1,              // page
  20,             // pageSize
  undefined,      // search
  undefined,      // sortBy
  undefined,      // sortOrder
  6.5244,         // latitude (Lagos, Nigeria)
  3.3792          // longitude
);

Real-world Example​

Here's a complete example based on the maps application usage:

import { Configuration, NowPost } from "@nowpost/nowpost-ts";

// Types for your application
export type PickupPoint = {
  id: string;
  name: string;
  description: string;
  latitude: number;
  longitude: number;
  address: {
    address: string;
    city: string;
    state: string;
    country: string;
  };
  partner: {
    name: string;
    type: string;
  };
  workingHours: {
    openingMonday?: string;
    closingMonday?: string;
    // ... other days
  };
};

// Initialize the SDK
const configuration = new Configuration({
  basePath: "https://api.nowpost.com",
});

const nowpost = new NowPost(configuration);

// Function to get and transform PUDO points
export async function getPudoPoints(): Promise<PickupPoint[]> {
  try {
    const response = await nowpost.pudoPoints.publicPudoPointsGet();
    const data = response.data.data?.data || [];

    // Transform the API response to match your application's data structure
    return data.map((point) => ({
      ...point,
      latitude: Number(point?.address?.latitude),
      longitude: Number(point?.address?.longitude),
    }));
  } catch (error) {
    console.error('Error fetching PUDO points:', error);
    throw error;
  }
}

// Usage in your application
async function displayPudoPoints() {
  try {
    const points = await getPudoPoints();
    
    points.forEach(point => {
      console.log(`${point.name} - ${point.address.city}`);
      console.log(`Location: ${point.latitude}, ${point.longitude}`);
      console.log(`Operated by: ${point.partner.name}`);
    });
  } catch (error) {
    console.error('Failed to load PUDO points:', error);
  }
}

Configuration Options​

The Configuration class supports various options:

const configuration = new Configuration({
  // Base URL for the API (required)
  basePath: 'https://api.nowpost.com',
  
  // API key for authenticated endpoints
  apiKey: 'your-api-key-here',
  
  // Additional headers to send with requests
  headers: {
    'User-Agent': 'MyApp/1.0.0',
    'X-Custom-Header': 'value'
  },
  
  // Custom axios configuration
  baseOptions: {
    timeout: 10000, // 10 seconds timeout
  }
});

Environment Configuration​

Development​

const configuration = new Configuration({
  basePath: 'https://api.nowpost.com',
});

Production​

const configuration = new Configuration({
  basePath: 'https://api.nowpost.com',
});

Environment Variables​

For better security and configuration management, use environment variables:

const configuration = new Configuration({
  basePath: process.env.NOWPOST_API_BASE_URL || 'https://api.nowpost.com',
  apiKey: process.env.NOWPOST_API_KEY,
});

Error Handling​

The SDK throws errors for various scenarios. Always wrap your API calls in try-catch blocks:

import { AxiosError } from 'axios';

async function fetchPudoPointsSafely() {
  try {
    const response = await nowpost.pudoPoints.publicPudoPointsGet();
    return response.data.data?.data || [];
  } catch (error) {
    if (error instanceof AxiosError) {
      // Handle HTTP errors
      console.error('API Error:', error.response?.status, error.response?.data);
      
      if (error.response?.status === 404) {
        console.log('No PUDO points found');
        return [];
      } else if (error.response?.status >= 500) {
        console.log('Server error, please try again later');
        throw new Error('Service temporarily unavailable');
      }
    } else {
      // Handle network or other errors
      console.error('Network error:', error);
      throw new Error('Failed to connect to NowPost API');
    }
    
    return [];
  }
}

TypeScript Support​

The SDK is built with TypeScript and provides full type definitions:

import type { 
  PudoPointResponse, 
  PudoPointListResponse,
  PaginationDTO 
} from '@nowpost/nowpost-ts';

// All API responses are fully typed
const response: { data: PudoPointListResponse } = 
  await nowpost.pudoPoints.publicPudoPointsGet();

// Individual PUDO point is typed
const pudoPoint: PudoPointResponse = response.data.data.data[0];

// Pagination info is typed
const pagination: PaginationDTO = response.data.data.pagination;

Browser Support​

The SDK works in both Node.js and modern browsers. For browser usage, ensure you handle CORS appropriately:

<script type="module">
import { NowPost, Configuration } from 'https://unpkg.com/@nowpost/nowpost-ts@latest/dist/index.mjs';

const nowpost = new NowPost(new Configuration({
  basePath: 'https://api.nowpost.com'
}));

// Use the SDK in your browser application
const points = await nowpost.pudoPoints.publicPudoPointsGet();
console.log(points.data);
</script>

Next Steps​

Support​