Gophr Bridge SDK

A simple, lightweight SDK for interacting with the Gophr Bridge API. This SDK provides easy-to-use methods for getting delivery quotes and creating shipments.

Installation

Install the package from npm:

npm install gophr-bridge-sdk

Getting Started Quickly

# 1. Install the SDK
npm install gophr-bridge-sdk

# 2. Create a basic example file
cat > gophr-test.js << 'EOF'
const GophrBridge = require('gophr-bridge-sdk');

const gophr = new GophrBridge({
    clientId: 'your_client_id',
    clientSecret: 'your_client_secret'
    // testing: true is the default (development API)
});

async function test() {
    try {
        const quote = await gophr.getQuote({
            first_name: 'John', last_name: 'Doe',
            phone: '5555555555', email: '[email protected]',
            address_1: '1000 Ryan St', city: 'Lake Charles',
            state: 'LA', zip: '70602', country: 'US',
            items: [{ quantity: 1, name: 'Test Item', weight: 1 }]
        });
        console.log('Standard fee:', gophr.getStandardQuoteFee(quote));
    } catch (error) {
        console.error('Error:', error.message);
    }
}

test();
EOF

# 3. Add your credentials and run
node gophr-test.js

Quick Start

1. Environment Setup

Create a .env file in your project root with your Gophr Bridge API credentials:

GOPHR_CLIENT_ID=your_client_id_here
GOPHR_CLIENT_SECRET=your_client_secret_here
GOPHR_TESTING=true

2. Basic Usage

const GophrBridge = require('gophr-bridge-sdk');
require('dotenv').config();

// Initialize the SDK
const gophr = new GophrBridge({
    clientId: process.env.GOPHR_CLIENT_ID,
    clientSecret: process.env.GOPHR_CLIENT_SECRET,
    testing: process.env.GOPHR_TESTING === 'true'
});

// Get a quote
async function getQuote() {
    try {
        const quote = await gophr.getQuote({
            first_name: 'John',
            last_name: 'Doe',
            phone: '5555555555',
            email: '[email protected]',
            address_1: '1000 Ryan St',
            address_2: '',
            city: 'Lake Charles',
            state: 'LA',
            zip: '70602',
            country: 'US',
            pick_up_instructions: 'Ring the doorbell',
            drop_off_instructions: 'Leave at front door',
            scheduled_for: null, // ASAP delivery
            items: [{
                quantity: 1,
                name: 'Document Package',
                sku: 'DOC-001',
                weight: 2
            }]
        });
        
        console.log('Quote received:', quote);
        
        // Use getter methods to extract specific values
        const standardQuoteId = gophr.getStandardQuoteId(quote);
        const standardFee = gophr.getStandardQuoteFee(quote);
        const expeditedFee = gophr.getExpeditedQuoteFee(quote);
        
        console.log(`Standard quote: $${standardFee} (ID: ${standardQuoteId})`);
        console.log(`Expedited quote: $${expeditedFee}`);
        
        return quote;
    } catch (error) {
        GophrBridge.logError(error);
    }
}

// Create a shipment
async function createShipment(quoteId) {
    try {
        const shipment = await gophr.createShipment({
            quote_id: quoteId,
            drop_off_instructions: 'Updated delivery instructions'
        });
        
        console.log('Shipment created:', shipment);
        
        // Use getter methods to extract specific values
        const deliveryId = gophr.getDeliveryId(shipment);
        const status = gophr.getDeliveryStatus(shipment);
        const fee = gophr.getShippingFee(shipment);
        const vehicleType = gophr.getVehicleType(shipment);
        
        console.log(`Shipment ${deliveryId} created with status: ${status}`);
        console.log(`Vehicle: ${vehicleType}, Fee: $${fee}`);
        
        return shipment;
    } catch (error) {
        GophrBridge.logError(error);
    }
}
}

API Reference

Constructor

new GophrBridge(config)

Parameters:

