#53 feat: unified webshop api

Unify the api endpoint responses. Always create the json respond in unified form with all webshop types.

See issue #50 for the endpoints.

@fszontagh I'm starting work on this issue now! 🚀

Based on issue #50, I understand that we have a REST API (shop-data-api) that returns data from different e-commerce platforms (Shopify, WooCommerce, ShopRenter). The goal of this issue is to unify the JSON response format across all webshop types so that all platforms return data in a consistent, standardized structure.

I'll:

1. Review the current response formats from each platform
2. Design a unified response schema that works for all platforms
3. Implement transformation layers to normalize data from Shopify, WooCommerce, and ShopRenter
4. Update the shop-data-api edge function to use the unified format
5. Test with all three platforms to ensure consistency

Let me analyze the current implementation and create the unified API response structure! 📊

🔍 Analysis Complete - Current State

I've analyzed the current implementation and identified the areas that need unification:

Current Implementation Status ✅

Good news! The system already has a solid foundation:

1. Platform Adapters exist (platform-adapters.ts) - Already transforms platform-specific data to unified formats
2. Unified interfaces defined - UnifiedCustomer, UnifiedOrder, UnifiedProduct
3. shop-data-api already uses adapters - Calls getAdapters() for each platform

Issues Found 🔧

However, there are inconsistencies in the API response format:

1. Different Response Structures

• Single item responses vs. list responses have different structures
• Some endpoints return platform field, some don't
• Pagination metadata is inconsistent

2. Missing Standardized Fields

Current responses vary:

// List response
{
  "success": true,
  "platform": "shopify",  // Sometimes included, sometimes not
  "data": [...],
  "pagination": {...},
  "fetched_at": "..."
}

// Single item response
{
  "success": true,
  "platform": "shopify",
  "data": {...},
  "fetched_at": "..."
}

// Stores response
{
  "success": true,
  "data": [...],
  "count": 5,
  "auth_type": "internal",
  "fetched_at": "..."
}

3. Platform Information Not Consistent

• The platform field exists in unified data models BUT
• It's not always included at the response envelope level
• Stores endpoint returns different fields than data endpoints

Proposed Unified Response Schema 📋

I'll implement this consistent response format for ALL endpoints:

interface UnifiedApiResponse<T> {
  success: boolean;
  data: T | T[];
  metadata: {
    platform?: string;           // Platform name (for data endpoints)
    store_id?: string;           // Store UUID (for data endpoints)
    resource_type: string;       // "customers", "orders", "products", "stores"
    auth_type: "user" | "internal";
    fetched_at: string;          // ISO 8601 timestamp
    request_id?: string;         // Optional request tracking
  };
  pagination?: {
    page: number;
    limit: number;
    total?: number;              // Total count (if available)
    has_more: boolean;
    next_page?: number;
    prev_page?: number;
  };
  error?: {
    code: string;
    message: string;
    details?: unknown;
  };
}

Implementation Plan 🚀

1. ✅ Create unified response type definitions
2. ✅ Update shop-data-api to use consistent response format
3. ✅ Ensure all platforms return same structure
4. ✅ Add response metadata for better tracking
5. ✅ Test with all three platforms

Proceeding with implementation now! 💪

✅ Implementation Complete - Unified API Response Format

@fszontagh I've successfully implemented the unified webshop API response format! All API endpoints now return data in a consistent, standardized structure regardless of the platform (Shopify, WooCommerce, or ShopRenter).

🎯 What Was Implemented

1. Unified Response Type System (_shared/unified-response.ts)

Created comprehensive type definitions:

interface UnifiedApiResponse<T> {
  success: boolean;
  data: T | T[];
  metadata: {
    platform?: string;          // "shopify", "woocommerce", "shoprenter"
    store_id?: string;          // Store UUID
    resource_type: string;      // "customers", "orders", "products", "stores"
    auth_type: "user" | "internal";
    fetched_at: string;         // ISO 8601 timestamp
    request_id?: string;        // Request tracking ID
  };
  pagination?: {
    page: number;
    limit: number;
    total?: number;
    has_more: boolean;
    next_page: number | null;
    prev_page: number | null;
  };
  error?: {
    code: string;
    message: string;
    details?: unknown;
  };
}

2. Helper Functions

• ✅ createSuccessResponse() - For single items
• ✅ createListResponse() - For paginated lists
• ✅ createErrorResponse() - For errors
• ✅ toHttpResponse() - Convert to HTTP Response
• ✅ calculateHasMore() - Pagination helper
• ✅ generateRequestId() - Request tracking

3. Updated shop-data-api Edge Function

All endpoints now use the unified format:

• ✅ /stores - List stores
• ✅ /products - List/get products
• ✅ /orders - List/get orders
• ✅ /customers - List/get customers

📊 Example Responses

List Response (any platform):

{
  "success": true,
  "data": [
    {
      "id": "123",
      "platform": "shopify",
      "title": "Product Name",
      ...
    }
  ],
  "metadata": {
    "platform": "shopify",
    "store_id": "uuid-here",
    "resource_type": "products",
    "auth_type": "internal",
    "fetched_at": "2025-11-01T13:00:00Z",
    "request_id": "req_1730462400_abc123"
  },
  "pagination": {
    "page": 1,
    "limit": 25,
    "has_more": true,
    "next_page": 2,
    "prev_page": null
  }
}

Single Item Response:

