1.3.2 • Published 3 years ago

@vinka/viper-api v1.3.2

Weekly downloads
-
License
UNLICENSED
Repository
bitbucket
Last release
3 years ago

Vinka Driver App API

WebSocket Events

Login

Not a real login in the sense that there is no authentication but this message is used for sending the vehicle number to the server. This event needs to be resent every time the socket connection drops and re-establises. So, clients should do something like this in their Socket.io initialization code:

socket.on('connect', async () => {
    try {
        await login();
    } catch (e) {
        // login failed
    }
});

async login() {
    return new Promise((res, rej) => {
        socket.on('loginOk', res);
        socket.emit('login', {vehicleNumber: 1});
    });
}
  • key: login
  • direction: client -> server
  • payload:
export interface Login {
    vehicleNumber: number,
}

Upon successful login, the server will send following message:

  • key: loginOk
  • direction: server -> client
  • payload: no payload

Error:

  • key: loginError
  • direction: server -> client

Get Itinerary

Client may use this request to get the current itinerary from server.

  • key: getItinerary
  • direction: client -> server
  • payload: no payload

Client requests current itinerary. Server will respond with itinerary event.

  • key: itinerary
  • direction: server -> client
  • payload: list of ItineraryItems. Note that the list is ordered by time, so there should be no need to sort the list on the client. See definition below:

Error:

  • key: getItineraryError
  • direction: server -> client
export interface Rider {
    firstName: string,
    lastName: string,
}

export interface Address {
    lat: number;
    lng: number;
    street: string;
    streetNumber: string;
    city: string;
}

export interface ItineraryItem {
    itemId: number;      // unique id among all items in the itinerary list
    itemType: string;    // "stop", "break-start", "break-end", "shift-start", "shift-end"
    itemAction: string;  // stops: "pick", "drop", breaks and shifts: "start", "end"
    entityId: number;    // entity's (stop, break, shift) own id
    status: string;
    plannedTime: string;
}

export interface StopItem extends ItineraryItem {
    tripId: number;
    routeId: number;
    passenger: Rider;
    address: Address;
    eta: string;
}

export interface BreakItem extends ItineraryItem {
    eta: string;
}

export interface ShiftItem extends ItineraryItem {
}

Itinerary Update

  • key: itineraryUpdate
  • direction: server -> client
  • payload: top level properties are:
    • upsertedItems: these items are either new or existing items that are being updated. Content of this property is the same as in itinerary event. The list is sorted by time.
    • removedItems: these items have been removed from the itinerary. Each item is
export interface RemovedItineraryItem {
    itemType: string;    // "stop", "break-start", "break-end", "shift-start", "shift-end"
    itemId: number;      // unique id among all items in the itinerary list
    entityId: number;    // entity's (stop, break, shift) own id
}

Send Location

Vehicle should send the location to server periodically.

  • key: location
  • direction: client -> server
  • payload
export interface GpsData {
    lat: number;
    lng: number;
    timestamp: string;
    accuracy: number;
    speed: number;
    bearing: number;
}

export interface Location {
    vehicleNumber: number;
    routeId: number;   // null if not on a route at the moment (between routes)
    vehicleTime: string;  // device's time
    gps: GpsData;
}

Send Stop Perform

When driver performs (or arrives to) a stop, this event should be sent.

  • key: stopPerform
  • direction: client -> server
  • payload
export interface Perform {
    itemType: string;   // "stop", "break-start", "break-end", "shift-start", "shift-end"
    itemId: number;     // optional
    entityId: number;   // stop id (required)
    status: string;     // "arrived", "performed", "no-show"
    vehicleTime: string;
    gps: GpsData;
}

Request Last Location

This event is mainly for simulations. Vehicle may use this event to request its last recorded location. This is a handy way for simulated vehicles to resume driving from their last location if the service has been restarted.

  • key: getLastLocation
  • direction: client -> server
  • payload: no payload

The server will respond with following message:

  • key: lastLocation
  • direction: server -> client
  • payload: the GpsData

Error:

  • key: getLastLocationError
  • direction: server -> client

Errors

In case an operation fails (e.g. getItinerary) fails, server sends and event with Error suffix (e.g. getItineraryError) and following payload:

export interface Error {
    code: string,
    description: string,
}
1.3.2

3 years ago

1.3.1

3 years ago

1.3.1-0

3 years ago

1.3.0

4 years ago

1.2.18

4 years ago

1.2.17

4 years ago

1.2.16

4 years ago

1.2.15

4 years ago

1.2.14

4 years ago

1.2.13

4 years ago

1.2.12

5 years ago

1.2.11

5 years ago

1.2.10

5 years ago

1.2.10-beta.0

5 years ago

1.2.9

5 years ago

1.2.8

5 years ago

1.2.7

5 years ago

1.2.6

5 years ago

1.2.5

5 years ago

1.2.4

5 years ago

1.2.3

6 years ago

1.2.2

6 years ago

1.2.0

6 years ago

1.1.0

6 years ago

1.0.19

6 years ago

1.0.18

6 years ago

1.0.16

6 years ago

1.0.15

6 years ago

1.0.14

6 years ago

1.0.13

6 years ago

1.0.12

6 years ago

1.0.11

6 years ago

1.0.10

6 years ago

1.0.9

6 years ago

1.0.8

6 years ago

1.0.7

6 years ago

1.0.6

6 years ago

1.0.5

6 years ago

1.0.4

6 years ago

1.0.3

6 years ago

1.0.2

6 years ago

1.0.1

6 years ago

1.0.0

6 years ago