• config.clientId (string, required) - Your Gophr client ID
• config.clientSecret (string, required) - Your Gophr client secret
• config.testing (boolean, optional) - Use development API when true, production when false (default: true)

API Endpoints:

• Development: https://dev-api-bridge.gophr.app (default)
• Production: https://api-bridge.gophr.app

Methods

getQuote(quoteData)

Get a delivery quote.

Parameters:

• quoteData (object) - Quote request data
  • first_name (string, required) - Customer first name
  • last_name (string, required) - Customer last name
  • phone (string, required) - Customer phone number
  • email (string, optional) - Customer email
  • address_1 (string, required) - Delivery address line 1
  • address_2 (string, optional) - Delivery address line 2
  • city (string, required) - Delivery city
  • state (string, required) - Delivery state
  • zip (string, required) - Delivery ZIP code
  • country (string, optional, default: 'US') - Delivery country
  • pick_up_instructions (string, optional) - Pickup instructions
  • drop_off_instructions (string, optional) - Drop-off instructions
  • scheduled_for (string|null, optional) - Scheduled delivery date (YYYY-MM-DD format)
  • items (array, required) - Array of items to be delivered

Returns: Promise resolving to quote response object

createShipment(shipmentData)

Create a shipment from a quote.

Parameters:

• shipmentData (object) - Shipment creation data
  • quote_id (string, required) - Quote ID from previous quote request
  • drop_off_instructions (string, optional) - Drop-off instructions

Returns: Promise resolving to shipment response object

buildQuoteData(customerInfo, addressInfo, items, options)

Helper method to build quote data with a more structured approach.

Parameters:

• customerInfo (object) - Customer information
  • firstName (string)
  • lastName (string)
  • phone (string)
  • email (string, optional)
• addressInfo (object) - Address information
  • address1 (string)
  • address2 (string, optional)
  • city (string)
  • state (string)
  • zip (string)
  • country (string, optional)
• items (array) - Items array
• options (object, optional) - Additional options
  • pickupInstructions (string)
  • dropoffInstructions (string)
  • scheduledFor (string|null)

Static Methods

GophrBridge.logError(error)

Utility method to log API errors in a formatted way.

Getter Methods

The SDK provides convenient instance methods to extract specific values from API responses:

Quote Response Getters

• gophr.getStandardQuoteId(quoteResponse) - Extract standard quote ID
• gophr.getExpeditedQuoteId(quoteResponse) - Extract expedited quote ID
• gophr.getStandardQuoteFee(quoteResponse) - Extract standard quote fee
• gophr.getExpeditedQuoteFee(quoteResponse) - Extract expedited quote fee
• gophr.getQuoteSummary(quoteResponse) - Get formatted quote summary

Shipment Response Getters

• gophr.getDeliveryId(shipmentResponse) - Extract delivery ID
• gophr.getDeliveryStatus(shipmentResponse) - Extract delivery status
• gophr.getShippingFee(shipmentResponse) - Extract shipping fee
• gophr.getVehicleType(shipmentResponse) - Extract vehicle type
• gophr.getDistance(shipmentResponse) - Extract distance in miles
• gophr.getShipmentWeight(shipmentResponse) - Extract shipment weight
• gophr.getShipmentItems(shipmentResponse) - Extract items array
• gophr.getPickupAddress(shipmentResponse) - Extract pickup address object
• gophr.getDropoffAddress(shipmentResponse) - Extract drop-off address object
• gophr.getScheduledFor(shipmentResponse) - Extract scheduled delivery date
• gophr.isExpedited(shipmentResponse) - Check if shipment is expedited
• gophr.getShipmentSummary(shipmentResponse) - Get formatted shipment summary

Payload Getters

• gophr.getQuotePayload(quoteResponse) - Extract full quote payload
• gophr.getShipmentPayload(shipmentResponse) - Extract full shipment payload

Utility Getters

• gophr.isSuccessful(response) - Check if API response was successful

Advanced Usage

Using the Helper Method

