Update documentation for v1.2

RadiusNetworks · Mar 27, 2020 · 167163e · 167163e
1 parent 8affe33
commit 167163e
Show file tree

Hide file tree

Showing 4 changed files with 186 additions and 37 deletions.
diff --git a/doc/customer.md b/doc/customer.md
@@ -15,13 +15,15 @@ let customerInfo = CustomerInfo(
 )
 
 // Post it to the API
-FlyBuy.customer.create(withInfo: customerInfo, termsOfService: true, ageVerification: true) { (customer, error) -> (Void) in
+FlyBuy.customer.create(withInfo: customerInfo, termsOfService: userAcceptedTerms, ageVerification: userVerifiedAge) { (customer, error) -> (Void) in
   // Handle customer or deal with error
 }
 ```
 
 _Note: The `phone` parameter is optional_
 
+**IMPORTANT:** If the `termsOfService` and `ageVerification` parameters are not `true`, an error will be returned and the customer will not be created.
+
 ## Login Via Customer Token
 
 Login the user with a previously obtained customer API token

diff --git a/doc/data_models.md b/doc/data_models.md
@@ -0,0 +1,149 @@
+# FlyBuy Data Models
+
+Several data objects are used and returned by the FlyBuy SDK. These include:
+
+- [FlyBuy Data Models](#flybuy-data-models)
+  - [Customer Info](#customer-info)
+  - [Customer](#customer)
+  - [Site](#site)
+  - [Order](#order)
+    - [Customer State ENUM Values](#customer-state-enum-values)
+    - [Order State ENUM Values](#order-state-enum-values)
+    - [Pickup Window](#pickup-window)
+  - [Errors](#errors)
+
+## Customer Info
+
+The `CustomerInfo` type is used to update customer information. It is also returned in the `Order` for the customer information for an order.
+
+```swift
+open class CustomerInfo {
+    public let name: String
+    public let carType: String?
+    public let carColor: String?
+    public let licensePlate: String?
+    public let phone: String?
+}
+```
+
+## Customer
+
+The `Customer` type provide details of the current customer using `FlyBuy.customer.current` and is returned after creating a customer or logging in.
+
+```swift
+open class Customer {
+    public let token: String
+    public let emailAddress: String?
+    public let info: CustomerInfo
+}
+```
+
+## Site
+
+The `Site` type provides details for a particular site.
+
+```swift
+open class Site {
+    public let id: Int
+    public let partnerIdentifier: String?
+    public let name: String?
+    public let phone: String?
+    public let fullAddress: String?
+    public let longitude: String?
+    public let latitude: String?
+    public let instructions: String?
+    public let descriptionText: String?
+    public let coverPhotoURL: String?
+}
+```
+
+## Order
+
+The `Order` type provides details for a order.
+
+```swift
+open class Order {
+    public let id: Int
+    public var state: OrderState
+    public var customerState: CustomerState
+    public let partnerIdentifier: String?
+    public let pickupWindow: PickupWindow?
+    public let pickupType: String?
+    public var etaAt: Date?
+    public let redeemedAt: Date?
+    public var customerRating: String?
+    public var customerComment: String?
+
+    public let siteID: Int
+    public let siteName: String?
+    public let sitePhone: String?
+    public let siteFullAddress: String?
+    public let siteLongitude: String?
+    public let siteLatitude: String?
+    public let siteInstructions: String?
+    public let siteDescription: String?
+    public let siteCoverPhotoURL: String?
+
+    public let customerID: String?
+    public let customerName: String?
+    public let customerCarType: String?
+    public let customerCarColor: String?
+    public let customerLicensePlate: String?
+}
+```
+
+### Customer State ENUM Values
+
+`CustomerState` provides the current status of the customer.
+
+| Value       | Description                                                             |
+|-------------|-------------------------------------------------------------------------|
+| `created`   | Customer has claimed their order                                        |
+| `enRoute`   | Order tracking has started and the customer is on their way             |
+| `nearby`    | Customer is close to the site                                           |
+| `arrived`   | Customer has arrived on site                                            |
+| `waiting`   | Customer is in a pickup area or has manually indicated they are waiting |
+| `completed` | Order is complete                                                       |
+
+### Order State ENUM Values
+
+`OrderState` provide the state of the order from the merchant's perspective. 
+
+| Value       | Description                                                             |
+|-------------|-------------------------------------------------------------------------|
+| `created`   | Order has been created                                                  |
+| `ready`     | Order is ready for customer to claim                                    |
+| `delayed`   | Order has been delayed by merchant after customer arrives               |
+| `cancelled` | Merchant has cancelled order                                            |
+| `completed` | Order is complete                                                       |
+| `gone`      | Returned by API when order does not exist                               |
+
+### Pickup Window 
+
+The `PickupWindow` type provides the time range when an order is expected to be picked up. It will be `nil` if there is no pickup window, i.e., ASAP. If there is just a pickup time, the `start` and `end` will be the same.
+
+```swift
+public class PickupWindow: NSObject {
+    public let start: Date
+    public let end: Date
+}
+```
+
+## Errors
+
+If there is an error for any SDK method, the callback will return a swift `Error` object. 
+
+Possible types include, but are not limited to, the following:
+
+```swift
+public class FlyBuyError : LocalizedError {
+    internal(set) public var errorDescription: String?
+    public let title: String
+}
+```
+
+```swift
+public class FlyBuyAPIError : FlyBuyError {
+    public let statusCode: HTTPStatusCode?
+    public var errors: [String : [String]]?
+```
diff --git a/doc/orders.md b/doc/orders.md
@@ -1,14 +1,16 @@
 # Orders
 
-Examples are in Swift.
+Examples are in Swift. Refer to [Data Models](data_models.md) for details on classes and objects used by the SDK.
 
 - [Fetch Claimed Orders](#fetch-claimed-orders)
 - [Fetch Unclaimed Orders](#fetch-unclaimed-orders)
 - [Observe Orders](#observe-orders)
 - [Claim Orders](#claim-orders)
 - [Create Orders](#create-orders)
 - [Update Orders](#update-orders)
-- [Rate Orders](#rate-orders)
+  - [Update customer state](#update-customer-state)
+  - [Update order state](#update-order-state)
+- [Customer Ratings](#customer-ratings)
 
 ## <span id="fetch-claimed-orders">Fetch Claimed Orders</span>
 
@@ -40,7 +42,7 @@ FlyBuy.orders.closed
 
 ```swift
 FlyBuy.orders.fetch(withRedemptionCode: code) { (order, error)
-  // Update order claim view with order details here
+  // Check error response and update order claim view with order details here
 }
 ```
 
@@ -74,20 +76,29 @@ func registerForNotifications() {
 To claim an order for the current customer, the app should call the `claim` method.
 
 ```swift
+// Create the customer info struct for person picking up (name is required)
 let customerInfo = CustomerInfo(
-  name: "Bob Smith",
-  carType: "Honda Civic",
-  carColor: "white",
-  licensePlate: "ABC-123",
-  phone: "555-5555"
+  name: "Marty McFly",
+  carType: "DeLorean",
+  carColor: "Silver",
+  licensePlate: "OUTATIME",
+  phone: "555-555-5555"
 )
 
 FlyBuy.orders.claim(withRedemptionCode: code, customerInfo: customerInfo) { (order, error)
   // If error == nil, order has been claimed
 }
 ```
 
-After an order is claimed, call `FlyBuy.orders.fetch()` to update the list of orders from the server. The newly claimed order will appear in the list of open orders, which is available via `FlyBuy.orders.open`.
+**IMPORTANT:** Make sure to call `FlyBuy.orders.fetch()` to sync the orders after successfully claiming the order. The newly claimed order will appear in the list of open orders, which is available via `FlyBuy.orders.open`.
+
+Optionally, the pickup type can be set when claiming an order. This is only necessary for apps that do not set the pickup type via backend integrations when the order is created. Supported pickup types currently include `"curbside"`, `"pickup"`, and `"delivery"`. Passing `nil` will leave the `pickupType` unchanged.
+
+```swift
+FlyBuy.orders.claim(withRedemptionCode: code, customerInfo: customerInfo, pickupType: pickupType) { (order, error)
+  // If error == nil, order has been claimed
+}
+```
 
 ## <span id="create-orders">Create Orders</span>
 
@@ -101,11 +112,11 @@ Most orders will have a pickup time of "ASAP". If you have a different pickup wi
 
 ```swift
 let customerInfo = CustomerInfo(
-  name: "Bob Smith",
-  carType: "Honda Civic",
-  carColor: "white",
-  licensePlate: "ABC-123",
-  phone: "555-5555"
+  name: "Marty McFly",
+  carType: "DeLorean",
+  carColor: "Silver",
+  licensePlate: "OUTATIME",
+  phone: "555-555-5555"
 )
 
 FlyBuy.orders.create(siteID: 101, partnerIdentifier: "1234123", customerInfo: customerInfo) { (order, error) -> (Void) in
@@ -127,6 +138,8 @@ window = PickupWindow(<date/time here>)
 
 Orders are always updated with an order event. The order object cannot be updated directly.
 
+### Update customer state
+
 ```swift
 FlyBuy.orders.event(orderID: order.id, customerState: .waiting)
 
@@ -137,12 +150,18 @@ FlyBuy.orders.event(orderID: order.id, customerState: .waiting) { (order, error)
 }
 ```
 
+Refer to [Customer State ENUM Values](data_models.md#customer-state-enum-values) for possible `customerState` values.
+
+### Update order state
+
 You can update an order's state, if necessary, with any valid `OrderState` enum:
 
 ```swift
 FlyBuy.orders.event(orderID: order.id, state: .cancelled)
 ```
 
+Refer to [Order State ENUM Values](#order-state-enum-values) for possible `state` values.
+
 ## <span id="rate-orders">Customer Ratings</span>
 
 If you collect customer ratings in your app, you can pass them to FlyBuy. The `rating` should be an integer and `comments` (optional) should be a string:
@@ -151,25 +170,3 @@ If you collect customer ratings in your app, you can pass them to FlyBuy. The `r
 FlyBuy.orders.rateOrder(orderID: 123, rating: 5, comments: 'Great service')
 ```
 
-## Customer State ENUM Values
-
-| Value       | Description                                                             |
-|-------------|-------------------------------------------------------------------------|
-| `created`   | Customer has claimed their order                                        |
-| `enRoute`   | Order tracking has started and the customer is on their way             |
-| `nearby`    | Customer is close to the site                                           |
-| `arrived`   | Customer has arrived on site                                            |
-| `waiting`   | Customer is in a pickup area or has manually indicated they are waiting |
-| `completed` | Order is complete                                                       |
-
-
-## Order State ENUM Values
-
-| Value       | Description                                                             |
-|-------------|-------------------------------------------------------------------------|
-| `created`   | Order has been created                                                  |
-| `ready`     | Order is ready for customer to claim                                    |
-| `delayed`   | Order has been delayed by merchant after customer arrives               |
-| `cancelled` | Merchant has cancelled order                                            |
-| `completed` | Order is complete                                                       |
-| `gone`      | Returned by API when order does not exist                               |
diff --git a/doc/quickstart.md b/doc/quickstart.md
@@ -110,3 +110,4 @@ Now that you have FlyBuy installed and configured, you need to integrate it with
 - [Managing Customers](customer.md)
 - [Managing Orders](orders.md)
 - [Managing Sites](sites.md)
+- [Data Models](data_models.md)