CocoaPods trunk is moving to be read-only. Read more on the blog, there are 19 months to go.

Handybook 1.0.0

Handybook 1.0.0

×

TestsTested ✓
LangLanguage Obj-CObjective C
License MIT
ReleasedLast Release Dec 2014

Maintained by Muhammad Ibrahim.

 
Depends on:
AFNetworking~> 2.2
Stripe~> 1.1
 

Handybook 1.0.0

Handybook iOS Cocoapod

By Muhammad Ibrahim (@0ibrahim) and Jayant Sani (@jsani0102)

Description

The Handybook Cocoapod is an Objective-C wrapper around the Handybook API and provides third party developers accesss to the Handybook services (e.g booking a cleaning, any sort of handyman etc). Using these files you can intergrate the functionality of the Handybook API into your own app and make bookings using Handybook.

For example, an app that helps people to plan parties can make use of the Handybook Cocoapod by offering to book a cleaning the morning after.

How to get an API key?

To interface with the Handybook API you need an API key. To request an API key please email [email protected]

Getting Started

Follow these steps to get started with using this pod:
1. Add pod 'Handybook', '1.0' to your Podfile
2. Using the command line execute pod install in the project directory
3. Add your API_KEY and API_SECRET in the HBAPI.m file 4. Import the appropriate API files by adding the right header to your source file e.g #import <Handybook/HBAPIBooking.h> for using the booking methods
5. Access the singleton methods using e.g. [[HBAPI sharedInstance] createBooking:];

Testing Environment

By default the Pod will hit the handybook staging server so that developers can test their code. Once your application has gone through review, you will be provided with your production key and secret which will allow you to make real bookings.

To enable production bookings, change the baseURL in HBAPI.m by replacing s-handybook.hbinternal.com with www.handybook.com

Bookings - HBAPIBooking.h

