@storecraft/sdk 1.0.14 → 1.0.16

package/src/email.js

@@ -0,0 +1,67 @@
+/**
+ * @import { 
+ *  MailResponse, SendMailParams, SendMailWithTemplateParams, templates_keys, 
+ *  templates_input_types
+ * } from '@storecraft/core/api'
+ */
+
+import { StorecraftSDK } from '../index.js'
+import { fetchApiWithAuth, url } from './utils.api.fetch.js';
+
+/**
+ */
+export default class Email {
+
+  /**
+   * @param {StorecraftSDK} sdk 
+   */
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * @description Send an email to multiple recipients
+   * @param {SendMailParams} params mail parameters
+   * @returns {Promise<MailResponse<any>>}
+   */
+  send = async (params) => {
+    const json = await fetchApiWithAuth(
+      this.sdk,
+      'emails/send',
+      { 
+        method: 'POST',
+        body: JSON.stringify(params),
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      },
+    );
+    return json;
+  }
+
+  /**
+   * @description Send an email to multiple recipients with a template. 
+   * Each template has a `subject`, `html` and `text` body templates, 
+   * that you can configure at the dashboard
+   * @template {templates_keys | string} [HANDLE=keyof templates_input_types]
+   * @param {SendMailWithTemplateParams<HANDLE>} params mail parameters
+   * @returns {Promise<MailResponse<any>>}
+   */
+  sendWithTemplate = async (params) => {
+    const json = await fetchApiWithAuth(
+      this.sdk,
+      'emails/send-with-template',
+      { 
+        method: 'POST',
+        body: JSON.stringify(params),
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      },
+    );
+    return json;
+  }
+
+}
+
+

package/src/images.js

