@storecraft/sdk 1.0.12 → 1.0.14

package/index.js

@@ -1,6 +1,5 @@
 /**
  * @import { StorecraftSDKConfig } from './types.js'
- * @import { App } from '@storecraft/core'
  */
 import Auth from './src/auth.js'
 import Customers from './src/customers.js'
@@ -22,6 +21,7 @@ import Notifications from './src/notifications.js'
 import Storage from './src/storage.js'
 import AI from './src/ai.js'
 import Search from './src/search.js'
+import { fetchApiWithAuth, fetchOnlyApiResponseWithAuth } from './src/utils.api.fetch.js'
 
 /**
  * @description The official `storecraft` universal **SDK** for `javascript`
@@ -59,6 +59,48 @@ export class StorecraftSDK {
     this.notifications = new Notifications(this);
   }
 
+  /**
+   * @description 
+   * - Prepends `backend` endpoint. 
+   * - Fetches with `authentication` middleware. 
+   * - Refreshed `auth` if needed. 
+   * - Throws a `json` representation of the `error`, 
+   * if the request is `bad`
+   * 
+   * @template {any} [R=any]
+   * 
+   * @param {string} path relative path in api
+   * @param {RequestInit} [init] request `init` type
+   * @param {URLSearchParams} [query] url search params
+   * 
+   * @throws {error}
+   * 
+   * @returns {Promise<R>}
+   */   
+  fetchApiWithAuth = (path, init, query) => {
+    return fetchApiWithAuth(
+      this, path, init, query
+    )
+  }
+
+  /**
+   * @description 
+   * - Prepends `backend` endpoint. 
+   * - Fetches with `authentication` middleware. 
+   * - Refreshed `auth` if needed. 
+   * 
+   * @param {string} path relative path in api
+   * @param {RequestInit} [init] request `init` type
+   * @param {URLSearchParams} [query] url search params
+   * 
+   * @returns {Promise<Response>}
+   */   
+  fetchOnlyApiResponseWithAuth = (path, init, query) => {
+    return fetchOnlyApiResponseWithAuth(
+      this, path, init, query
+    )
+  }
+
   /**
    * @param {StorecraftSDKConfig} [config] 
    */  

package/jsconfig.json