The flow to make a Handybook booking looks like the following:
  1. Create the booking object, fill in the necessary information to make the booking
  2. Make the booking with a network call - createBooking:successBlock:failureBlock:

  3. Pay for the booking (see below for options)

  • Payment with an existing user:
    • All the user's information must be included in the HBUser property of the HBBooking object
    • Call the appropriate payment method - payForBookingWithExistingUser
  • Payment without an existing user:
    • The HBUser property of the HBBooking object should be nil
    • Generate a new stripe token to associate with the user - stripeTokenWithCard:expirationMonth:expirationYear:cvc:
    • Call the appropriate payment method - payForBooking:WithStripeToken:firstName:lastName:address:aptNumber:phoneNumber:
    • Prompt for a password, persist the user in our servers - getConfirmationForBooking:password: 
    /**
     * Use this method to get a quote for a booking that you want to make. Returns 
     * the price, hours and timings of booking as a JSON object.
     *
     * @params
     * booking - HBBooking object filled in with booking information  
     **/

    - (void)createBooking:(HBBooking *)booking
         successBlock:(void(^)(NSDictionary *responseObject))successBlock
         failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Use this method to get a quote when you have a voucher code. Return the 
     * discounted price, hours and timings of the booking quote.
     *
     * @params
     * booking - HBBooking object filled in with booking info
     * voucher - voucher code that is to be applied to the booking for discount
     **/

    - (void)createBooking:(HBBooking *)booking
              WithVoucher:(NSString *)voucher
             successBlock:(void(^)(NSDictionary *responseObject))successBlock
             failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Use this method to pay for a booking when there is an existing user. 
     * The booking object must have a user property of type HBUser. This 
     * completes the booking and returns a confirmation with time of booking 
     * and price.
     *
     * @params
     * booking - HBBooking object filled in with booking info
     **/

    - (void)payForBookingWithExistingUser:(HBBooking *)booking
                         successBlock:(void(^)(NSDictionary *responseObject))successBlock
                         failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Use this method to pay for a booking when there is no user.
     * 
     * @params
     * booking - HBBooking object filled in with booking info
     * stripeToken - get stripeToken from stripeToken generator by passing credit card info.
     * firstName - first name of user
     * lastName - last name of user
     * address - address of the user
     * aptNumber - address line 2
     * phoneNumber - phone number of the user
     *
     **/

    - (void)payForBooking:(HBBooking *)booking
          WithStripeToken:(NSString *)stripeToken
                firstName:(NSString *)firstName
                 lastName:(NSString *)lastName
                  address:(NSString *)address
                aptNumber:(NSString *)aptNumber
              phoneNumber:(NSString *)phone
             successBlock:(void(^)(NSDictionary *responseObject))successBlock
             failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * User this method to set a new booking date for bookings where you have made the 
     * quote but not completed the payment.
     *
     * @params
     * booking - HBBooking object filled with booking info
     * Date - date to be set for new booking (yyyy-MM-dd HH:mm)
     **/

    - (void)setNewBooking:(HBBooking *)booking
                     Date:(NSString*)date
             successBlock:(void(^)(NSDictionary *responseObject))successBlock
             failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Cancel a booking that has already been paid for.
     *
     * @params
     * booking - HBBooking object filled in with booking info
     * cancellationReason - number representing the reason from preCancellationInfoForBooking (1 - 5)
     **/

    - (void)cancelBooking:(HBBooking *)booking
       cancellationReason:(NSNumber *)cancellationReason
             successBlock:(void(^)(NSDictionary *responseObject)) successBlock
             failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Reschedule an existing booking. This operation differs from setting a new
     * booking date because a booking can only be rescheduled after it has been 
     * paid for. A new date can only be set if the booking has not been paid yet.
     *
     * @params
     * booking - the HBBooking object that contains all the booking information
     * date - the date that the booking should be rescheduled for. ([yyyy-MM-dd HH:mm])
     * @optional rescheduleAll - if this is a recurring booking and all future bookings
     * should be rescheduled, set to "1". If only a one-time occurrence, set to "0".
     **/

    - (void)rescheduleBooking:(HBBooking *)booking
                      forDate:(NSString *)date
                rescheduleAll:(NSString *)rescheduleAll
                 successBlock:(void(^)(NSDictionary *responseObject))successBlock
                 failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Replicate an existing booking. Creates a new booking with exactly
     * the same characteristics as the booking that is being duplicated.
     *
     * @params
     * booking - the HBBooking object that contains all the booking informations
     **/

    - (void)duplicateBooking:(HBBooking *)booking
                successBlock:(void(^)(NSDictionary *responseObject))successBlock
                failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Validates a zipcode for a specific booking, checking if the particular service
     * is available in a certain zipcode. A promo code can also be passed to see if
     * the code is available in a certain area, as some promos are region-specific.
     *
     * @params
     * booking - the HBBooking object that contains all the booking information
     * @optional promo - the promo code, pass nil if not applicable
     **/

    - (void)checkZipcodeforBooking:(HBBooking *)booking
                WithPromoIfPresent:(NSString *)promo
                      successBlock:(void(^)(NSDictionary *responseObject))successBlock
                      failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Displays the precancelation info for a specific booking. The precancelation info
     * is presented before a user cancels their booking, listing the reasons for why
     * the booking might be cancelled. The user must specify a reason when cancelling.
     *
     * @params
     * booking - the HBBooking object that contains the booking information
     **/

    - (void)getPrecancelationInfoForBooking:(HBBooking *)booking
                               successBlock:(void(^)(NSDictionary *responseObject))successBlock
                               failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Part of the post-booking flow, this method confirms that a booking quote has been
     * created an that the booking has been paid. In addition, a password parameter can be
     * passed into the method to create and persist a user if the user did not previously
     * exist.
     *
     **/

    - (void)getConfirmationForBooking:(HBBooking *)booking
                             password:(NSString *)password
                         successBlock:(void(^)(NSDictionary *responseObject))successBlock
                         failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Enter a promo code in order to receive a discount price before the booking flow. 
     *
     * @params
     * promoCode - the promo code to be applied
     **/

    - (void)getPrebookingPromo:(NSString *)promoCode
                  successBlock:(void(^)(NSDictionary *responseObject))successBlock
                  failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Apply a coupon to a booking for a discounted price.
     * 
     * @params
     * coupon - the coupon code to apply to the booking
     * booking - the HBBooking object that contains the booking information
     **/

    - (void)applyCoupon:(NSString *)coupon
              toBooking:(HBBooking *)booking
           successBlock:(void(^)(NSDictionary *responseObject))successBlock
           failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Remove a coupon from a booking. The booking must already have a coupon applied to it.
     *
     * @params
     * booking - the HBBooking object that contains the booking information
     **/

    - (void)removeCouponFromBooking:(HBBooking *)booking
                       successBlock:(void(^)(NSDictionary *responseObject))successBlock
                       failureBlock:(void(^)(NSError *error))failureBlock