const customerInfo = {
    firstName: 'Jane',
    lastName: 'Smith', 
    phone: '5555551234',
    email: '[email protected]'
};

const addressInfo = {
    address1: '123 Main St',
    address2: 'Apt 4B',
    city: 'New York',
    state: 'NY', 
    zip: '10001'
};

const items = [{
    quantity: 2,
    name: 'Books',
    sku: 'BOOK-001',
    weight: 5
}];

const options = {
    pickupInstructions: 'Call when arriving',
    dropoffInstructions: 'Ring apartment buzzer',
    scheduledFor: '2025-09-25'
};

const quoteData = gophr.buildQuoteData(customerInfo, addressInfo, items, options);
const quote = await gophr.getQuote(quoteData);

// Extract specific values using getter methods
const standardQuoteId = gophr.getStandardQuoteId(quote);
const standardFee = gophr.getStandardQuoteFee(quote);
console.log(`Standard quote: $${standardFee} (ID: ${standardQuoteId})`);

Using Getter Methods

Extract specific values easily from API responses:

// Get a quote
const quote = await gophr.getQuote(quoteData);

// Extract specific values using getters
const standardQuoteId = gophr.getStandardQuoteId(quote);
const standardFee = gophr.getStandardQuoteFee(quote);
const expeditedFee = gophr.getExpeditedQuoteFee(quote);

console.log(`Standard quote: $${standardFee} (ID: ${standardQuoteId})`);
console.log(`Expedited quote: $${expeditedFee}`);

// Or get a formatted summary
const summary = gophr.getQuoteSummary(quote);
console.log('Quote Summary:', summary);

// Create shipment using extracted quote ID
const shipment = await gophr.createShipment({
    quote_id: standardQuoteId,
    drop_off_instructions: 'Updated instructions'
});

// Extract shipment information
const deliveryId = gophr.getDeliveryId(shipment);
const status = gophr.getDeliveryStatus(shipment);
const fee = gophr.getShippingFee(shipment);

console.log(`Shipment ${deliveryId} created with status: ${status}, fee: $${fee}`);

// Access detailed shipment information
const pickupAddress = gophr.getPickupAddress(shipment);
const dropoffAddress = gophr.getDropoffAddress(shipment);
const items = gophr.getShipmentItems(shipment);
const weight = gophr.getShipmentWeight(shipment);
const isExpedited = gophr.isExpedited(shipment);

console.log('Pickup:', pickupAddress);
console.log('Drop-off:', dropoffAddress);
console.log('Items:', items);
console.log(`Weight: ${weight}lbs, Expedited: ${isExpedited}`);

// Or get the full payload for complete access
const fullPayload = gophr.getShipmentPayload(shipment);
console.log('Full shipment payload:', fullPayload);

Error Handling

The SDK provides enhanced error handling with detailed error information:

try {
    const quote = await gophr.getQuote(quoteData);
} catch (error) {
    // Use the built-in error logger
    GophrBridge.logError(error);
    
    // Or handle manually
    if (error.status === 400) {
        console.log('Bad request:', error.details);
    } else if (error.isNetworkError) {
        console.log('Network issue:', error.message);
    }
}

Examples

Running the Example

After installing the package, you can run the complete example:

# Copy the example to your project
cp node_modules/gophr-bridge-sdk/examples/index.js gophr-example.js
cp node_modules/gophr-bridge-sdk/examples/example.env .env

# Edit .env with your actual credentials
# Then run the example
node gophr-example.js

Example File

The package includes a comprehensive example file:

• examples/index.js - Complete SDK demonstration including quotes, shipments, and all getter methods

This single example demonstrates:

• Getting delivery quotes
• Creating shipments
• Using all getter methods for data extraction
• Accessing address information and coordinates
• Using helper methods for structured data
• Error handling best practices
• Advanced usage patterns

Requirements

• Node.js 22.0.0 or higher
• Valid Gophr Bridge API credentials

Dependencies

• axios - HTTP client for API requests
• dotenv - Environment variable management

License

MIT