npm - @storecraft/payments-paypal - Versions diffs - 1.0.0 - Mend

@storecraft/payments-paypal 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md +43 -0
package/adapter.html.js +136 -0
package/adapter.js +377 -0
package/adapter.utils.js +76 -0
package/index.js +1 -0
package/package.json +34 -0
package/tests/storage.test.js +11 -0
package/tsconfig.json +14 -0
package/types.checkout_orders_v2.d.ts +6960 -0
package/types.private.d.ts +6 -0
package/types.public.d.ts +33 -0

package/README.md ADDED Viewed

@@ -0,0 +1,43 @@
+# Paypal payment gateway for **StoreCraft**
+[paypal standard](https://developer.paypal.com/docs/checkout/standard/) integration
+## Features
+- Create checkouts with `AUTHORIZE` or `CAPTURE` intents
+- `capture`, `void`, `refund` actions
+- Get a readable and explainable `status`
+- Supports both `prod` and `test` endpoints
+```bash
+npm i @storecraft/payments-paypal-standard
+```
+## Howto
+```js
+const config = {
+  env: 'prod',
+  client_id: '<get-from-your-paypal-dashboard>',
+  secret: '<get-from-your-paypal-dashboard>',
+  currency_code: 'USD',
+  intent_on_checkout: 'AUTHORIZE'
+}
+new PaypalStandard(config);
+```
+## Developer info and test
+Integration examples
+- https://developer.paypal.com/studio/checkout/standard/integrate
+Credit Card Generator
+- https://developer.paypal.com/tools/sandbox/card-testing/#link-creditcardgenerator
+## todo:
+- Add tests
+- Think about adding more dynamic config
+```text
+Author: Tomer Shalev (tomer.shalev@gmail.com)
+```

package/adapter.html.js ADDED Viewed

@@ -0,0 +1,136 @@
+/**
+ *
+ * @description Official PayPal UI integration with `storecraft`.
+ *
+ * Test with dummy data with this generator
+ * https://developer.paypal.com/tools/sandbox/card-testing/#link-creditcardgenerator.
+ *
+ * Or use the following dummy details:
+ * - Card number: 4032033785933750
+ * - Expiry date: 12/2027
+ * - CVC code: 897
+ *
+ * @param {import("./types.public.js").Config} config
+ * @param {Partial<import("@storecraft/core/v-api").OrderData>} order_data
+ */
+export default function html_buy_ui(config, order_data) {
+  const orderData = order_data?.payment_gateway?.on_checkout_create;
+  return `
+<!DOCTYPE html>
+<html style="height: 100%; width: 100%">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width; height=device-height, initial-scale=1.0" />
+    <title>PayPal JS SDK Standard Integration</title>
+  </head>
+  <body style='display: flex; flex-direction: column; justify-content: start; height: 100%; align-items: center;'>
+      <div id="paypal-button-container" style='width: 100%' ></div>
+      <p id="result-message"></p>
+    <!-- Initialize the JS-SDK -->
+    <script src="https://www.paypal.com/sdk/js?currency=${config.default_currency_code}&client-id=${config.client_id}&intent=${config.intent_on_checkout.toLowerCase()}"></script>
+    <!-- code -->
+    <script>
+    const resultMessage = (msg) => {
+      document.getElementById('result-message').innerHTML = msg
+      console.log(msg);
+    }
+    window.paypal
+      .Buttons(
+        {
+          style: {
+            shape: "rect",
+            layout: "vertical",
+            color: "gold",
+            label: "paypal",
+            disableMaxWidth: true
+          },
+          message: {
+            amount: ${order_data.pricing.total},
+          },
+          async createOrder() {
+            try {
+              if ('${orderData.id}') {
+                return '${orderData.id}';
+              }
+              const errorDetail = ${orderData?.details?.[0]};
+              const errorMessage = errorDetail
+                ? (errorDetail.issue + errorDetail.description + "(" + '${orderData.debug_id}' + ")")
+                : JSON.stringify(orderData);
+              throw new Error(errorMessage);
+            } catch (error) {
+              console.error(error);
+              resultMessage("Could not initiate PayPal Checkout...<br><br> " + error);
+            }
+          },
+          async onApprove(data, actions) {
+            try {
+              const response = await fetch("/api/checkout/${order_data.id}/complete", {
+                method: "POST",
+                headers: {
+                  "Content-Type": "application/json",
+                },
+              });
+              const orderData_main = await response.json();
+              const orderData = orderData_main.payment_gateway.on_checkout_complete;
+              // Three cases to handle:
+              //   (1) Recoverable INSTRUMENT_DECLINED -> call actions.restart()
+              //   (2) Other non-recoverable errors -> Show a failure message
+              //   (3) Successful transaction -> Show confirmation or thank you message
+              const errorDetail = orderData?.details?.[0];
+              if (errorDetail?.issue === "INSTRUMENT_DECLINED") {
+                // (1) Recoverable INSTRUMENT_DECLINED -> call actions.restart()
+                // recoverable state, per
+                // https://developer.paypal.com/docs/checkout/standard/customize/handle-funding-failures/
+                return actions.restart();
+              } else if (errorDetail) {
+                // (2) Other non-recoverable errors -> Show a failure message
+                throw new Error(errorDetail.description + "(" + orderData.debug_id + ")");
+              }
+              // else if (!orderData.purchase_units) {
+              //   throw new Error(JSON.stringify(orderData));
+              // }
+              else {
+                // (3) Successful transaction -> Show confirmation or thank you message
+                // Or go to another URL:  actions.redirect('thank_you.html');
+                const transaction =
+                  orderData?.purchase_units?.[0]?.payments?.captures?.[0] ||
+                  orderData?.purchase_units?.[0]?.payments?.authorizations?.[0];
+                resultMessage(
+                  "Transaction " + transaction?.status + ":" + transaction?.id +
+                  " See console for all available details"
+                );
+                console.log(
+                  "Capture result",
+                  orderData,
+                  JSON.stringify(orderData, null, 2)
+                );
+              }
+            } catch (error) {
+              console.error(error);
+              resultMessage(
+                "Sorry, your transaction could not be processed... " + error
+              );
+            }
+          }
+        }
+      ).render("#paypal-button-container");
+    </script>
+  </body>
+</html>
+    `
+}

package/adapter.js ADDED Viewed

@@ -0,0 +1,377 @@
+import { CheckoutStatusEnum, PaymentOptionsEnum } from '@storecraft/core/v-api/types.api.enums.js';
+import { fetch_with_auth, throw_bad_response } from './adapter.utils.js';
+import { StorecraftError } from '@storecraft/core/v-api/utils.func.js';
+import html_buy_ui from './adapter.html.js';
+/**
+ * @typedef {import('./types.private.js').paypal_order} CreateResult
+ * @typedef {import('@storecraft/core/v-api').PaymentGatewayStatus} PaymentGatewayStatus
+ * @typedef {import('@storecraft/core/v-api').CheckoutStatusEnum} CheckoutStatusOptions
+ * @typedef {import('@storecraft/core/v-api').OrderData} OrderData
+ * @typedef {import('./types.public.js').Config} Config
+ * @typedef {import('@storecraft/core/v-payments').payment_gateway<Config, CreateResult>} payment_gateway
+ */
+/**
+ * @implements {payment_gateway}
+ *
+ * @description **Paypal Payment** gateway (https://developer.paypal.com/docs/checkout/)
+ */
+export class Paypal {
+  /** @type {Config} */ #_config;
+  /**
+   *
+   * @param {Config} config
+   */
+  constructor(config) {
+    this.#_config = this.#validate_and_resolve_config(config);
+  }
+  /**
+   *
+   * @param {Config} config
+   */
+  #validate_and_resolve_config(config) {
+    config = {
+      default_currency_code: 'USD',
+      env: 'prod',
+      intent_on_checkout: 'AUTHORIZE',
+      ...config,
+    }
+    const is_valid = config.client_id && config.secret;
+    if(!is_valid) {
+      throw new StorecraftError(
+        `Payment gateway ${this.info.name ?? 'unknown'} has invalid config !!!
+        Missing client_id or secret`
+      )
+    }
+    return config;
+  }
+  get info() {
+    return {
+      name: 'Paypal payments',
+      description: `Set up standard and advanced payments to present payment buttons to your payers so they can pay with PayPal, debit and credit cards, Pay Later options, Venmo, and alternative payment methods.
+      You can get started quickly with this 15-minute copy-and-paste integration. If you have an older Checkout integration, you can upgrade your Checkout integration.`,
+      url: 'https://developer.paypal.com/docs/checkout/',
+      logo_url: 'https://www.paypalobjects.com/webstatic/mktg/logo/pp_cc_mark_37x23.jpg'
+    }
+  }
+  get config() {
+    return this.#_config;
+  }
+  get actions() {
+    return [
+      {
+        handle: 'capture',
+        name: 'Capture',
+        description: 'Capture an authorized payment'
+      },
+      {
+        handle: 'void',
+        name: 'Void',
+        description: 'Cancel an authorized payment'
+      },
+      {
+        handle: 'refund',
+        name: 'Refund',
+        description: 'Refund a captured payment'
+      },
+    ]
+  }
+  /**
+   *
+   * @type {payment_gateway["invokeAction"]}
+   */
+  invokeAction(action_handle) {
+    switch (action_handle) {
+      case 'capture':
+        return this.capture.bind(this);
+      case 'void':
+        return this.void.bind(this);
+      case 'refund':
+        return this.refund.bind(this);
+      default:
+        break;
+    }
+  }
+  /**
+   * @description (Optional) buy link ui
+   *
+   * @param {Partial<OrderData>} order
+   *
+   * @return {Promise<string>} html
+   */
+  async onBuyLinkHtml(order) {
+    return html_buy_ui(
+      this.config, order
+    )
+  }
+  /**
+   * @description TODO: the user prefers to capture intent instead
+   *
+   * @param {OrderData} order
+   *
+   * @return {Promise<CreateResult>}
+   */
+  async onCheckoutCreate(order) {
+    const { default_currency_code: currency_code, intent_on_checkout } = this.config;
+    /** @type {import('./types.private.js').paypal_order_request} */
+    const body = {
+      intent: intent_on_checkout==='AUTHORIZE' ? 'AUTHORIZE' : 'CAPTURE',
+      purchase_units: [
+        {
+          custom_id: order.id,
+          amount: {
+            currency_code: currency_code,
+            value: order.pricing.total.toFixed(2),
+          },
+          invoice_id: `${order.id}_${Date.now()}`
+        },
+      ],
+    }
+    const response = await fetch_with_auth(
+      this.config, 'v2/checkout/orders', {
+        method: 'post',
+        body: JSON.stringify(body),
+      }
+    );
+    await throw_bad_response(response);
+    /** @type {CreateResult} */
+    const json = await response.json();
+    return json;
+  }
+  /**
+   * @description todo: logic for if user wanted capture at approval
+   *
+   * @param {CreateResult} create_result
+   *
+   * @return {ReturnType<payment_gateway["onCheckoutComplete"]>}
+   */
+  async onCheckoutComplete(create_result) {
+    // the url based on authorize or capture intent
+    const url = this.config.intent_on_checkout==='AUTHORIZE' ?
+          `v2/checkout/orders/${create_result.id}/authorize` :
+          `v2/checkout/orders/${create_result.id}/capture`;
+    const response = await fetch_with_auth(
+      this.config, url,
+      { method: 'post' }
+    );
+    await throw_bad_response(response);
+    /** @type {import('./types.private.js').paypal_order} */
+    const payload = await response.json();
+    let status;
+    switch(payload.status) {
+      case 'COMPLETED':
+        status = {
+          payment: PaymentOptionsEnum.authorized,
+          checkout: CheckoutStatusEnum.complete
+        }
+        break;
+      case 'PAYER_ACTION_REQUIRED':
+        status = {
+          checkout: CheckoutStatusEnum.requires_action
+        }
+        break;
+      default:
+        status = {
+          checkout: CheckoutStatusEnum.failed
+        }
+        break;
+    }
+    return {
+      status,
+      onCheckoutComplete: payload
+    }
+  }
+  /**
+   * @description Fetch the order and analyze it's status
+   *
+   *
+   * @param {CreateResult} create_result
+   *
+   *
+   * @returns {Promise<PaymentGatewayStatus>}
+   */
+  async status(create_result) {
+    const o = await this.retrieve_order(create_result);
+    const purchase_unit = o.purchase_units?.[0];
+    const authorization = purchase_unit?.payments?.authorizations?.[0];
+    const capture = purchase_unit?.payments?.captures?.[0];
+    const refund = purchase_unit?.payments?.refunds?.[0];
+    /** @type {PaymentGatewayStatus} */
+    const stat = {
+      messages: [],
+      actions: this.actions
+    }
+    /** @param {typeof authorization | typeof capture | typeof refund} u */
+    const get_values = u => {
+      return {
+        currency_code: u.amount.currency_code,
+        price: u.amount.value,
+        reason: u?.status_details?.reason,
+        create_time: new Date(u?.create_time).toUTCString(),
+        update_time: new Date(u?.update_time).toUTCString(),
+        id: u?.id, status: u.status
+      }
+    }
+    if(refund) {
+      const v = get_values(refund);
+      stat.messages = [
+        `**${v.price}${v.currency_code}** were tried to be \`REFUNDED\` at \`${v.create_time}\``,
+        `The status is \`${v.status}\`, updated at \`${v.update_time}\``,
+        v.reason && `The reason for this status is \`${v.reason}\``,
+        `Refund ID is \`${v.id}\`.`
+      ].filter(Boolean);
+    } else if(capture) {
+      const v = get_values(capture);
+      stat.messages = [
+        `**${v.price}${v.currency_code}** were tried to be \`CAPTURED\` at \`${v.create_time}\``,
+        `The status is \`${v.status}\`, updated at \`${v.update_time}\``,
+        v.reason && `The reason for this status is \`${v.reason}\``,
+        `Capture ID is \`${v.id}\`.`
+      ].filter(Boolean);
+    } else if (authorization) {
+      const v = get_values(authorization);
+      const expiration_time = new Date(authorization?.expiration_time).toUTCString();
+      stat.messages = [
+        `**${v.price}${v.currency_code}** were tried to be \`AUTHORIZED\` at \`${v.create_time}\``,
+        `The status is \`${authorization.status}\`, updated at \`${v.update_time}\``,
+        `The authorization will expire at \`${expiration_time}\``,
+        v.reason && `The reason for this status is \`${v.reason}\``,
+        `Authorization ID is \`${v.id}\`.`
+      ].filter(Boolean);
+    } else { // just an intent
+      const currency_code = purchase_unit.amount.currency_code;
+      const price = purchase_unit.amount.value;
+      stat.messages = [
+        `An intent to **${o.intent}** of **${price}${currency_code}** was initiated`,
+        `The status is \`${o.status}\``
+      ];
+    }
+    return stat;
+  }
+  /**
+   * @description [https://developer.paypal.com/api/rest/webhooks/rest/](https://developer.paypal.com/api/rest/webhooks/rest/)
+   *
+   * @param {Request} request
+   */
+  async webhook(request) {
+    return null;
+  }
+  /**
+   * @description Retrieve latest order payload
+   *
+   * @param {CreateResult} create_result first create result, holds paypal id
+   *
+   * @return {Promise<import('./types.private.js').paypal_order>}
+   */
+  retrieve_order = async (create_result) => {
+    const response = await fetch_with_auth(
+      this.config,
+      `v2/checkout/orders/${create_result.id}`,
+      { method: 'get' }
+    );
+    await throw_bad_response(response);
+    /** @type {import('./types.private.js').paypal_order} */
+    const jsonData = await response.json();
+    return jsonData;
+  }
+  // actions
+  /**
+   * @description todo: logic for if user wanted capture at approval
+   *
+   * @param {CreateResult} create_result
+   */
+  async void(create_result) {
+    const paypal_order = await this.retrieve_order(create_result);
+    const authorization_id = paypal_order?.purchase_units?.[0]?.payments?.authorizations?.[0]?.id
+    const response = await fetch_with_auth(
+      this.config,
+      `v2/payments/authorizations/${authorization_id}/void`,
+      { method: 'post' }
+    );
+    await throw_bad_response(response);
+    return this.status(create_result);
+  }
+  /**
+   * @description todo: logic for if user wanted capture at approval
+   *
+   * @param {CreateResult} create_result
+   */
+  async capture(create_result) {
+    const paypal_order = await this.retrieve_order(create_result);
+    const authorization_id = paypal_order?.purchase_units?.[0]?.payments?.authorizations?.[0]?.id
+    const response = await fetch_with_auth(
+      this.config,
+      `v2/payments/authorizations/${authorization_id}/capture`,
+      { method: 'post' }
+    );
+    await throw_bad_response(response);
+    return this.status(create_result);
+  }
+  /**
+   * @description todo: logic for if user wanted capture at approval
+   *
+   * @param {CreateResult} create_result
+   */
+  async refund(create_result) {
+    const paypal_order = await this.retrieve_order(create_result);
+    const capture_id = paypal_order?.purchase_units?.[0]?.payments?.captures?.[0]?.id;
+    const response = await fetch_with_auth(
+      this.config,
+      `v2/payments/captures/${capture_id}/refund`,
+      { method: 'post' }
+    );
+    await throw_bad_response(response);
+    return this.status(create_result);
+  }
+}