@@ -1,6 +1,8 @@
 {
   "compilerOptions": {
     "checkJs": true,
+    "allowJs": true,
+    "maxNodeModuleJsDepth": 100,
     "target": "ESNext",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storecraft/sdk",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "Official storecraft Universal Javascript SDK",
   "license": "MIT",
   "author": "Tomer Shalev (https://github.com/store-craft)",

package/src/ai.js

@@ -2,16 +2,21 @@
  * @import { 
  *  AgentRunParameters, AgentRunResponse 
  * } from '@storecraft/core/ai/agents/types.js'
+ * @import {
+ *  HEADER_STORECRAFT_THREAD_ID_LITERAL
+ * } from '@storecraft/core/rest/con.ai.routes.js'
  * @import { content } from '@storecraft/core/ai/types.public.js'
  */
 
-import { HEADER_STORECRAFT_THREAD_ID } from '@storecraft/core/rest/con.ai.routes.js';
 import { StorecraftSDK } from '../index.js'
 import { url } from './utils.api.fetch.js';
 
+const HEADER_STORECRAFT_THREAD_ID = /** @satisfies {HEADER_STORECRAFT_THREAD_ID_LITERAL} */ (
+  'X-STORECRAFT-THREAD-ID'
+);
+
 /**
  * @description **AI**
- * 
  */
 export default class AI {
 
@@ -26,12 +31,13 @@ export default class AI {
   /**
    * @description Speak with the main `storecraft` agent sync. It is
    * recommended to use the streamed version {@link streamSpeak}
+   * @param {string} agent_handle agent identifier
    * @param {AgentRunParameters} params 
    * @returns {Promise<AgentRunResponse>}
    */
-  speak = async (params) => {
+  speak = async (agent_handle, params) => {
     const response = await fetch(
-      url(this.sdk.config, 'ai/agent/run'),
+      url(this.sdk.config, `ai/agents/${agent_handle}/run`),
       {
         method: 'post',
         body: JSON.stringify(params),
@@ -46,11 +52,12 @@ export default class AI {
 
   /**
    * @description Stream Speak with the main `storecraft` agent via Server-Sent Events
+   * @param {string} agent_handle agent identifier
    * @param {AgentRunParameters} params 
    */
-  streamSpeak = async function(params) {
+  streamSpeak = async function(agent_handle, params) {
     const response = await fetch(
-      url(this.sdk.config, 'ai/agent/stream'),
+      url(this.sdk.config, `ai/agents/${agent_handle}/stream`),
       {
         method: 'post',
         body: JSON.stringify(params),
@@ -60,7 +67,9 @@ export default class AI {
       }
     );
 
-    const threadId = response.headers.get(HEADER_STORECRAFT_THREAD_ID ?? 'X-Storecraft-Thread-Id');
+    const threadId = response.headers.get(
+      HEADER_STORECRAFT_THREAD_ID ?? 'X-Storecraft-Thread-Id'
+    );
 
     if(!threadId) {
       throw new Error(
@@ -93,7 +102,6 @@ const sleep = (ms=100) => {
  */
 const StreamSpeakGenerator = async function *(stream) {
   for await (const sse of SSEGenerator(stream)) {
-    await sleep(50);
     yield ( /** @type {content} */ (JSON.parse(sse.data)));
   }
 }

package/src/auth.js

@@ -1,19 +1,16 @@
 /**
  * @import {
- *  ApiAuthChangePasswordType, ApiAuthResult, ApiAuthSigninType, ApiAuthSignupType, 
- *  ApiKeyResult, ApiQuery, AuthUserType, error,
- OAuthProvider,
- OAuthProviderCreateURIParams,
- OAuthProviderCreateURIResponse,
- OAuthProvidersList,
- SignWithOAuthProviderParams
+ *  ApiAuthChangePasswordType, ApiAuthResult, ApiAuthSigninType, 
+ *  ApiAuthSignupType, ApiKeyResult, ApiQuery, AuthUserType, error, 
+ *  OAuthProvider, OAuthProviderCreateURIParams, 
+ *  OAuthProviderCreateURIResponse, SignWithOAuthProviderParams
  * } from '@storecraft/core/api'
  * @import { SdkConfigAuth } from '../types.js';
  */
 
 import { api_query_to_searchparams } from '@storecraft/core/api/utils.query.js';
 import { StorecraftSDK } from '../index.js';
-import { fetchApiWithAuth, url } from './utils.api.fetch.js';
+import { count_query_of_resource, fetchApiWithAuth, url } from './utils.api.fetch.js';
 import { assert } from './utils.functional.js';
 
 
@@ -381,7 +378,7 @@ export default class Auth {
       this.#sdk,
       '/auth/apikeys',
       {
-        method: 'post'
+        method: 'post',
       }
     );
 
@@ -424,10 +421,7 @@ export default class Auth {
   }
 
   /**
-   * 
-   * 
    * @param {ApiQuery<AuthUserType>} query
-   * 
    */
   list_auth_users = async (query) => {
     const sq = api_query_to_searchparams(query);
@@ -442,6 +436,18 @@ export default class Auth {
     return items;
   }
 
+  /**
+   * @param {ApiQuery<AuthUserType>} query
+   */
+  count_auth_users_query = async (query) => {
+    const sq = api_query_to_searchparams(query);
+    return count_query_of_resource(
+      this.#sdk,
+      `/auth/users`,
+      query
+    )
+  }
+
 
   list_api_keys_auth_users = async () => {
 
@@ -458,15 +464,15 @@ export default class Auth {
   }
 
   identity_providers_list = async () => {
-      /** @type {OAuthProvider[]} */
-      const items = await fetchApiWithAuth(
-        this.#sdk,
-        '/auth/identity-providers',
-        {
-          method: 'get'
-        }
-      );
-      return items;
+    /** @type {OAuthProvider[]} */
+    const items = await fetchApiWithAuth(
+      this.#sdk,
+      '/auth/identity-providers',
+      {
+        method: 'get'
+      }
+    );
+    return items;
   }
 
   /**
@@ -478,7 +484,7 @@ export default class Auth {
     /** @type {OAuthProviderCreateURIResponse} */
     const result = await fetchApiWithAuth(
       this.#sdk,
-      '/auth/identity-providers/create_authorization_uri',
+      '/auth/identity-providers/create-authorization-uri',
       {
         method: 'post',
         body: JSON.stringify(params),

package/src/collections.js

@@ -1,9 +1,13 @@
 /**
- * @import { CollectionType, CollectionTypeUpsert } from '@storecraft/core/api'
+ * @import { 
+ *  ApiQuery, CollectionType, CollectionTypeUpsert, ProductType, VariantType 
+ * } from '@storecraft/core/api'
  */
 import { StorecraftSDK } from '../index.js'
-import { collection_base, fetchApiWithAuth } from './utils.api.fetch.js';
-import { filter_fields, filter_unused } from './utils.functional.js';
+import { 
+  collection_base, count_query_of_resource, 
+  fetchApiWithAuth, list_from_collection_resource 
+} from './utils.api.fetch.js';
 
 /**
  * @description Base `collections` **CRUD**
@@ -41,34 +45,55 @@ export default class Collections extends collection_base {
     return result
   }
 
-  // /**
-  //  * Add tags in bulk to products in collection
-  //  * @param {string} colId 
-  //  * @param {string[]} tags 
-  //  * @param {boolean} add true for add false for remove 
-  //  */
-  // bulkAddRemoveTags = async (colId, tags, add=true) => {
+  /**
+   * @description List all the tags of products in a collection, 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
+   * 
+   * @param {string} id_or_handle Collection `id` or `handle`
+   * @return {Promise<string[]>} List of tags
+   */
+  list_used_products_tags = async (id_or_handle) => {
+    const result = await fetchApiWithAuth(
+      this.sdk,
+      `collections/${id_or_handle}/products/used_tags`,
+      {
+        method: 'get'
+      }
+    );
 
-  //   // first get all products in collection
-  //   const tag_all = tags ?? []
-  //   const tag_all_prefixed = tag_all.map(t => `tag:${t}`)
-  //   const tag_vs = tag_all.map(it => it.split('_').pop())
+    return result
+  }
 
-  //   var products = await this.context.products.list([`col:${colId}`], 10000)
-  //   // console.log('products ', products)
-  //   // console.log('colId ', colId)
-  //   const batch = writeBatch(this.context.firebase.db)
-  //   products.forEach(it => {
-  //     const ref = doc(this.context.firebase.db, 'products', it[0])
-  //     batch.update(ref, { 
-  //       tags : add ? arrayUnion(...tags) : arrayRemove(...tags),
-  //       search : add ? arrayUnion(...tag_all, ...tag_all_prefixed, ...tag_vs) : 
-  //                      arrayRemove(...tag_all, ...tag_all_prefixed, ...tag_vs),
-  //       updatedAt : Date.now()
-  //     })
-  //   })
-  //   await batch.commit()
+  /**
+   * @description Query the `products` in a collection
+   * 
+   * @param {string} id_or_handle Collection `id` or `handle`
+   * @param {ApiQuery<(ProductType | VariantType)>} query query
+   * @return {Promise<(ProductType | VariantType)[]>} List of products in collection
+   */
+  query_collection_products = async (id_or_handle, query) => {
+    const result = list_from_collection_resource(
+      this.sdk,
+      `collections/${id_or_handle}/products`,
+      query
+    );
+    return result
+  }
 
-  // }
+  /**
+   * @description Count the number of `products` in a collection by a query
+   * 
+   * @param {string} id_or_handle Collection `id` or `handle`
+   * @param {ApiQuery<(ProductType | VariantType)>} query query
+   * @return {Promise<number>} count
+   */
+  count_collection_products_query = async (id_or_handle, query) => {
+    return count_query_of_resource(
+      this.sdk,
+      `collections/${id_or_handle}/products`,
+      query
+    );
+  }
 
 }

package/src/customers.js

@@ -1,8 +1,13 @@
 /**
- * @import { CustomerType, CustomerTypeUpsert } from '@storecraft/core/api'
+ * @import { 
+ *  ApiQuery, CustomerType, CustomerTypeUpsert, OrderData 
+ * } from '@storecraft/core/api'
  */
 import { StorecraftSDK } from '../index.js'
-import { collection_base } from './utils.api.fetch.js';
+import { 
+  collection_base, count_query_of_resource, 
+  list_from_collection_resource 
+} from './utils.api.fetch.js';
 
 /**
  * @description Base `customers` **CRUD**
@@ -18,4 +23,37 @@ export default class Customers extends collection_base {
   constructor(sdk) {
     super(sdk, 'customers');
   }
+
+  /**
+   * @description Query customer orders, this is only available to admin and 
+   * the customer (with auth token)
+   * 
+   * @param {string} id_or_handle customer `id` or `handle` or `email`
+   * @param {ApiQuery<OrderData>} query query
+   * @return {Promise<OrderData[]>} List of orders of customer
+   */
+  query_customer_orders = async (id_or_handle, query) => {
+    const result = list_from_collection_resource(
+      this.sdk,
+      `customers/${id_or_handle}/orders`,
+      query
+    );
+    return result
+  }
+
+  /**
+   * @description Count the number of orders of a specific
+   * customer with a query
+   * 
+   * @param {string} id_or_handle customer `id` or `handle` or `email`
+   * @param {ApiQuery<OrderData>} query query
+   * @return {Promise<number>} count
+   */
+  count_customer_orders_query = async (id_or_handle, query) => {
+    return count_query_of_resource(
+      this.sdk,
+      `customers/${id_or_handle}/orders`,
+      query
+    );
+  }
 }

package/src/discounts.js

@@ -1,8 +1,16 @@
 /**
- * @import { DiscountType, DiscountTypeUpsert } from '@storecraft/core/api'
+ * @import { 
+ *  ApiQuery, DiscountType, DiscountTypeUpsert, 
+ ProductType,
+ VariantType
+ * } from '@storecraft/core/api'
  */
 import { StorecraftSDK } from '../index.js'
-import { collection_base } from './utils.api.fetch.js';
+import { 
+  collection_base, count_query_of_resource, 
+  fetchApiWithAuth, 
+  list_from_collection_resource 
+} from './utils.api.fetch.js';
 
 /**
  * @description Base `discounts` **CRUD**
@@ -19,4 +27,57 @@ export default class Discounts extends collection_base {
     super(sdk, 'discounts');
   }
 
+  /**
+   * @description Each discount has eligible products, 
+   * you can query and filter these products by discount
+   * 
+   * @param {string} id_or_handle discount `id` or `handle`
+   * @param {ApiQuery<ProductType | VariantType>} query query
+   * @return {Promise<(ProductType | VariantType)[]>} List of discounts
+   */
+  query_discount_products = async (id_or_handle, query) => {
+    const result = list_from_collection_resource(
+      this.sdk,
+      `discounts/${id_or_handle}/products`,
+      query
+    );
+    return result;
+  }
+
+  /**
+   * @description Each discount has eligible products, 
+   * you can count the query products by discount
+   * 
+   * @param {string} id_or_handle discount `id` or `handle`
+   * @param {ApiQuery<ProductType | VariantType>} query query
+   * @return {Promise<number>} count
+   */
+  count_discount_products_query = async (id_or_handle, query) => {
+    return count_query_of_resource(
+      this.sdk,
+      `discounts/${id_or_handle}/products`,
+      query
+    );
+  }
+
+  /**
+   * @description List all the tags of products in a collection, 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
+   * 
+   * @param {string} id_or_handle Discount `id` or `handle`
+   * @return {Promise<string[]>} List of tags
+   */
+  list_used_discount_products_tags = async (id_or_handle) => {
+    const result = await fetchApiWithAuth(
+      this.sdk,
+      `discounts/${id_or_handle}/products/used_tags`,
+      {
+        method: 'get'
+      }
+    );
+
+    return result
+  }
+
 }

package/src/payments.js

@@ -3,7 +3,8 @@
  */
 import { StorecraftSDK } from '../index.js'
 import { 
-  fetchApiWithAuth, get_from_collection_resource, list_from_collection_resource 
+  fetchApiWithAuth, get_from_collection_resource, 
+  list_from_collection_resource 
 } from './utils.api.fetch.js';
 
 /**

package/src/products.js

@@ -3,7 +3,7 @@
  */
 import { StorecraftSDK } from '../index.js'
 import { 
-  collection_base, fetchOnlyApiResponseWithAuth 
+  collection_base, fetchApiWithAuth, fetchOnlyApiResponseWithAuth 
 } from './utils.api.fetch.js';
 
 /**
@@ -21,6 +21,26 @@ export default class Products extends collection_base {
     super(sdk, 'products');
   }
 
+  /**
+   * @description List all of the tags of all the products deduped, 
+   * 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 () => {
+    const result = await fetchApiWithAuth(
+      this.sdk,
+      `products/used_tags`,
+      {
+        method: 'get'
+      }
+    );
+
+    return result
+  }
+
   /**
    * 
    * Change stock quantity of a `product` by a delta difference

package/src/search.js

@@ -1,7 +1,4 @@
 /**
- * @import { 
- *  AgentRunParameters, AgentRunResponse 
- * } from '@storecraft/core/ai/agents/types.js'
  * @import { 
  *  ApiQuery, QuickSearchResult, SimilaritySearchInput, SimilaritySearchResult 
  * } from '@storecraft/core/api'
@@ -9,9 +6,8 @@
 
 import { 
   api_query_to_searchparams, object_to_search_params, 
-  parse_query, string_array_to_string 
+  string_array_to_string 
 } from '@storecraft/core/api/utils.query.js';
-import { HEADER_STORECRAFT_THREAD_ID } from '@storecraft/core/rest/con.ai.routes.js';
 import { StorecraftSDK } from '../index.js'
 import { fetchApiWithAuth, url } from './utils.api.fetch.js';
 

package/src/storage.js

@@ -1,6 +1,5 @@
 /**
  * @import { StorageFeatures, StorageSignedOperation } from '@storecraft/core/storage'
- * @import { error } from '@storecraft/core/api'
  */
 
 import { StorecraftSDK } from '../index.js'
@@ -190,30 +189,35 @@ export default class Storage {
    * - 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 {boolean} isImage 
+   * @param {IS_IMAGE} [isImage=true]
+   * @returns {Promise<IS_IMAGE extends true ? string : any>}
    */
-  getSource = async (url, isImage=true) => {
+  getSource = async (url, isImage=(/** @type {IS_IMAGE} */ (true))) => {
     try {
 
       const is_storage = url.startsWith('storage://');
 
       // if we havent found a driver, rturn the url
       if(!is_storage)
-        return url;
+        return /** @type {IS_IMAGE extends true ? string : any} */(url);
 
       const key = url.split('storage://').at(-1);
       const blob = await this.getBlob(key);
 
-      if(isImage)
-        return URL.createObjectURL(blob)
+      if(isImage) {
+        return /** @type {IS_IMAGE extends true ? string : any} */ (
+          URL.createObjectURL(blob)
+        )
+      }
       else
         return blob.text().then(JSON.parse)    
     } catch(e) {
       console.log(e)
     }
 
-    return url;
+    return /** @type {IS_IMAGE extends true ? string : any} */ (url);
   }
 
 

package/src/utils.api.fetch.js

@@ -6,7 +6,6 @@
 import { 
   api_query_to_searchparams 
 } from '@storecraft/core/api/utils.query.js';
-import { assert } from './utils.functional.js';
 
 
 /**
@@ -43,7 +42,9 @@ export const url = (config, path, query) => {
  * 
  * @returns {Promise<Response>}
  */ 
-export const fetchOnlyApiResponseWithAuth = async (sdk, path, init={}, query=undefined) => {
+export const fetchOnlyApiResponseWithAuth = async (
+  sdk, path, init={}, query=undefined
+) => {
 
   const auth_token = await sdk.auth.working_auth_token();
   const auth_header_value = (
@@ -63,12 +64,6 @@ export const fetchOnlyApiResponseWithAuth = async (sdk, path, init={}, query=und
   );
 
   return response;
-
-  // const auth_problem = response.status >= 400 && response.status < 500;
-
-  // if(auth_problem) {
-
-  // }
 }
 
 
@@ -80,7 +75,7 @@ export const fetchOnlyApiResponseWithAuth = async (sdk, path, init={}, query=und
  * - Throws a `json` representation of the `error`, 
  * if the request is `bad`
  * 
- * @template {any} R
+ * @template {any} [R=any]
  * 
  * @param {StorecraftSDK} sdk
  * @param {string} path relative path in api
@@ -91,7 +86,9 @@ export const fetchOnlyApiResponseWithAuth = async (sdk, path, init={}, query=und
  * 
  * @returns {Promise<R>}
  */ 
-export const fetchApiWithAuth = async (sdk, path, init={}, query=undefined) => {
+export const fetchApiWithAuth = async (
+  sdk, path, init={}, query=undefined
+) => {
 
   const response = await fetchOnlyApiResponseWithAuth(
     sdk, path, init, query
@@ -163,6 +160,24 @@ export async function upsert_to_collection_resource(sdk, resource, item) {
   );
 }
 
+/**
+ * @description Count the number of items in a query
+ * @template G
+ * @param {StorecraftSDK} sdk
+ * @param {string} resource base path of resource
+ * @param {ApiQuery<G>} [query] the query
+ * @returns {Promise<number>} count
+ */
+export async function count_query_of_resource(sdk, resource, query) {
+  const sq = api_query_to_searchparams(query);
+  return fetchApiWithAuth(
+    sdk, 
+    `${resource}/count_query?${sq.toString()}`,
+    {
+      method: 'get',
+    }
+  ).then((result) => Number(result.count));
+}
 
 /**
  * 
@@ -230,7 +245,7 @@ export class collection_base {
   /**
    * 
    * @param {StorecraftSDK} sdk storecraft sdk
-   * @param {string} base_name base name of resource type
+   * @param {string} base_name base path of resource type
    */
   constructor(sdk, base_name) {
     this.#sdk = sdk;
@@ -272,16 +287,21 @@ export class collection_base {
   }
 
   /**
-   * 
    * @param {ApiQuery<G>} query Query object
-   * 
-   * 
    * @returns {Promise<G[]>}
    */
   async list(query) {
     return list_from_collection_resource(this.sdk, this.base_name, query);
   }
 
+  /**
+   * @description Count the number of items in a query
+   * @param {ApiQuery<G>} query Query object
+   */
+  async count_query(query) {
+    return count_query_of_resource(this.sdk, this.base_name, query);
+  }
+
   get base_name() {
     return this.#base_name;
   }