docs(modules): link published apps samples, fix typos

fixes #12

functions/routes/ecom/modules/apply-discount.js

@@ -1,47 +1,43 @@
 exports.post = ({ appSdk, admin }, req, res) => {
   /**
-    * Requests coming from Modules API have two object properties on body: `params` and `application`.
-    * `application` is a copy of your app installed by the merchant,
-    * including the properties `data` and `hidden_data` with admin settings configured values.
-    * JSON Schema reference for the Apply Discount module objects:
-    * `params`: https://apx-mods.e-com.plus/api/v1/apply_discount/schema.json?store_id=100
-    * `response`: https://apx-mods.e-com.plus/api/v1/apply_discount/response_schema.json?store_id=100
-    */
+   * Requests coming from Modules API have two object properties on body: `params` and `application`.
+   * `application` is a copy of your app installed by the merchant,
+   * including the properties `data` and `hidden_data` with admin settings configured values.
+   * JSON Schema reference for the Apply Discount module objects:
+   * `params`: https://apx-mods.e-com.plus/api/v1/apply_discount/schema.json?store_id=100
+   * `response`: https://apx-mods.e-com.plus/api/v1/apply_discount/response_schema.json?store_id=100
+   *
+   * Complete (advanced) example in our default discouts app:
+   * https://github.com/ecomplus/discounts/blob/master/routes/ecom/modules/apply-discount.js
+   */
 
   const { params, application } = req.body
   const { storeId } = req
-
+  const response = {}
   // merge all app options configured by merchant
   const appData = Object.assign({}, application.data, application.hidden_data)
 
-  // setup basic required response object
-  const response = {
-    discount_rule: {}
+  if (appData.available_extra_discount) {
+    response.available_extra_discount = appData.available_extra_discount
+  }
+  if (params.discount_coupon) {
+    // should match discount by coupon code
   }
 
   /* DO THE STUFF HERE TO FILL RESPONSE OBJECT WITH DISCOUNT OPTIONS */
-  /*
-  // You can set how many discount rules you need. 
-  // But you can leave set up an extra discount that applies with the rules configured in the application. 
-  // example;
-  if (appData.available_extra_discount) {
-    const extra = appData.available_extra_discount
-    const { amount } = params
-
-    if (amount.total <= extra.min_amount) {
-      const discountValue = extra.value
 
-      if (extra.type === 'percentage') {
-        discountValue *= (amount.total / 100)
-      }
-
-      const newAmountTotal = (amount.total - discountValue)
-    }
-
-    response.available_extra_discount = {
-      ...appData.available_extra_discount
+  /**
+   * Sample snippets:
+
+  // set discount value
+  response.discount_rule = {
+    label: 'X Campaign',
+    extra_discount: {
+      value: 20.5,
+      flags: ['x-coupon']
     }
   }
+
   */
 
   res.send(response)

functions/routes/ecom/modules/calculate-shipping.js

@@ -4,9 +4,15 @@ exports.post = ({ appSdk }, req, res) => {
    * JSON Schema reference for Calculate Shipping module objects:
    * `params`: https://apx-mods.e-com.plus/api/v1/calculate_shipping/schema.json?store_id=100
    * `response`: https://apx-mods.e-com.plus/api/v1/calculate_shipping/response_schema.json?store_id=100
+   *
+   * Examples in published apps:
+   * https://github.com/ecomplus/app-mandabem/blob/master/functions/routes/ecom/modules/calculate-shipping.js
+   * https://github.com/ecomplus/app-datafrete/blob/master/functions/routes/ecom/modules/calculate-shipping.js
+   * https://github.com/ecomplus/app-jadlog/blob/master/functions/routes/ecom/modules/calculate-shipping.js
    */
 
   const { params, application } = req.body
+  const { storeId } = req
   // setup basic required response object
   const response = {
     shipping_services: []
@@ -26,5 +32,38 @@ exports.post = ({ appSdk }, req, res) => {
 
   /* DO THE STUFF HERE TO FILL RESPONSE OBJECT WITH SHIPPING SERVICES */
 
+  /**
+   * Sample snippets:
+
+  if (params.items) {
+    let totalWeight = 0
+    params.items.forEach(item => {
+      // treat items to ship
+      totalWeight += item.quantity * item.weight.value
+    })
+  }
+
+  // add new shipping service option
+  response.shipping_services.push({
+    label: appData.label || 'My shipping method',
+    carrier: 'My carrier',
+    shipping_line: {
+      from: appData.from,
+      to: params.to,
+      package: {
+        weight: {
+          value: totalWeight
+        }
+      },
+      price: 10,
+      delivery_time: {
+        days: 3,
+        working_days: true
+      }
+    }
+  })
+
+  */
+
   res.send(response)
 }

functions/routes/ecom/modules/create-transaction.js

@@ -1,51 +1,49 @@
 exports.post = ({ appSdk, admin }, req, res) => {
   /**
-   * Requests coming from the modules receive a hydrated body with two objects, `params` and application`.
+   * Requests coming from Modules API have two object properties on body: `params` and `application`.
    * `application` is a copy of your app installed by the merchant,
    * including the properties `data` and `hidden_data` with admin settings configured values.
    * JSON Schema reference for the Create Transaction module objects:
    * `params`: https://apx-mods.e-com.plus/api/v1/create_transaction/schema.json?store_id=100
    * `response`: https://apx-mods.e-com.plus/api/v1/create_transaction/response_schema.json?store_id=100
+   *
+   * Examples in published apps:
+   * https://github.com/ecomplus/app-pagarme/blob/master/functions/routes/ecom/modules/create-transaction.js
+   * https://github.com/ecomplus/app-custom-payment/blob/master/functions/routes/ecom/modules/create-transaction.js
    */
 
   const { params, application } = req.body
   const { storeId } = req
-
   // merge all app options configured by merchant
   const appData = Object.assign({}, application.data, application.hidden_data)
-
-  // payment `transaction` object
-  // required in `response` object and must follow schema: https://apx-mods.e-com.plus/api/v1/create_transaction/response_schema.json?store_id=100
+  // setup required `transaction` response object
   const transaction = {}
 
-  // Indicates whether the buyer should be redirected to payment link right after checkout
+  // indicates whether the buyer should be redirected to payment link right after checkout
   let redirectToPayment = false
 
   /**
    * Do the stuff here, call external web service or just fill the `transaction` object
-   * according to the by the chosen payment_method.
-   * `response`: https://apx-mods.e-com.plus/api/v1/create_transaction/response_schema.json?store_id=100
+   * according to the `appData` configured options for the chosen payment method.
    */
+
+  // WIP:
   switch (params.payment_method.code) {
     case 'credit_card':
-      // 
-      break;
+      // you may need to handle card hash and create transaction on gateway API
+      break
     case 'banking_billet':
-      //  
-      break;
+      // create new "Boleto bancário"
+      break
     case 'online_debit':
-      // redirectToPayment = true
-      break;
+      redirectToPayment = true
+      break
     default:
-      break;
+      break
   }
 
-  // setup basic required response object
-  // must follow schema : https://apx-mods.e-com.plus/api/v1/create_transaction/response_schema.json?store_id=100
-  const response = {
+  res.send({
     redirect_to_payment: redirectToPayment,
     transaction
-  }
-
-  res.send(response)
+  })
 }

functions/routes/ecom/modules/list-payments.js

@@ -1,41 +1,48 @@
 exports.post = ({ appSdk }, req, res) => {
   /**
-   * Requests coming from the modules receive a hydrated body with two objects, `params` and application`.
-   * In `application` is a copy of your application installed by the merchant, including the properties` data` and `hidden_data`.
-   * JSON Schema of the list_payments module
+   * Requests coming from Modules API have two object properties on body: `params` and `application`.
+   * `application` is a copy of your app installed by the merchant,
+   * including the properties `data` and `hidden_data` with admin settings configured values.
+   * JSON Schema reference for the List Payments module objects:
    * `params`: https://apx-mods.e-com.plus/api/v1/list_payments/schema.json?store_id=100
    * `response`: https://apx-mods.e-com.plus/api/v1/list_payments/response_schema.json?store_id=100
+   *
+   * Examples in published apps:
+   * https://github.com/ecomplus/app-pagarme/blob/master/functions/routes/ecom/modules/list-payments.js
+   * https://github.com/ecomplus/app-custom-payment/blob/master/functions/routes/ecom/modules/list-payments.js
    */
+
   const { params, application } = req.body
   const { storeId } = req
-
-  // merge all app options configured by merchant
-  const appData = Object.assign({}, application.data, application.hidden_data)
-
   // setup basic required response object
-  // Must follow schema: https://apx-mods.e-com.plus/api/v1/list_payments/response_schema.json?store_id=100
   const response = {
     payment_gateways: []
   }
+  // merge all app options configured by merchant
+  const appData = Object.assign({}, application.data, application.hidden_data)
 
   /* DO THE STUFF HERE TO FILL RESPONSE OBJECT WITH PAYMENT GATEWAYS */
-  /* 
-    // eg;
-    response.payment_gateways.push({
-      intermediator: {
-        code: 'paupay',
-        link: 'https://www.paupay.com.br',
-        name: 'paupay'
-      },
-      payment_url: 'https://www.paupay.com.br/',
-      type: 'payment',
-      payment_method: {
-        code: 'banking_billet',
-        name: 'Boleto Bancário'
-      },
-      label: 'Boleto Bancário',
-      expiration_date: appData.banking_billet.expiration_date || 14
-    })
+
+  /**
+   * Sample snippets:
+
+  // add new payment method option
+  response.payment_gateways.push({
+    intermediator: {
+      code: 'paupay',
+      link: 'https://www.palpay.com.br',
+      name: 'paupay'
+    },
+    payment_url: 'https://www.palpay.com.br/',
+    type: 'payment',
+    payment_method: {
+      code: 'banking_billet',
+      name: 'Boleto Bancário'
+    },
+    label: 'Boleto Bancário',
+    expiration_date: appData.expiration_date || 14
+  })
+
   */
 
   res.send(response)