package/adapter.utils.js ADDED Viewed

@@ -0,0 +1,76 @@
+export const endpoints = {
+  test: 'https://api-m.sandbox.paypal.com',
+  prod: 'https://api-m.paypal.com'
+}
+/**
+ * @typedef {import("./types.public.js").Config} Config
+ */
+/**
+ * @param {Config} config
+ */
+export const get_endpoint = (config) => endpoints[config.env==='test' ? 'test': 'prod'];
+/** @param {Response} response */
+export const throw_bad_response = async (response) => {
+  if(!response.ok) throw new Error(await response.text());
+}
+/**
+ * get access token if it has expired
+ *
+ * @param {Config} config
+ * @returns {Promise<{ access_token: string, endpoint: string }>}
+ */
+export const getAccessToken = async (config) => {
+  const { client_id, secret } = config;
+  const endpoint = get_endpoint(config);
+  const auth = btoa(client_id + ':' + secret);
+  // const expired = current_auth.expires_at - Date.now() <= 10*1000
+  // if(!expired)
+  //   return current_auth.latest_auth_response.access_token
+  const response = await fetch(
+    `${endpoint}/v1/oauth2/token`,
+    {
+      method: 'post',
+      body: 'grant_type=client_credentials',
+      headers: {
+        Authorization: `Basic ${auth}`,
+      },
+    }
+  );
+  await throw_bad_response(response);
+  const jsonData = await response.json()
+  // current_auth.latest_auth_response = jsonData
+  return {
+    endpoint,
+    access_token: jsonData.access_token
+  }
+}
+/**
+ * make a request, taking into account auth and endpoints for test and prod
+ * @param {Config} config
+ * @param {string} path relative path, i.e `v2/checkout/orders/..`
+ * @param {RequestInit} init
+ */
+export const fetch_with_auth = async (config, path, init={}) => {
+  const { access_token, endpoint } = await getAccessToken(config);
+  return fetch(
+    `${endpoint}/${path}`, {
+      ...init,
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${access_token}`,
+      },
+    }
+  );
+}

package/index.js ADDED Viewed

	@@ -0,0 +1 @@
1	+ export * from './adapter.js'

package/package.json ADDED Viewed

@@ -0,0 +1,34 @@
+{
+  "name": "@storecraft/payments-paypal",
+  "version": "1.0.0",
+  "description": "Official Paypal integration with Storecraft",
+  "license": "MIT",
+  "author": "Tomer Shalev (https://github.com/store-craft)",
+  "homepage": "https://github.com/store-craft/storecraft",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/store-craft/storecraft.git",
+    "directory": "packages/payments-paypal"
+  },
+  "keywords": [
+    "commerce",
+    "dashboard",
+    "code",
+    "storecraft"
+  ],
+  "type": "module",
+  "main": "index.js",
+  "types": "./types.public.d.ts",
+  "scripts": {
+    "payments-paypal:test": "uvu -c",
+    "payments-paypal:publish": "npm publish --access public"
+  },
+  "dependencies": {
+  },
+  "devDependencies": {
+    "@storecraft/core": "^1.0.0",
+    "@types/node": "^20.11.0",
+    "uvu": "^0.5.6",
+    "dotenv": "^16.3.1"
+  }
+}

package/tests/storage.test.js ADDED Viewed

@@ -0,0 +1,11 @@
+import 'dotenv/config';
+import { test } from 'uvu';
+import * as assert from 'uvu/assert';
+test('todo', async () => {
+  assert.ok(true, 'todo')
+});
+test.run();

package/tsconfig.json ADDED Viewed

@@ -0,0 +1,14 @@
+{
+  "compileOnSave": false,
+  "compilerOptions": {
+    "noEmit": true,
+    "allowJs": true,
+    "checkJs": true,
+    "target": "ESNext",
+    "resolveJsonModule": true,
+    "moduleResolution": "NodeNext",
+    "module": "NodeNext",
+    "composite": true,
+  },
+  "include": ["*", "*/*", "src/*"]
+}