@storecraft/payments-paypal 1.0.9 → 1.0.11

package/README.md

@@ -19,13 +19,13 @@ npm i @storecraft/payments-paypal
 
 ## Howto
 
-```js
-import { PayPal } from '@storecraft/payments-paypal';
+```ts
+import { PayPal, Config } from '@storecraft/payments-paypal';
 
-const config = {
+const config: Config = {
   env: 'prod',
-  client_id: '<get-from-your-paypal-dashboard>',
-  secret: '<get-from-your-paypal-dashboard>',
+  client_id: process.env.PAYPAL_CLIENT_ID,
+  secret: env.process.PAYPAL_SECRET,
   currency_code: 'USD',
   intent_on_checkout: 'AUTHORIZE'
 }
@@ -48,13 +48,7 @@ const app = new App(config)
 .withStorage(new GoogleStorage())
 .withPaymentGateways(
   {
-    'paypal_standard_prod': new Paypal(
-      { 
-        client_id: process.env.PAYPAL_CLIENT_ID, 
-        secret: process.env.PAYPAL_SECRET, 
-        env: 'prod' 
-      }
-    ),
+    'paypal_standard_prod': new Paypal() // config can be inferred from env variables
   }
 );
 

package/adapter.html.js

@@ -1,3 +1,7 @@
+/**
+ * @import { Config } from './types.public.js'
+ * @import { OrderData } from '@storecraft/core/api'
+*/
 /**
  * 
  * @description Official PayPal UI integration with `storecraft`.
@@ -10,8 +14,8 @@
  * - Expiry date: 12/2027
  * - CVC code: 897
  * 
- * @param {import("./types.public.d.ts").Config} config 
- * @param {Partial<import("@storecraft/core/api").OrderData>} order_data 
+ * @param {Config} config 
+ * @param {Partial<OrderData>} order_data 
  */
 export default function html_buy_ui(config, order_data) {
   const orderData = order_data?.payment_gateway?.on_checkout_create;

package/adapter.js

@@ -1,3 +1,10 @@
+/**
+ * @import { Config } from './types.public.js'
+ * @import { ENV } from '@storecraft/core';
+ * @import { OrderData, PaymentGatewayStatus } from '@storecraft/core/api'
+ * @import { payment_gateway } from '@storecraft/core/payments'
+ * @import { paypal_order, paypal_order_request } from './types.private.js'
+*/
 import { 
   CheckoutStatusEnum, PaymentOptionsEnum 
 } from '@storecraft/core/api/types.api.enums.js';
@@ -6,44 +13,58 @@ import { StorecraftError } from '@storecraft/core/api/utils.func.js';
 import html_buy_ui from './adapter.html.js';
 
 /**
- * @typedef {import('./types.private.d.ts').paypal_order} CreateResult
- * @typedef {import('@storecraft/core/api').PaymentGatewayStatus} PaymentGatewayStatus
- * @typedef {import('@storecraft/core/api').CheckoutStatusEnum} CheckoutStatusOptions
- * @typedef {import('@storecraft/core/api').OrderData} OrderData
- * @typedef {import('./types.public.d.ts').Config} Config
- * @typedef {import('@storecraft/core/payments').payment_gateway<Config, CreateResult>} payment_gateway
+ * @typedef {paypal_order} CreateResult
+ * @typedef {payment_gateway<Config, CreateResult>} Impl
  */
 
+
 /**
- * @implements {payment_gateway}
- * 
  * @description **Paypal Payment** gateway (https://developer.paypal.com/docs/checkout/)
- */
+ * 
+ * @implements {Impl}
+*/
 export class Paypal {
   
-  /** @type {Config} */ #_config;
+  /** @satisfies {ENV<Config>} */
+  static EnvConfigProd = /** @type{const} */ ({
+    client_id: `PAYPAL_CLIENT_ID_PROD`,
+    secret: 'PAYPAL_SECRET_PROD',
+  });
+
+  /** @satisfies {ENV<Config>} */
+  static EnvConfigTest = /** @type{const} */ ({
+    client_id: `PAYPAL_CLIENT_ID_TEST`,
+    secret: 'PAYPAL_SECRET_TEST',
+  });
 
-  /**
-   * 
-   * @param {Config} config 
-   */
-  constructor(config) {
-    this.#_config = this.#validate_and_resolve_config(config);
-  }
+  /** @type {Config} */ #_config;
 
   /**
    * 
    * @param {Config} config 
    */
-  #validate_and_resolve_config(config) {
-    config = {
+  constructor(config={}) {
+    // this.#_config = this.#validate_and_resolve_config(config);
+    this.#_config = {
       default_currency_code: 'USD',
       env: 'prod',
       intent_on_checkout: 'AUTHORIZE',
       ...config,
     }
+  }
 
-    const is_valid = config.client_id && config.secret;
+  /** @type {Impl["onInit"]} */
+  onInit = (app) => {
+    const is_prod = Boolean(this.config.env==='prod');
+    this.config.client_id ??= app.platform.env[
+      is_prod ? Paypal.EnvConfigProd.client_id : Paypal.EnvConfigTest.client_id
+    ] ?? 'PAYPAL_CLIENT_ID';
+
+    this.config.secret ??= app.platform.env[
+      is_prod ? Paypal.EnvConfigProd.secret : Paypal.EnvConfigTest.secret
+    ] ?? 'PAYPAL_SECRET';
+
+    const is_valid = this.config.client_id && this.config.secret;
 
     if(!is_valid) {
       throw new StorecraftError(
@@ -51,8 +72,6 @@ export class Paypal {
         Missing client_id or secret`
       )
     }
-
-    return config;
   }
 
   get info() {
@@ -91,7 +110,7 @@ export class Paypal {
 
   /**
    * 
-   * @type {payment_gateway["invokeAction"]}
+   * @type {Impl["invokeAction"]}
    */
   invokeAction(action_handle) {
     switch (action_handle) {
@@ -108,11 +127,7 @@ export class Paypal {
   }
 
   /**
-   * @description (Optional) buy link ui
-   * 
-   * @param {Partial<OrderData>} order 
-   * 
-   * @return {Promise<string>} html 
+   * @type {Impl["onBuyLinkHtml"]}
    */
   async onBuyLinkHtml(order) {
 
@@ -124,14 +139,12 @@ export class Paypal {
   /**
    * @description TODO: the user prefers to capture intent instead
    * 
-   * @param {OrderData} order 
-   * 
-   * @return {Promise<CreateResult>}
+   * @type {Impl["onCheckoutCreate"]}
    */
   async onCheckoutCreate(order) {
     const { default_currency_code: currency_code, intent_on_checkout } = this.config; 
 
-    /** @type {import('./types.private.js').paypal_order_request} */
+    /** @type {paypal_order_request} */
     const body = {
       intent: intent_on_checkout==='AUTHORIZE' ? 'AUTHORIZE' : 'CAPTURE',
       purchase_units: [
@@ -163,9 +176,7 @@ export class Paypal {
   /**
    * @description todo: logic for if user wanted capture at approval
    * 
-   * @param {CreateResult} create_result 
-   * 
-   * @return {ReturnType<payment_gateway["onCheckoutComplete"]>}  
+   * @type {Impl["onCheckoutComplete"]}
    */
   async onCheckoutComplete(create_result) {
     // the url based on authorize or capture intent
@@ -179,7 +190,7 @@ export class Paypal {
 
     await throw_bad_response(response);
     
-    /** @type {import('./types.private.js').paypal_order} */
+    /** @type {paypal_order} */
     const payload = await response.json();
     
     let status;
@@ -211,11 +222,7 @@ export class Paypal {
   /**
    * @description Fetch the order and analyze it's status
    * 
-   * 
-   * @param {CreateResult} create_result 
-   * 
-   * 
-   * @returns {Promise<PaymentGatewayStatus>}
+   * @type {Impl["status"]}
    */
   async status(create_result) {
     const o = await this.retrieve_order(create_result);
@@ -286,9 +293,10 @@ export class Paypal {
   /**
    * @description [https://developer.paypal.com/api/rest/webhooks/rest/](https://developer.paypal.com/api/rest/webhooks/rest/)
    * 
-   * @param {Request} request 
+   * @type {Impl["webhook"]}
    */
   async webhook(request) {
+    throw new Error('Paypal:: webhook - not supported yet !');
     return null;
   }
 
@@ -297,7 +305,7 @@ export class Paypal {
    * 
    * @param {CreateResult} create_result first create result, holds paypal id
    * 
-   * @return {Promise<import('./types.private.js').paypal_order>} 
+   * @return {Promise<paypal_order>} 
    */
   retrieve_order = async (create_result) => {
     const response = await fetch_with_auth(
@@ -308,7 +316,7 @@ export class Paypal {
 
     await throw_bad_response(response);
 
-    /** @type {import('./types.private.js').paypal_order} */
+    /** @type {paypal_order} */
     const jsonData = await response.json();
     return jsonData;
   }  

package/adapter.utils.js

@@ -1,13 +1,12 @@
+/**
+ * @import { Config } from './types.public.js'
+*/
 
 export const endpoints = {
   test: 'https://api-m.sandbox.paypal.com',
   prod: 'https://api-m.paypal.com'
 }
 
-/**
- * @typedef {import("./types.public.d.ts").Config} Config
- */
-
 /**
  * @param {Config} config 
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storecraft/payments-paypal",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "Official Paypal integration with Storecraft",
   "license": "MIT",
   "author": "Tomer Shalev (https://github.com/store-craft)",

package/types.public.d.ts

@@ -6,26 +6,33 @@ export { Paypal } from './adapter.js';
 export type Config = {
   /**
    * @description default currency code
+   * @default 'USD'
    */
   default_currency_code?: string;
 
   /**
    * @description the environment
+   * @default 'prod'
    */
-  env: 'prod' | 'test';
+  env?: 'prod' | 'test';
 
   /**
-   * @description private client id
+   * @description private client id. If missing, 
+   * - if `env===prod` -> will be inferred from env variable `PAYPAL_CLIENT_ID_PROD` or `PAYPAL_CLIENT_ID`
+   * - if `env===test` -> will be inferred from env variable `PAYPAL_CLIENT_ID_TEST` or `PAYPAL_CLIENT_ID`
    */
-  client_id: string;
+  client_id?: string;
 
   /**
-   * @description private secret
+   * @description private secret. If missing, 
+   * - if `env===prod` -> will be inferred from env variable `PAYPAL_SECRET_PROD` or `PAYPAL_SECRET`
+   * - if `env===test` -> will be inferred from env variable `PAYPAL_SECRET_TEST` or `PAYPAL_SECRET`
    */
-  secret: string;
+  secret?: string;
   
   /**
    * @description default intent to `authorize` or `capture` on order creation
+   * @default 'AUTHORIZE'
    */
   intent_on_checkout?: 'AUTHORIZE' | 'CAPTURE';
 }