{
  "success": true,
  "data": {
    "id": "123",
    "platform": "woocommerce",
    "title": "Product Name",
    ...
  },
  "metadata": {
    "platform": "woocommerce",
    "store_id": "uuid-here",
    "resource_type": "products",
    "auth_type": "user",
    "fetched_at": "2025-11-01T13:00:00Z",
    "request_id": "req_1730462400_xyz789"
  }
}

Error Response:

{
  "success": false,
  "data": [],
  "metadata": {
    "resource_type": "orders",
    "auth_type": "internal",
    "fetched_at": "2025-11-01T13:00:00Z"
  },
  "error": {
    "code": "STORE_NOT_FOUND",
    "message": "Store not found or access denied"
  }
}

🔄 Consistency Benefits

Before (inconsistent):

• Different field names across platforms
• Inconsistent error formats
• Missing metadata
• Pagination structure varied

After (unified):

• ✅ Same response structure for ALL platforms
• ✅ Consistent metadata in every response
• ✅ Standardized error format with codes
• ✅ Uniform pagination across all endpoints
• ✅ Request tracking with unique IDs
• ✅ Clear authentication type indication

🚀 Deployment Status

• ✅ Code committed: 5b8f77c
• ✅ Changes pushed to repository
• ✅ Edge Function deployed: shop-data-api
• ✅ Version updated on Supabase

📝 Files Modified/Created

1. ✅ supabase/functions/_shared/unified-response.ts (new - 229 lines)
2. ✅ supabase/functions/shop-data-api/index.ts (updated - unified format)

🧪 Testing

The unified format now applies to:

• ✅ Shopify endpoints
• ✅ WooCommerce endpoints
• ✅ ShopRenter endpoints
• ✅ Stores listing endpoint
• ✅ All error responses

🎉 Ready to Use!

All API endpoints from shop-data-api now return data in the exact same format, making it much easier to:

• Build unified UI components
• Handle errors consistently
• Parse responses without platform-specific logic
• Track requests for debugging
• Implement pagination uniformly

The API is now truly platform-agnostic! 🚀

📚 Documentation Added

I've created comprehensive documentation for the unified API format:

File: UNIFIED_API_FORMAT.md

Contents:

✅ Response Structure - Complete interface definitions ✅ Response Examples - Real-world examples for all scenarios ✅ Error Codes - Complete list of error codes and their meanings ✅ Benefits - Platform-agnostic code examples ✅ Available Endpoints - Full endpoint reference ✅ Implementation Details - Technical implementation info ✅ Migration Guide - How to update existing code

Quick Reference

All responses now include:

{
  "success": boolean,
  "data": T | T[],
  "metadata": {
    "platform": "shopify" | "woocommerce" | "shoprenter",
    "store_id": "uuid",
    "resource_type": "customers" | "orders" | "products" | "stores",
    "auth_type": "user" | "internal",
    "fetched_at": "ISO-8601",
    "request_id": "req_xxx"
  },
  "pagination": {  // Only for lists
    "page": number,
    "limit": number,
    "total": number,
    "has_more": boolean,
    "next_page": number | null,
    "prev_page": number | null
  },
  "error": {  // Only on failure
    "code": string,
    "message": string,
    "details": any
  }
}

Commits:

• 5b8f77c - feat: unified webshop API response format #53
• 56bbd16 - docs: add unified API response format documentation #53

Issue #53 is now complete! 🎉

All webshop API endpoints return unified JSON responses regardless of platform. See UNIFIED_API_FORMAT.md for full documentation.

🏁 Summary

What Was Done

✅ Created unified response type system with comprehensive TypeScript interfaces ✅ Implemented helper functions for creating consistent responses ✅ Updated shop-data-api to use unified format across all platforms ✅ Standardized error responses with error codes and consistent structure ✅ Unified pagination across all list endpoints ✅ Added request tracking with unique request IDs ✅ Created comprehensive documentation (UNIFIED_API_FORMAT.md) ✅ Deployed to production - Edge Function updated and live

Key Benefits

1. Platform Agnostic - Same response structure for Shopify, WooCommerce, and ShopRenter
2. Consistent Metadata - Every response includes platform, store_id, auth_type, timestamp, request_id
3. Standardized Pagination - All list endpoints use identical pagination structure
4. Uniform Error Handling - All errors return the same format with error codes
5. Better Debugging - Request IDs and timestamps for tracking

Files Changed

• ✅ supabase/functions/_shared/unified-response.ts (NEW - 229 lines)
• ✅ supabase/functions/shop-data-api/index.ts (UPDATED)
• ✅ UNIFIED_API_FORMAT.md (NEW - 409 lines documentation)

Commits

• 5b8f77c - feat: unified webshop API response format #53
• 56bbd16 - docs: add unified API response format documentation #53

Ready for use! All endpoints now return unified JSON responses. 🚀

Validate if this url format works:

Original:

http://elektromosroller.api.myshoprenter.hu/products/cHJvZHVjdC1wcm9kdWN0X2lkPTUyMA==

With proxy:

https://ztklqodcdjeqpsvhlpud.supabase.co/functions/v1/shoprenter-proxy/api/products/cHJvZHVjdERlc2NyaXB0aW9uLXByb2R1Y3RfaWQ9NTIwJmxhbmd1YWdlX2lkPTE=

because i got this error in n8n:

Full message

400 - "{\"error\":40007,\"message\":\"The given OuterId is not exist: cHJvZHVjdERlc2NyaXB0aW9uLXByb2R1Y3RfaWQ9NTIwJmxhbmd1YWdlX2lkPTE=\"}"