Snippost - Snipcart InPost Integration

A comprehensive shipping integration solution that seamlessly connects Snipcart e-commerce platform with InPost shipping services, providing automated shipment creation and interactive parcel locker selection through an intelligent geo-widget.

🚀 Features

• Seamless Snipcart Integration: Drop-in JavaScript widget that integrates with any Snipcart-powered e-commerce site
• InPost Shipping Automation: Automatic shipment creation through InPost API
• Interactive Geo-Widget: Real-time parcel locker selection with geolocation support
• Member Management: Integration with Memberstack for user authentication and configuration
• Multi-language Support: Supports Polish and English interfaces
• Real-time Address Updates: Automatically updates shipping addresses based on selected parcel lockers
• Serverless Architecture: Deployed on Vercel for optimal performance and scalability

🛠️ Tech Stack

Frontend

• Vite - Build tool and development server
• Vanilla JavaScript - Lightweight client-side implementation
• InPost GeoWidget - Interactive map for parcel locker selection

Backend

• Node.js with Express.js - RESTful API server
• Axios - HTTP client for external API calls
• CORS - Cross-origin resource sharing support
• dotenv - Environment variable management

Deployment & Infrastructure

• Vercel - Serverless deployment platform
• Memberstack - User management and authentication
• InPost API - Shipping service integration

Development Tools

• Chokidar - File watching for development
• fs-extra - Enhanced file system operations
• Concurrently - Run multiple commands simultaneously

🚀 Quick Start

Prerequisites

• Node.js 16+
• NPM or Yarn package manager
• Memberstack account with configured custom fields
• InPost API credentials
• Snipcart account

Installation

1. Clone the repository

   git clone <repository-url>
   cd snippost-project

2. Install dependencies

   npm install

3. Environment Setup Create a .env file in the root directory:

   MEMBERSTACK_API_KEY=your_memberstack_api_key
   DEBUG=true

4. Development Server

   npm run dev

   This starts both the Vite development server and the Express API server concurrently.

Build for Production

npm run build

The build process creates optimized bundles for both the widget and geo-widget components.

📖 Usage

Basic Integration

Add the Snippost widget to your Snipcart-powered website:

<script src="https://snippost.vercel.app/snippost-widget.js"></script>
<script>
  // Initialize with your member ID
  snippost.initialize('your-member-id', true); // true enables debug mode
</script>

Memberstack Configuration

Configure the following custom fields in your Memberstack setup:

Field Name	Description	Required
domain-1-webflow	Primary domain configuration	✅
first-name	User's first name	✅
organization-id	InPost organization ID	✅
geo-token	InPost geo-widget token	✅
inpost-apikey	InPost production API key	✅
inpostapi-sandbox-key	InPost sandbox API key	✅
kurier	Courier shipping rate	✅
paczkomat	Parcel locker shipping rate	✅
kurier-darmowy	Free courier threshold	⚪
paczkomat-darmowy	Free parcel locker threshold	⚪

🔧 API Endpoints

GET /api/get-member/:memberId

Retrieves member configuration from Memberstack.

Response:

{
  "organizationId": "string",
  "domain": "string", 
  "geoToken": "string"
}

POST /api/create-shipment

Creates a new shipment through InPost API.

Request Body:

{
  "order": { /* InPost shipment object */ },
  "shipx_id": "organization_id",
  "shipx_url": "api_base_url"
}

🎯 How It Works

1. Initialization: The widget fetches member configuration from Memberstack
2. Configuration: Sets up InPost credentials and shipping parameters
3. Integration: Loads the geo-widget when InPost shipping is selected
4. Selection: User selects a parcel locker from the interactive map
5. Update: Shipping address is automatically updated in Snipcart
6. Shipment: Order completion triggers automatic shipment creation via InPost API

🌍 Deployment

The project is configured for seamless deployment on Vercel:

vercel

The vercel.json configuration handles:

• Serverless function routing for API endpoints
• Static asset serving
• Build process optimization

🛠️ Development

File Watching

Run the file combiner in watch mode for development:

npm run watch

This utility monitors key files and combines them into main_project.txt for easy reference.

Debug Mode

Enable detailed logging by setting debug: true when initializing the widget or setting DEBUG=true in your environment variables.

🔐 Security Considerations

• API keys are stored securely in Memberstack custom fields
• CORS is properly configured for cross-origin requests
• Environment variables protect sensitive configuration
• Input validation prevents malformed requests

📄 License

This project is available under the MIT License.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📞 Support

For technical support or questions:

• Check the debugging logs in browser console
• Verify Memberstack custom field configuration
• Ensure InPost API credentials are valid
• Contact the development team for advanced troubleshooting

---

Built with ❤️ for seamless e-commerce shipping experiences