Users - HBAPIUser.h

    /**
     * Create a session by logging in a user. The responseObject for this API
     * call contains the user_id and auth_token, which will be needed in
     * subsequent calls.
     *
     * @params
     * email - the user's email
     * password - the password for the user's account
     **/

    - (void)loginWithEmail:(NSString *)email
               andPassword:(NSString *)password
              successBlock:(void(^)(NSDictionary *responseObject))successBlock
              failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Get all the bookings associated with a user.
     *
     * @params
     * user - the HBUser object that contains the user's information
     **/

    - (void)getBookingsForUser:(HBUser *)user
                  successBlock:(void(^)(NSDictionary *responseObject))successBlock
                  failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Get the user's information, which includes their addresses and bookings,
     * among other information.
     *
     * @params
     * user - the HBUser object that contains the user's information
     **/

    - (void)getInfoForUser:(HBUser *)user
              successBlock:(void(^)(NSDictionary *responseObject))successBlock
              failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Share the user's information. Retrieve a promo code to give to friends
     * to get discounts on bookings. The user can share the code through
     * social media.
     *
     * @params
     * user - the HBUser object that contains the user's information
     **/

     - (void)shareInfoForUser:(HBUser *)user
            successBlock:(void(^)(NSDictionary *responseObject))successBlock
            failureBlock:(void(^)(NSError *error))failureBlock
    /**
     * Make modifications to the user's personal information. Input different
     * information than the user's confirmation in order to change it. For
     * example, if the user's current listed name is "Bill," but the user wants
     * to change it to "William," pass in "William" as the firstName parameter
     * to change the user's first name to "William" on our servers.
     * @Note - the password parameters are optional. They are only needed if
     * the user wants to change their password. Otherwise, pass in nil.
     *
     * @params
     * user - the HBUser object that contains the user's information
     * firstName - the user's desired first name
     * lastName - the user's desired last name
     * email - the user's desired email
     * phoneNumber - the user's desired phone number
     * @optional - the following parameters are only needed if the user wants to change their password:
     * currentPassword - the user's current password
     * newPassword - the user's desired new password
     * passwordConfirmation - to confirm the password, must match the new password
     **/

    - (void)editUserInfo:(HBUser *)user
           WithFirstName:(NSString *)firstName
                lastName:(NSString *)lastName
                   email:(NSString *)email
             phoneNumber:(NSString *)phoneNumber
         currentPassword:(NSString *)currentPassword
             newPassword:(NSString *)newPassword
    passwordConfirmation:(NSString *)passwordConfirmation
            successBlock:(void(^)(NSDictionary *responseObject))successBlock
            failureBlock:(void(^)(NSError *error))failureBlock

Services - HBAPIServices.h

    /**
     * Retrieves all the home services that Handybook offers. Returns a 
     * dictionary that maps a particular service's name to its service ID in 
     * the success block.
     *
     * @params - none
     **/

    - (void)getAllServices:(void(^)(NSDictionary *responseObject))successBlock
              failureBlock:(void(^)(NSError *error))failureBlock

Service Attributes - HBAPIServiceAttributes.h

    /**
     * Retrieves the service attributes for a certain serviceID. Returns an 
     * array of HBServiceAttributes objects that must be filled in before
     * creating a booking in the success block.
     *
     * @params
     * serviceID - the numerical ID of a specific services 
     * (ex. home cleaning's service ID is 3)
     **/

    - (void)getServiceAttributesForService:(NSNumber *)serviceID
                              successBlock:(void(^)(NSArray *responseObject))successBlock
                              failureBlock:(void(^)(NSError *error))failureBlock

Stripe Token Generator - HBStripeTokenGenerator.h

    /**
     * Generates a stripe token for a new user
     * 
     * @params
     * cardNumber - the user's credit card number
     * month - the credit card's expiration month
     * year - the credit card's expiration year
     * cvc - the credit card's cvc number (3 digits)
     **/

    + (void)stripeTokenWithCard:(NSString *)cardNumber
                expirationMonth:(NSNumber *)month
                 expirationYear:(NSNumber *)year
                            cvc:(NSString *)cvc
                   successBlock:(void(^)(NSString *stripeToken))successBlock
                        failure:(void(^)(NSError *error))failureBlock