@@ -6,13 +6,11 @@ import { collection_base } from './utils.api.fetch.js';
 
 /**
  * @description Base `images` **CRUD**
- * 
  * @extends {collection_base<ImageTypeUpsert, ImageType>}
  */
 export default class Images extends collection_base {
 
   /**
-   * 
    * @param {StorecraftSDK} sdk 
    */
   constructor(sdk) {

package/src/notifications.js

@@ -1,5 +1,7 @@
 /**
- * @import { NotificationTypeUpsert, NotificationType } from '@storecraft/core/api'
+ * @import { 
+ *  NotificationTypeUpsert, NotificationType 
+ * } from '@storecraft/core/api'
  */
 import { StorecraftSDK } from '../index.js'
 import { 
@@ -14,7 +16,6 @@ import {
 export default class Notifications extends collection_base {
 
   /**
-   * 
    * @param {StorecraftSDK} sdk 
    */
   constructor(sdk) {
@@ -22,7 +23,6 @@ export default class Notifications extends collection_base {
   }
 
   /**
-   * 
    * @param {NotificationTypeUpsert[]} items 
    */
   upsertBulk = items => {

package/src/orders.js

@@ -1,8 +1,9 @@
 /**
- * @import { OrderDataUpsert, OrderData } from '@storecraft/core/api'
+ * @import { OrderDataUpsert, OrderData, ApiQuery } from '@storecraft/core/api'
  */
+import { api_query_to_searchparams } from '@storecraft/core/api/utils.query.js';
 import { StorecraftSDK } from '../index.js'
-import { collection_base } from './utils.api.fetch.js';
+import { collection_base, fetchApiWithAuth } from './utils.api.fetch.js';
 
 /**
  * @description Base `orders` **CRUD**
@@ -12,11 +13,27 @@ import { collection_base } from './utils.api.fetch.js';
 export default class Orders extends collection_base {
 
   /**
-   * 
    * @param {StorecraftSDK} sdk 
    */
   constructor(sdk) {
     super(sdk, 'orders');
   }
 
+  /**
+   * @description List orders of current authenticated user
+   * @param {ApiQuery<OrderData>} [query] 
+   * @returns {Promise<OrderData[]>}
+   */
+  list_my_orders(
+    query={}
+  ) {
+    const sq = api_query_to_searchparams(query);
+    return fetchApiWithAuth(
+      this.sdk, 
+      `${this.base_name}/me?${sq.toString()}`,
+      {
+        method: 'get'
+      }
+    );
+  }
 }

package/src/payments.js

@@ -1,5 +1,7 @@
 /**
- * @import { PaymentGatewayItemGet, PaymentGatewayStatus } from '@storecraft/core/api'
+ * @import { 
+ *  PaymentGatewayItemGet, PaymentGatewayStatus 
+ * } from '@storecraft/core/api'
  */
 import { StorecraftSDK } from '../index.js'
 import { 
@@ -16,7 +18,6 @@ export default class Payments {
   #sdk = undefined;
   
   /**
-   * 
    * @param {StorecraftSDK} sdk 
    */
   constructor(sdk) {
@@ -24,34 +25,29 @@ export default class Payments {
   }
 
   /**
-   * 
    * @param {string} handle payment gateway `handle`
-   * 
-   * 
    * @returns {Promise<PaymentGatewayItemGet>}
    */
   get(handle) {
-    return get_from_collection_resource(this.sdk, 'payments/gateways', handle);
+    return get_from_collection_resource(
+      this.sdk, 'payments/gateways', handle
+    );
   }
 
   /**
-   * 
-   * 
    * @returns {Promise<PaymentGatewayItemGet[]>}
    */
   list() {
-    return list_from_collection_resource(this.sdk, 'payments/gateways');
+    return list_from_collection_resource(
+      this.sdk, 'payments/gateways'
+    );
   }
 
 
   /**
-   * 
    * Consult with the `payment` gateway about the payment
    * status of an `order`.
-   * 
-   * 
    * @param {string} order_id 
-   * 
    * @returns {Promise<PaymentGatewayStatus>}
    */
   paymentStatusOfOrder(order_id) {
@@ -65,15 +61,12 @@ export default class Payments {
   }
   
   /**
-   * 
-   * Invoke a `payment gateway` action on `order`. The list of available actions can be found
-   * using {@link get_from_collection_resource} or {@link paymentStatusOfOrder}
-   * 
-   * 
+   * Invoke a `payment gateway` action on `order`. 
+   * The list of available actions can be found
+   * using {@link get_from_collection_resource} or 
+   * {@link paymentStatusOfOrder}
    * @param {string} action_handle The `action` handle at the gateway
    * @param {string} order_id the `id` of the `order`
-   * 
-   * 
    * @returns {Promise<PaymentGatewayStatus>}
    */
   invokeAction(action_handle, order_id) {
@@ -85,7 +78,42 @@ export default class Payments {
       }
     )
   }
-  
+
+  /**
+   * Get an optional HTML Pay UI of the `payment gateway`
+   * @param {string} order_id the `id` of the `order`
+   * @returns {Promise<string>} `html` of the `payment gateway` UI
+   */
+  getBuyUI(order_id) {
+    return fetchApiWithAuth(
+      this.sdk, 
+      `/payments/buy_ui/${order_id}`,
+      {
+        method: 'get'
+      }
+    )
+  }
+    
+  /**
+   * invoke the webhook endpoint for async payment
+   * @param {string} gateway_handle The handle of the `payment gateway`
+   * @param {any} [body={}] Payload for the gateway webhook. This is specific to the
+   * `payment gateway` and the `webhook` endpoint.
+   * @returns {Promise<string>}
+   */
+  webhook(gateway_handle, body={}) {
+    return fetchApiWithAuth(
+      this.sdk, 
+      `/payments/gateways/${gateway_handle}/webhook`,
+      {
+        method: 'post',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(body)
+      }
+    )
+  }  
 
   get sdk() {
     return this.#sdk;

package/src/posts.js

@@ -12,7 +12,6 @@ import { collection_base } from './utils.api.fetch.js';
 export default class Posts extends collection_base {
 
   /**
-   * 
    * @param {StorecraftSDK} sdk 
    */
   constructor(sdk) {

package/src/products.js

@@ -14,7 +14,6 @@ import {
 export default class Products extends collection_base {
 
   /**
-   * 
    * @param {StorecraftSDK} sdk 
    */
   constructor(sdk) {
@@ -26,7 +25,6 @@ export default class Products extends collection_base {
    * This is helpful for building a filter system in the frontend if 
    * you know in advance all the tags of the products in a collection, 
    * also see the collection confined version db_collections.list_collection_products_tags
-   * 
    * @return {Promise<string[]>} List of tags
    */
   list_used_tags = async () => {
@@ -42,15 +40,14 @@ export default class Products extends collection_base {
   }
 
   /**
-   * 
    * Change stock quantity of a `product` by a delta difference
    * number.
-   * 
    * @param {string} id_or_handle `id` ot `handle`
    * @param {number} howmuch a diff number by how much to update stock
+   * @return {Promise<boolean>} 
    */
   changeStockOfBy = async (id_or_handle, howmuch) => {
-    const response = await fetchOnlyApiResponseWithAuth(
+    const response = await fetchApiWithAuth(
       this.sdk,
       `products/${id_or_handle}?quantityBy=${howmuch}`,
       {
@@ -58,12 +55,11 @@ export default class Products extends collection_base {
       }
     );
 
-    return response.ok;
+    return response;
   }
 
   /**
    * Add `products` to `collection`
-   * 
    * @param {ProductType[]} products 
    * @param {CollectionType} collection 
    */
@@ -78,7 +74,6 @@ export default class Products extends collection_base {
 
   /**
    * Remove `products` from `collection`
-   * 
    * @param {ProductType[]} products 
    * @param {CollectionType} collection 
    */

package/src/search.js

@@ -13,15 +13,12 @@ import { fetchApiWithAuth, url } from './utils.api.fetch.js';
 
 /**
  * @description **Search** API (two options):
- * 
  * - Quick Search across many resources
  * - Similarity search across `discount`, `products`, `collections`, `shipping`
- * 
  */
 export default class Search {
 
   /**
-   * 
    * @param {StorecraftSDK} sdk 
    */
   constructor(sdk) {

package/src/settings.js

@@ -9,11 +9,10 @@ import { collection_base } from './utils.api.fetch.js';
 export default class Settings extends collection_base {
 
   /**
-   * 
    * @param {StorecraftSDK} sdk 
    */
   constructor(sdk) {
-    super(sdk, 'settings');
+    super(sdk, 'reference/settings');
   }
 
 }

package/src/shipping.js

@@ -12,7 +12,6 @@ import { collection_base } from './utils.api.fetch.js';
 export default class Shipping extends collection_base {
 
   /**
-   * 
    * @param {StorecraftSDK} sdk 
    */
   constructor(sdk) {

package/src/statistics.js

@@ -4,7 +4,9 @@
 import { App } from '@storecraft/core';
 import { StorecraftSDK } from '../index.js'
 import { fetchApiWithAuth } from './utils.api.fetch.js';
-import { api_query_to_searchparams } from '@storecraft/core/api/utils.query.js';
+import { 
+  api_query_to_searchparams 
+} from '@storecraft/core/api/utils.query.js';
 
 /**
  * @description statistics endpoint
@@ -12,11 +14,8 @@ import { api_query_to_searchparams } from '@storecraft/core/api/utils.query.js';
 export default class Statistics  {
   /** @type {StorecraftSDK} */
   #sdk;
-  /** @type {Record<string, any>} */
-  #cache = {};
 
   /**
-   * 
    * @param {StorecraftSDK} sdk 
    */
   constructor(sdk) {
@@ -26,54 +25,30 @@ export default class Statistics  {
   get sdk() {
     return this.#sdk;
   }
- 
-  /**
-   * @param {string} key
-   * 
-   *  @returns {boolean} 
-   */
-  isCacheValid = key => {
-    return false;
-    // return this.cache[key] && 
-    // (Date.now()-this.cache[key].updatedAt)<HOUR
-  }
-
-  /**
-   * 
-   * @param {string} key 
-   * @returns {OrdersStatisticsType}
-   */
-  fromCache = (key) => {
-    if(this.isCacheValid(key))
-      return this.#cache[key]
-    return undefined
-  }
-
-  /**
-   * 
-   * @param {string} key 
-   * @param {OrdersStatisticsType} value
-   */
-  putCache = (key, value) => {
-    this.#cache[key] = value
-  }
-
 
   /**
    * @description Load **Orders** `statistics`
-   * 
-   * @param {string | number | Date} [from_day] `ISO` string | `UTC` | `timestamp` | `Date`
-   * @param {string | number | Date} [to_day] `ISO` string | `UTC` | `timestamp` | `Date`
-   * 
+   * @param {string | number | Date} [from_day] 
+   * `ISO` string | `UTC` | `timestamp` | `Date`
+   * @param {string | number | Date} [to_day] 
+   * `ISO` string | `UTC` | `timestamp` | `Date`
    * @returns {Promise<OrdersStatisticsType>}
    */
   orders = async (from_day, to_day) => {
     const search = new URLSearchParams();
     
-    if(from_day)
-      search.set('fromDay', new Date(from_day).toISOString());
-    if(to_day)
-      search.set('toDay', new Date(to_day).toISOString());
+    if(from_day) {
+      search.set(
+        'fromDay', 
+        new Date(from_day).toISOString()
+      );
+    }
+    if(to_day) {
+      search.set(
+        'toDay', 
+        new Date(to_day).toISOString()
+      );
+    }
 
     return fetchApiWithAuth(
       this.sdk, 
@@ -83,14 +58,9 @@ export default class Statistics  {
 
   /**
    * @description Load **count** `statistics`
-   * 
    * @param {keyof App["db"]["resources"]} table 
    * @param {ApiQuery} [query]
-   * 
-   * 
    * @returns {Promise<number>}
-   * 
-   * 
    * @throws
    */
   countOf = async (table, query) => {

package/src/storage.js

@@ -1,19 +1,18 @@
 /**
- * @import { StorageFeatures, StorageSignedOperation } from '@storecraft/core/storage'
+ * @import { 
+ *  StorageFeatures, StorageSignedOperation 
+ * } from '@storecraft/core/storage'
  */
 
 import { StorecraftSDK } from '../index.js'
 import { fetchOnlyApiResponseWithAuth } from './utils.api.fetch.js'
 
 /**
- * 
  * @description `Storecraft` storage service.
- * 
  * Supports:
  * - direct `downloads` / `uploads`
  * - presigned-urls for `download` / `upload` (If supported)
  * - `delete` files
- * 
  */
 export default class Storage {
 
@@ -34,11 +33,8 @@ export default class Storage {
   }
 
   /**
-   * 
    * @description Retrieve the `features` of `storage`, which informs:
    * - Does `storage` supports `pre-signed` urls for `download` / `upload`
-   * 
-   * 
    * @returns {Promise<StorageFeatures>}
    */
   features = async () => {
@@ -75,12 +71,9 @@ export default class Storage {
   
   /**
    * @description Get a blob from `storage` driver with `presigned` urls
-   * 
    * @param {string} key file path key, 
    * examples `image.png`, `collections/thumb.jpeg`
-   * 
    * @return {Promise<Blob>}
-   * 
    * @throws {error}
    */
   getBlobSigned = async (key) => {
@@ -104,7 +97,7 @@ export default class Storage {
       /** @type {StorageSignedOperation} */
       const presigned_req = await r.json();
 
-      const presigned_res = await fetch(
+      const presigned_res = await this.sdk.fetcher(
         presigned_req.url, 
         {
           method: presigned_req.method,
@@ -119,13 +112,11 @@ export default class Storage {
   }
 
   /**
-   * @description Get a blob from `storage` driver, straight download. (Not recommended)
-   * 
+   * @description Get a blob from `storage` driver, 
+   * straight download. (Not recommended)
    * @param {string} key file path key, 
    * examples `image.png`, `collections/thumb.jpeg`
-   * 
    * @return {Promise<Blob>}
-   * 
    * @throws {error}
    */
   getBlobUnsigned = async (key) => {
@@ -137,10 +128,8 @@ export default class Storage {
     );
 
     const ctype = r.headers.get('Content-Type');
-
     if(!r.ok) {
       const error = await r.json();
-
       throw error;
     }
 
@@ -149,12 +138,9 @@ export default class Storage {
 
   /**
    * @description Get a blob from `storage` driver.
-   * 
    * @param {string} key file path key, 
    * examples `image.png`, `collections/thumb.jpeg`
-   * 
    * @return {Promise<Blob>}
-   * 
    * @throws {error}
    */
   getBlob = async (key) => {
@@ -169,32 +155,36 @@ export default class Storage {
 
   /** @param {string} path  */
   getText = (path) => 
-      this.getBlob(path).then(blob => blob.text());
+    this.getBlob(path).then(blob => blob.text());
 
   /** @param {string} path  */
   getJson = (path) => 
-      this.getBlob(path).then(blob => blob.text().then(JSON.parse));
+    this.getBlob(path).then(
+      blob => blob.text().then(JSON.parse)
+    );
 
   /** @param {string} path  */
   getImageObjectURL = (path) => 
-      this.getBlob(path).then(blob => URL.createObjectURL(blob));
+    this.getBlob(path).then(
+      blob => URL.createObjectURL(blob)
+    );
 
   /**
    * @description get file source by inspecting the url:
-   * 
    * - If it starts with `storage://`, then use `backend` 
    * storage service, to download and convert it to encoded 
    * `object-url` for `<img/>`
-   * 
    * - Else. it is assumed to be a public `url`, and will 
    * return the given url.
-   * 
    * @template {false | true} [IS_IMAGE=true]
    * @param {string} url 
    * @param {IS_IMAGE} [isImage=true]
    * @returns {Promise<IS_IMAGE extends true ? string : any>}
    */
-  getSource = async (url, isImage=(/** @type {IS_IMAGE} */ (true))) => {
+  getSource = async (
+    url, 
+    isImage=(/** @type {IS_IMAGE} */ (true))
+  ) => {
     try {
 
       const is_storage = url.startsWith('storage://');
@@ -222,12 +212,13 @@ export default class Storage {
 
 
   /**
-   * @description Put a blob into `storage` driver with `presigned` urls
-   * 
+   * @description Put a blob into `storage` driver 
+   * with `presigned` urls if supported. this means the upload
+   * is offloaded from the backend to the client straight into 
+   * other services that supports it such as s3.
    * @param {string} key file path key, 
    * examples `image.png`, `collections/thumb.jpeg`
    * @param {string | Blob | Uint8Array | ArrayBuffer | File} data 
-   * 
    */
   putBytesSigned = async (key, data) => {
 
@@ -248,7 +239,7 @@ export default class Storage {
     if(ctype === 'application/json') {
       /** @type {StorageSignedOperation} */
       const presigned_req = await r.json();
-      const presigned_res = await fetch(
+      const presigned_res = await this.sdk.fetcher(
         presigned_req.url, 
         {
           method: presigned_req.method,
@@ -264,12 +255,11 @@ export default class Storage {
   }
 
   /**
-   * @description Put a blob into `storage` driver with direct `upload` (Not Recommended)
-   * 
+   * @description Put a blob into `storage` driver with 
+   * direct `upload` (Not Recommended)
    * @param {string} key file path key, 
    * examples `image.png`, `collections/thumb.jpeg`
    * @param {string | Blob | Uint8Array | ArrayBuffer | File} data 
-   * 
    */
   putBytesUnsigned = async (key, data) => {
 
@@ -295,13 +285,10 @@ export default class Storage {
 
   /**
    * @description Put bytes into `storage` driver.
-   * 
    * @param {string} key file path key, 
    * examples `image.png`, `collections/thumb.jpeg`
    * @param {string | Blob | Uint8Array | ArrayBuffer | File} data 
-   * 
    * @return {Promise<boolean>}
-   * 
    * @throws {error}
    */
   putBytes = async (key, data) => {
@@ -316,7 +303,6 @@ export default class Storage {
 
   /**
    * @description Delete a `file` by key
-   * 
    * @param {string} key file path key, 
    * examples `image.png`, `collections/thumb.jpeg`
    */
@@ -327,6 +313,11 @@ export default class Storage {
       { method: 'delete' }
     );
 
+    if(!r.ok) {
+      const error = await r.json();
+      throw error;
+    }
+    
     return r.ok;
   }