BuddyShopping Backend

This is the home of the WebSocket server behind BuddyShopping Ecwid app.

Build Instructions

• Build in release mode: nimble install or docker build -t buddyshopping-backend .

• Build in development mode: nimble build

• Run the app on port 8080: ./buddyshopping

• Run tests:

  • Build and run the app.

  • Run the test suite in a separate tab: nimble test

• Generate and upload API docs: nimble docs

Messages

The client and the server communicate by exchanging messages in serialized JSON over WebSocket. The supported message types are listed below.

startSession

To start a shared shopping session, the client on the host's storefront establishes connection with the server at wss://buddyshopping.now.sh/:sessionId, where :sessionId is a unique random string. Session ID is generated by the host's client and shared with the host's friends.

The initial message that starts the session:

{
  "event": "startSession",
  "payload": {
    "customerName": "Michael"
  }
}

customerName is entered by the customer. It's a regular human-readable name. like “John,” or “Alice.” It doesn't have to be unique.

In exchange for the data above, the server generates a unique customer ID and sends it to the client:

{
  "event": "startSession",
  "payload": {
    "customerId": "1234567qwe0000001"
  }
}

The client should use the received customerId in future messages to identify the customer.

joinSession

To join a running shared shopping session, the client on the guest's storefront establishes connection to the same session as the session's host; the session ID is extracted from the invitation URL generated for and sent by the host.

The message to join a session:

{
  "event": "joinSession",
  "payload": {
    "customerName": "Constantine"
  }
}

In exchange, the server generates a unique customer ID and sends it to the client:

{
  "event": "joinSession",
  "payload": {
    "customerId": "1234567asd0000002"
  }
}

updateCart

Whenever a customer updates the cart state on their storefront, e.g. adds items, removes items, changes the properties or quantities of the items, the client sends a message to inform the server about the change:

{
  "event": "updateCart",
  "payload": {
    "customerId": "1234567asd0000002",
    "cartContent": {
      "items": [{...}, {...}, ...],
      "productsQuantity": 3,
      "orderId": 123,
      "couponName": null,
      "weight": 1.23,
      "paymentMethod": null,
      "shippingMethod": null,
      "cartId": "456asd"
    }
  }
}

The object at cartContent key is an Ecwid's Cart Object. It is the new state of the shopping cart.

customerId is the unique ID the client received after starting or joining the session.

customerReadyToCheckout

When a customer is ready to checkout, their client sends the following message:

{
  "event": "customerReadyToCheckout",
  "payload": {
    "customerId": "1234567asd0000002",
    "customerReadyToCheckout": true
  }
}

If the customer cancels their ready state, the same message but with false is sent:

{
  "event": "customerReadyToCheckout",
  "payload": {
    "customerId": "1234567asd0000002",
    "customerReadyToCheckout": false
  }
}

The client must not allow the host to toggle ready to checkout state untill all guests have set theirs to true.

multicartUpdate

After any of the messages above is processed by the server, the server broadcasts the new state of the so called multicart to all clients connected to the session:

{
  "event": "multicartUpdate",
  "payload": {
    "multicartContent": [
      {
        "owner": {
          "id": "1234567qwe0000001",
          "name": "Michael",
          "isHost": true,
          "isReadyToCheckout": false
          },
        "content": {...}
      },
      {
        "owner": {
          "id": "1234567asd0000002",
          "name": "Constantine",
          "isHost": false,
          "isReadyToCheckout": true
          },
        "content": {...}
      },
    ]
  }
}

Multicart is an object that holds the state of all carts participating in the session.

content key points to a Cart Object from Ecwid's API.