@storecraft/sdk 1.0.10 → 1.0.11

package/README.md

@@ -35,6 +35,12 @@ Perform payments `status-check` / `invoke-action`
 #### AI
 Speak with a `storecraft` agent (Supports streaming :))
 
+#### Semantic / Similarity Search
+Search Storecraft with AI for similar `products`, `discounts`, `collections`, `shipping` based on a prompt.
+
+#### Quick Search
+List super lite search results with `id`, `handle`, `title` over most resources 
+
 <hr/>
 
 Start by installing, 

package/index.js

@@ -1,3 +1,7 @@
+/**
+ * @import { StorecraftSDKConfig } from './types.js'
+ * @import { App } from '@storecraft/core'
+ */
 import Auth from './src/auth.js'
 import Customers from './src/customers.js'
 import Tags from './src/tags.js'
@@ -17,24 +21,7 @@ import Settings from './src/settings.js'
 import Notifications from './src/notifications.js'
 import Storage from './src/storage.js'
 import AI from './src/ai.js'
-
-
-/**
- * @typedef {import('@storecraft/core/api').ApiAuthResult |
- *  import('@storecraft/core/api').ApiKeyResult
- * } SdkConfigAuth The `storecraft` **SDK** `auth` config, represents
- * either `apikey` or `jwt` authentication
- * 
- */
-
-
-/**
- * 
- * @typedef {object} StorecraftSDKConfig The `storecraft` **SDK** config
- * @property {string} [endpoint] Endpoint of `backend`
- * @property {SdkConfigAuth} [auth] `auth` info, may be either `apikey` or
- * `jwt` results
- */
+import Search from './src/search.js'
 
 /**
  * @description The official `storecraft` universal **SDK** for `javascript`
@@ -51,9 +38,9 @@ export class StorecraftSDK {
     this.#_config = config;
 
     this.ai = new AI(this);
+    this.search = new Search(this);
     this.auth = new Auth(this);
     this.storage = new Storage(this);
-
     this.customers = new Customers(this);
     this.tags = new Tags(this);
     this.templates = new Templates(this);

package/package.json

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

package/src/ai.js

@@ -5,7 +5,7 @@
  * @import { content } from '@storecraft/core/ai/types.public.js'
  */
 
-import { HEADER_STORECRAFT_THREAD_ID } from '../../core/rest/con.ai.routes.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';
 

package/src/auth.js

@@ -3,6 +3,7 @@
  *  ApiAuthChangePasswordType, ApiAuthResult, ApiAuthSigninType, ApiAuthSignupType, 
  *  ApiKeyResult, ApiQuery, AuthUserType, error
  * } from '@storecraft/core/api'
+ * @import { SdkConfigAuth } from '../types.js';
  */
 
 import { api_query_to_searchparams } from '@storecraft/core/api/utils.query.js';
@@ -12,10 +13,6 @@ import { assert } from './utils.functional.js';
 
 
 /**
- * 
- * @typedef {import('../index.js').SdkConfigAuth} SdkConfigAuth
- * 
- * 
  * @typedef {object} SubscriberCallbackPayload
  * @prop {SdkConfigAuth} auth
  * @prop {boolean} isAuthenticated
@@ -72,7 +69,7 @@ export default class Auth {
   }
 
   /**
-   * @param {import('../index.js').SdkConfigAuth} value 
+   * @param {SdkConfigAuth} value 
    */
   set currentAuth(value) {
     this.#sdk.config.auth = value;

package/src/checkout.js

@@ -1,3 +1,6 @@
+/**
+ * @import { CheckoutCreateType, OrderData, PricingData } from '@storecraft/core/api'
+ */
 import { StorecraftSDK } from '../index.js'
 import { fetchApiWithAuth } from './utils.api.fetch.js';
 
@@ -18,10 +21,10 @@ export default class Checkout {
   /**
    * @description Create a `checkout`
    * 
-   * @param {import('@storecraft/core/api').CheckoutCreateType} input 
+   * @param {CheckoutCreateType} input 
    * @param {string} gateway_handle 
    * 
-   * @returns {Promise<Partial<import('@storecraft/core/api').OrderData>>}
+   * @returns {Promise<Partial<OrderData>>}
    */
   create = async (input, gateway_handle) => {
 
@@ -46,7 +49,7 @@ export default class Checkout {
    * 
    * @param {string} order_id 
    * 
-   * @returns {Promise<Partial<import('@storecraft/core/api').OrderData>>}
+   * @returns {Promise<Partial<OrderData>>}
    */
   complete = async (order_id) => {
 
@@ -62,11 +65,12 @@ export default class Checkout {
   }
 
   /**
-   * @description calculate the pricing of an `order`. Using auto-discounts, coupons, shipping and line-items.
+   * @description calculate the pricing of an `order`. Using auto-discounts, 
+   * coupons, shipping and line-items.
    * 
-   * @param {Partial<import('@storecraft/core/api').OrderData>} order 
+   * @param {Partial<OrderData>} order 
    * 
-   * @returns {Promise<Partial<import('@storecraft/core/api').PricingData>>}
+   * @returns {Promise<Partial<PricingData>>}
    */
   pricing = async (order) => {
 

package/src/collections.js

@@ -1,3 +1,6 @@
+/**
+ * @import { CollectionType, CollectionTypeUpsert } 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';
@@ -5,10 +8,7 @@ import { filter_fields, filter_unused } from './utils.functional.js';
 /**
  * @description Base `collections` **CRUD**
  * 
- * @extends {collection_base<
- *  import('@storecraft/core/api').CollectionTypeUpsert, 
- *  import('@storecraft/core/api').CollectionType>
- * }
+ * @extends {collection_base<CollectionTypeUpsert, CollectionType>}
  */
 export default class Collections extends collection_base {
 

package/src/customers.js

@@ -1,13 +1,13 @@
+/**
+ * @import { CustomerType, CustomerTypeUpsert } from '@storecraft/core/api'
+ */
 import { StorecraftSDK } from '../index.js'
 import { collection_base } from './utils.api.fetch.js';
 
 /**
  * @description Base `customers` **CRUD**
  * 
- * @extends {collection_base<
- *  import('@storecraft/core/api').CustomerTypeUpsert, 
- *  import('@storecraft/core/api').CustomerType>
- * }
+ * @extends {collection_base<CustomerTypeUpsert, CustomerType>}
  */
 export default class Customers extends collection_base {
 

package/src/discounts.js

@@ -1,13 +1,13 @@
+/**
+ * @import { DiscountType, DiscountTypeUpsert } from '@storecraft/core/api'
+ */
 import { StorecraftSDK } from '../index.js'
 import { collection_base } from './utils.api.fetch.js';
 
 /**
  * @description Base `discounts` **CRUD**
  * 
- * @extends {collection_base<
- *  import('@storecraft/core/api').DiscountTypeUpsert, 
- *  import('@storecraft/core/api').DiscountType>
- * }
+ * @extends {collection_base<DiscountTypeUpsert, DiscountType>}
  */
 export default class Discounts extends collection_base {
 
@@ -19,131 +19,4 @@ export default class Discounts extends collection_base {
     super(sdk, 'discounts');
   }
 
-  // /**
-  //  * 
-  //  * @param {DiscountData} discount_data 
-  //  * @param {number} limit 
-  //  */
-  // publish = async (discount_data, limit=10000) => {
-  //   const coll_handle = `discount-${discount_data.code}`
-  //   const dd = { 
-  //     ...discount_data,
-  //     _published: coll_handle
-  //   }
-  //   if(dd.info.details.meta.type==='order')
-  //     throw 'Exporting a discount collection is only available for \
-  //             Product discounts (you chose Order discount)'
-
-  //   // save current document, allow to fail              
-  //   await this.set(
-  //     dd.code, dd
-  //   )
-  //   // await this.update(dd.code, { _published: coll_handle })
-
-    
-  //   // first, remove all previous collection tag from previous products              
-  //   try {
-  //     const products_to_remove = 
-  //           await this.context.products.list([`col:${coll_handle}`], 10000)
-  //     // console.log('products_to_remove ', products_to_remove);
-  //     const batch_remove = writeBatch(this.context.firebase.db)
-  //     products_to_remove.forEach(it => {
-  //       const ref = doc(this.context.firebase.db, 'products', it[0])
-  //       batch_remove.update(ref, { 
-  //         search : arrayRemove(`col:${coll_handle}`),
-  //         collections : arrayRemove(coll_handle),
-  //         [`discounts.${dd.code}`]: deleteField()
-  //       })
-  //     })
-  //     await batch_remove.commit()
-
-  //   } catch (e) {
-  //     console.log('Remove old: ' + String(e))
-  //     console.log(e)
-  //   }
-
-  //   try {
-  //     // filter in product filters
-  //     var product_filters = dd.info.filters.filter(f => f.meta.type==='product')
-
-  //     // then, make a server search that will filter out as much as possible
-  //     /**@type {Filter} */
-  //     var first_guided_filter = undefined
-  //     /**@type {string[]} */
-  //     var first_guided_search_terms = undefined
-
-  //     if(first_guided_filter = product_filters.find(f => f.meta.op==='p-in-handles')) {
-  //       first_guided_search_terms = first_guided_filter.value
-  //     }
-  //     else if(first_guided_filter = product_filters.find(f => f.meta.op==='p-in-tags')) {
-  //       first_guided_search_terms = first_guided_filter.value.map(t => `tag:${t}`)
-  //     }
-  //     else if(first_guided_filter = product_filters.find(f => f.meta.op==='p-in-collections')) {
-  //       first_guided_search_terms = first_guided_filter.value.map(c => `col:${c}`)
-  //     }
-  //   } catch (e) {
-  //     throw 'Filter preparing error: ' + String(e)
-  //   }
-
-  //   try {
-  //     // then, global filtering, this helps to reduce legal products for filtering
-  //     var products = await 
-  //             this.context.products.list(first_guided_search_terms, limit)
-
-  //     // now local filtering (due to firebase limitations with filtering)
-  //     var filtered_products = 
-  //             this.filterProductsWithFilters(products, product_filters)
-      
-  //     // products = products.slice(0, 400)
-  //   } catch (e) {
-  //     throw 'Filtering error: ' + String(e)
-  //   }
-
-  //   try {
-  //     // add collection tag to each product with batch write
-  //     const batch = writeBatch(this.context.firebase.db)
-  //     filtered_products.forEach(it => {
-  //       const p = it[1]
-  //       const isActive = p?.active==true || (p.active===undefined)
-  //       if(!isActive)
-  //         return;
-
-  //       const ref = doc(this.context.firebase.db, 'products', it[0])
-  //       const dd_mod = {...dd}
-  //       delete dd_mod.search
-  //       delete dd_mod.order
-  //       batch.update(ref, { 
-  //         collections : arrayUnion(coll_handle),
-  //         search : arrayUnion(`col:${coll_handle}`),
-  //         [`discounts.${dd_mod.code}`]: dd_mod
-  //       })
-  //     })
-  //     await batch.commit()
-  //   } catch (e) {
-  //     throw 'Products update failed: ' + String(e)
-  //   }
-
-  //   try {
-  //     // now, create a new collection
-  //     /**@type {import('./js-docs-types').CollectionData} */
-  //     const col_discount = {
-  //       desc : dd.desc,
-  //       handle : coll_handle,
-  //       title : dd.title,
-  //       media : dd.media,
-  //       tags : dd.tags,
-  //       attributes: dd.attributes,
-  //       createdAt: Date.now()
-  //     }
-
-  //     await this.context.collections.set(
-  //       col_discount.handle, col_discount
-  //     )
-  //     // await this.update(discount_data.code, { _published: coll_handle })
-  //   } catch (e) {
-  //     throw 'Collection creation failed: ' + String(e)
-  //   }
-    
-  // }
-
 }

package/src/images.js

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

package/src/notifications.js

@@ -1,3 +1,6 @@
+/**
+ * @import { NotificationTypeUpsert, NotificationType } from '@storecraft/core/api'
+ */
 import { StorecraftSDK } from '../index.js'
 import { 
   collection_base, fetchApiWithAuth 
@@ -6,10 +9,7 @@ import {
 /**
  * @description Base `notifications` **CRUD**
  * 
- * @extends {collection_base<
- *  import('@storecraft/core/api').NotificationTypeUpsert, 
- *  import('@storecraft/core/api').NotificationType>
- * }
+ * @extends {collection_base<NotificationTypeUpsert, NotificationType>}
  */
 export default class Notifications extends collection_base {
 
@@ -23,7 +23,7 @@ export default class Notifications extends collection_base {
 
   /**
    * 
-   * @param {import('@storecraft/core/api').NotificationTypeUpsert[]} items 
+   * @param {NotificationTypeUpsert[]} items 
    */
   upsertBulk = items => {
     return fetchApiWithAuth(

package/src/orders.js

@@ -1,13 +1,13 @@
+/**
+ * @import { OrderDataUpsert, OrderData } from '@storecraft/core/api'
+ */
 import { StorecraftSDK } from '../index.js'
 import { collection_base } from './utils.api.fetch.js';
 
 /**
  * @description Base `orders` **CRUD**
  * 
- * @extends {collection_base<
- *  import('@storecraft/core/api').OrderDataUpsert, 
- *  import('@storecraft/core/api').OrderData>
- * }
+ * @extends {collection_base<OrderDataUpsert, OrderData>}
  */
 export default class Orders extends collection_base {
 

package/src/payments.js

@@ -1,6 +1,9 @@
+/**
+ * @import { PaymentGatewayItemGet, PaymentGatewayStatus } from '@storecraft/core/api'
+ */
 import { StorecraftSDK } from '../index.js'
 import { 
-  fetchApiWithAuth, get, list 
+  fetchApiWithAuth, get_from_collection_resource, list_from_collection_resource 
 } from './utils.api.fetch.js';
 
 /**
@@ -8,7 +11,7 @@ import {
  */
 export default class Payments {
 
-  /** @type {import('../index.js').StorecraftSDK} */
+  /** @type {StorecraftSDK} */
   #sdk = undefined;
   
   /**
@@ -24,19 +27,19 @@ export default class Payments {
    * @param {string} handle payment gateway `handle`
    * 
    * 
-   * @returns {Promise<import('@storecraft/core/api').PaymentGatewayItemGet>}
+   * @returns {Promise<PaymentGatewayItemGet>}
    */
   get(handle) {
-    return get(this.sdk, 'payments/gateways', handle);
+    return get_from_collection_resource(this.sdk, 'payments/gateways', handle);
   }
 
   /**
    * 
    * 
-   * @returns {Promise<import('@storecraft/core/api').PaymentGatewayItemGet[]>}
+   * @returns {Promise<PaymentGatewayItemGet[]>}
    */
   list() {
-    return list(this.sdk, 'payments/gateways');
+    return list_from_collection_resource(this.sdk, 'payments/gateways');
   }
 
 
@@ -48,7 +51,7 @@ export default class Payments {
    * 
    * @param {string} order_id 
    * 
-   * @returns {Promise<import('@storecraft/core/api').PaymentGatewayStatus>}
+   * @returns {Promise<PaymentGatewayStatus>}
    */
   paymentStatusOfOrder(order_id) {
     return fetchApiWithAuth(
@@ -63,14 +66,14 @@ export default class Payments {
   /**
    * 
    * Invoke a `payment gateway` action on `order`. The list of available actions can be found
-   * using {@link get} or {@link paymentStatusOfOrder}
+   * 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<import('@storecraft/core/api').PaymentGatewayStatus>}
+   * @returns {Promise<PaymentGatewayStatus>}
    */
   invokeAction(action_handle, order_id) {
     return fetchApiWithAuth(

package/src/posts.js

@@ -1,13 +1,13 @@
+/**
+ * @import { PostTypeUpsert, PostType } from '@storecraft/core/api'
+ */
 import { StorecraftSDK } from '../index.js'
 import { collection_base } from './utils.api.fetch.js';
 
 /**
  * @description Base `posts` **CRUD**
  * 
- * @extends {collection_base<
- *  import('@storecraft/core/api').PostTypeUpsert, 
- *  import('@storecraft/core/api').PostType>
- * }
+ * @extends {collection_base<PostTypeUpsert, PostType>}
  */
 export default class Posts extends collection_base {
 

package/src/products.js

@@ -1,3 +1,6 @@
+/**
+ * @import { ProductTypeUpsert, ProductType, CollectionType } from '@storecraft/core/api'
+ */
 import { StorecraftSDK } from '../index.js'
 import { 
   collection_base, fetchOnlyApiResponseWithAuth 
@@ -6,10 +9,7 @@ import {
 /**
  * @description Base `products` **CRUD**
  * 
- * @extends {collection_base<
- *  import('@storecraft/core/api').ProductTypeUpsert, 
- *  import('@storecraft/core/api').ProductType>
- * }
+ * @extends {collection_base<ProductTypeUpsert, ProductType>}
  */
 export default class Products extends collection_base {
 
@@ -44,8 +44,8 @@ export default class Products extends collection_base {
   /**
    * Add `products` to `collection`
    * 
-   * @param {import('@storecraft/core/api').ProductType[]} products 
-   * @param {import('@storecraft/core/api').CollectionType} collection 
+   * @param {ProductType[]} products 
+   * @param {CollectionType} collection 
    */
   batchAddProductsToCollection = async (products, collection) => {
     for (const pr of products) {
@@ -59,8 +59,8 @@ export default class Products extends collection_base {
   /**
    * Remove `products` from `collection`
    * 
-   * @param {import('@storecraft/core/api').ProductType[]} products 
-   * @param {import('@storecraft/core/api').CollectionType} collection 
+   * @param {ProductType[]} products 
+   * @param {CollectionType} collection 
    */
   batchRemoveProductsFromCollection = async (products, collection) => {
     for (const pr of products) {

package/src/search.js

@@ -0,0 +1,84 @@
+/**
+ * @import { 
+ *  AgentRunParameters, AgentRunResponse 
+ * } from '@storecraft/core/ai/agents/types.js'
+ * @import { 
+ *  ApiQuery, QuickSearchResult, SimilaritySearchInput, SimilaritySearchResult 
+ * } from '@storecraft/core/api'
+ */
+
+import { 
+  api_query_to_searchparams, object_to_search_params, 
+  parse_query, 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';
+
+/**
+ * @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) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * @description List super lite search results with `id`, `handle`, `title`. 
+   * Primarily used for quick and responsive lookup, this is cheap and cost-effective 
+   * and works well in the dashboard. If an admin is hitting the endpoint, then he can 
+   * even get results for orders, customer and auth_users. You can also use the expand in the 
+   * query to efficiently control which resources are searched at the database
+   * @param {ApiQuery} params A regular {@link ApiQuery} object
+   * @returns {Promise<QuickSearchResult>}
+   */
+  quick = async (params) => {
+
+    /** @type {QuickSearchResult} */
+    const json = await fetchApiWithAuth(
+      this.sdk,
+      'search',
+      { method: 'get' },
+      api_query_to_searchparams(params)
+    );
+
+    return json;
+  }
+
+
+  /**
+   * @description Search Storecraft with AI for similar 
+   * `products`, `discounts`, `collections`, `shipping`
+   * based on a prompt
+   * @param {SimilaritySearchInput} params A {@link SimilaritySearchInput} object
+   * @returns {Promise<SimilaritySearchResult>}
+   */
+  similarity = async (params) => {
+
+    /** @type {SimilaritySearchResult} */
+    const json = await fetchApiWithAuth(
+      this.sdk,
+      'similarity-search',
+      { method: 'get' },
+      object_to_search_params({
+        q: params.q,
+        namespaces: string_array_to_string(params.namespaces),
+        limit: params.limit ?? 5
+      })
+    );
+
+    return json;
+  }
+
+}
+
+

package/src/shipping.js

@@ -1,13 +1,13 @@
+/**
+ * @import { ShippingMethodTypeUpsert, ShippingMethodType } from '@storecraft/core/api'
+ */
 import { StorecraftSDK } from '../index.js'
 import { collection_base } from './utils.api.fetch.js';
 
 /**
  * @description Base `shipping` **CRUD**
  * 
- * @extends {collection_base<
- *  import('@storecraft/core/api').ShippingMethodTypeUpsert, 
- *  import('@storecraft/core/api').ShippingMethodType>
- * }
+ * @extends {collection_base<ShippingMethodTypeUpsert, ShippingMethodType>}
  */
 export default class Shipping extends collection_base {
 

package/src/statistics.js

@@ -1,3 +1,6 @@
+/**
+ * @import { OrdersStatisticsType, ApiQuery } from '@storecraft/core/api'
+ */
 import { App } from '@storecraft/core';
 import { StorecraftSDK } from '../index.js'
 import { fetchApiWithAuth } from './utils.api.fetch.js';
@@ -38,7 +41,7 @@ export default class Statistics  {
   /**
    * 
    * @param {string} key 
-   * @returns {import('@storecraft/core/api').OrdersStatisticsType}
+   * @returns {OrdersStatisticsType}
    */
   fromCache = (key) => {
     if(this.isCacheValid(key))
@@ -49,7 +52,7 @@ export default class Statistics  {
   /**
    * 
    * @param {string} key 
-   * @param {import('@storecraft/core/api').OrdersStatisticsType} value
+   * @param {OrdersStatisticsType} value
    */
   putCache = (key, value) => {
     this.#cache[key] = value
@@ -62,7 +65,7 @@ export default class Statistics  {
    * @param {string | number | Date} [from_day] `ISO` string | `UTC` | `timestamp` | `Date`
    * @param {string | number | Date} [to_day] `ISO` string | `UTC` | `timestamp` | `Date`
    * 
-   * @returns {Promise<import('@storecraft/core/api').OrdersStatisticsType>}
+   * @returns {Promise<OrdersStatisticsType>}
    */
   orders = async (from_day, to_day) => {
     const search = new URLSearchParams();
@@ -82,7 +85,7 @@ export default class Statistics  {
    * @description Load **count** `statistics`
    * 
    * @param {keyof App["db"]["resources"]} table 
-   * @param {import('@storecraft/core/api').ApiQuery} [query]
+   * @param {ApiQuery} [query]
    * 
    * 
    * @returns {Promise<number>}

package/src/storage.js

@@ -1,3 +1,7 @@
+/**
+ * @import { StorageFeatures, StorageSignedOperation } from '@storecraft/core/storage'
+ * @import { error } from '@storecraft/core/api'
+ */
 
 import { StorecraftSDK } from '../index.js'
 import { fetchOnlyApiResponseWithAuth } from './utils.api.fetch.js'
@@ -16,7 +20,7 @@ export default class Storage {
 
   /**
    * @type {{
-   *  features: import('@storecraft/core/storage').StorageFeatures
+   *  features: StorageFeatures
    * }}
    */
   #cache = {
@@ -36,7 +40,7 @@ export default class Storage {
    * - Does `storage` supports `pre-signed` urls for `download` / `upload`
    * 
    * 
-   * @returns {Promise<import('@storecraft/core/storage').StorageFeatures>}
+   * @returns {Promise<StorageFeatures>}
    */
   features = async () => {
     if(this.#cache.features)
@@ -78,7 +82,7 @@ export default class Storage {
    * 
    * @return {Promise<Blob>}
    * 
-   * @throws {import('@storecraft/core/api').error}
+   * @throws {error}
    */
   getBlobSigned = async (key) => {
 
@@ -98,7 +102,7 @@ export default class Storage {
 
     // `presigned` url instructions
     if(ctype === 'application/json') {
-      /** @type {import('@storecraft/core/storage').StorageSignedOperation} */
+      /** @type {StorageSignedOperation} */
       const presigned_req = await r.json();
 
       const presigned_res = await fetch(
@@ -123,7 +127,7 @@ export default class Storage {
    * 
    * @return {Promise<Blob>}
    * 
-   * @throws {import('@storecraft/core/api').error}
+   * @throws {error}
    */
   getBlobUnsigned = async (key) => {
 
@@ -152,7 +156,7 @@ export default class Storage {
    * 
    * @return {Promise<Blob>}
    * 
-   * @throws {import('@storecraft/core/api').error}
+   * @throws {error}
    */
   getBlob = async (key) => {
 
@@ -238,7 +242,7 @@ export default class Storage {
 
     // `presigned` url instructions
     if(ctype === 'application/json') {
-      /** @type {import('@storecraft/core/storage').StorageSignedOperation} */
+      /** @type {StorageSignedOperation} */
       const presigned_req = await r.json();
       const presigned_res = await fetch(
         presigned_req.url, 
@@ -294,7 +298,7 @@ export default class Storage {
    * 
    * @return {Promise<boolean>}
    * 
-   * @throws {import('@storecraft/core/api').error}
+   * @throws {error}
    */
   putBytes = async (key, data) => {
 

package/src/storefronts.js

@@ -1,13 +1,14 @@
+/**
+ * @import { HandleOrId } from '@storecraft/core/database'
+ * @import { StorefrontType, StorefrontTypeUpsert } from '@storecraft/core/api'
+ */
 import { StorecraftSDK } from '../index.js'
 import { collection_base, fetchApiWithAuth } from './utils.api.fetch.js';
 
 /**
  * @description Base `storefronts` **CRUD**
  * 
- * @extends {collection_base<
- *  import('@storecraft/core/api').StorefrontTypeUpsert, 
- *  import('@storecraft/core/api').StorefrontType>
- * }
+ * @extends {collection_base<StorefrontTypeUpsert, StorefrontType>}
  */
 export default class Storefronts extends collection_base {
 
@@ -24,7 +25,7 @@ export default class Storefronts extends collection_base {
    * beneficial for `collections`, that hardly change and therefore can be 
    * efficiently stored in a cost-effective `storage` and **CDN** network.
    * 
-   * @param {import('@storecraft/core/database').HandleOrId} handle_or_id
+   * @param {HandleOrId} handle_or_id
    */
   publish = async (handle_or_id) => {
 

package/src/tags.js

@@ -1,13 +1,13 @@
+/**
+ * @import { TagType, TagTypeUpsert } from '@storecraft/core/api'
+ */
 import { StorecraftSDK } from '../index.js'
 import { collection_base } from './utils.api.fetch.js';
 
 /**
  * @description Base `tags` **CRUD**
  * 
- * @extends {collection_base<
- *  import('@storecraft/core/api').TagTypeUpsert, 
- *  import('@storecraft/core/api').TagType>
- * }
+ * @extends {collection_base<TagTypeUpsert, TagType>}
  */
 export default class Tags extends collection_base {
 

package/src/templates.js

@@ -1,13 +1,13 @@
+/**
+ * @import { TemplateTypeUpsert, TemplateType } from '@storecraft/core/api'
+ */
 import { StorecraftSDK } from '../index.js'
 import { collection_base } from './utils.api.fetch.js';
 
 /**
  * @description Base `templates` **CRUD**
  * 
- * @extends {collection_base<
- *  import('@storecraft/core/api').TemplateTypeUpsert, 
- *  import('@storecraft/core/api').TemplateType>
- * }
+ * @extends {collection_base<TemplateTypeUpsert, TemplateType>}
  */
 export default class Templates extends collection_base {
 

package/src/utils.api.fetch.js

@@ -1,4 +1,8 @@
-
+/**
+ * @import { error, ApiQuery } from '@storecraft/core/api'
+ * @import { StorecraftSDK } from '../index.js'
+ * @import { StorecraftSDKConfig } from '../types.js'
+ */
 import { 
   api_query_to_searchparams 
 } from '@storecraft/core/api/utils.query.js';
@@ -7,15 +11,21 @@ import { assert } from './utils.functional.js';
 
 /**
  * 
- * @param {import("../index.js").StorecraftSDKConfig} config 
+ * @param {StorecraftSDKConfig} config 
  * @param {string} path 
+ * @param {URLSearchParams} [query] url search params
  */
-export const url = (config, path) => {
+export const url = (config, path, query) => {
   let base = config?.endpoint?.trim();
 
   base = base?.endsWith('/') ? base.slice(0, -1) : base;
   path = path?.startsWith('/') ? path.slice(1) : path;
 
+  if(query?.size) {
+    path = path?.endsWith('/') ? path.slice(0, -1) : path;
+    path += '?' + query.toString();
+  }
+
   return base ? `${base}/api/${path}` : `/api/${path}`;
 }
 
@@ -26,13 +36,14 @@ export const url = (config, path) => {
  * - Fetches with `authentication` middleware. 
  * - Refreshed `auth` if needed. 
  * 
- * @param {import('../index.js').StorecraftSDK} sdk 
+ * @param {StorecraftSDK} sdk 
  * @param {string} path relative path in api
  * @param {RequestInit} [init] request `init` type
+ * @param {URLSearchParams} [query] url search params
  * 
  * @returns {Promise<Response>}
  */ 
-export const fetchOnlyApiResponseWithAuth = async (sdk, path, init={}) => {
+export const fetchOnlyApiResponseWithAuth = async (sdk, path, init={}, query=undefined) => {
 
   const auth_token = await sdk.auth.working_auth_token();
   const auth_header_value = (
@@ -41,7 +52,7 @@ export const fetchOnlyApiResponseWithAuth = async (sdk, path, init={}) => {
   
 
   const response = await fetch(
-    url(sdk.config, path),
+    url(sdk.config, path, query),
     {
       ...init,
       headers: {
@@ -71,19 +82,19 @@ export const fetchOnlyApiResponseWithAuth = async (sdk, path, init={}) => {
  * 
  * @template {any} R
  * 
- * @param {import('../index.js').StorecraftSDK} sdk
+ * @param {StorecraftSDK} sdk
  * @param {string} path relative path in api
  * @param {RequestInit} [init] request `init` type
+ * @param {URLSearchParams} [query] url search params
  * 
- * 
- * @throws {import('@storecraft/core/api').error}
+ * @throws {error}
  * 
  * @returns {Promise<R>}
  */ 
-export const fetchApiWithAuth = async (sdk, path, init={}) => {
+export const fetchApiWithAuth = async (sdk, path, init={}, query=undefined) => {
 
   const response = await fetchOnlyApiResponseWithAuth(
-    sdk, path, init
+    sdk, path, init, query
   );
 
   // console.log('fetchApiWithAuth::response', response)
@@ -108,14 +119,14 @@ export const fetchApiWithAuth = async (sdk, path, init={}) => {
  * @template {any} G Get type
  * 
  * 
- * @param {import('../index.js').StorecraftSDK} sdk
+ * @param {StorecraftSDK} sdk
  * @param {string} handle_or_id `handle` or `id`
  * @param {string} resource base path of resource
  * 
  * 
  * @returns {Promise<G>}
  */
-export async function get(sdk, resource, handle_or_id) {
+export async function get_from_collection_resource(sdk, resource, handle_or_id) {
   return fetchApiWithAuth(
     sdk, 
     `${resource}/${handle_or_id}`,
@@ -131,14 +142,14 @@ export async function get(sdk, resource, handle_or_id) {
  * @template {any} U the upsert type
  * 
  * 
- * @param {import('../index.js').StorecraftSDK} sdk
+ * @param {StorecraftSDK} sdk
  * @param {string} resource base path of resource
  * @param {U} item Item to upsert
  * 
  * 
  * @returns {Promise<string>} id
  */
-export async function upsert(sdk, resource, item) {
+export async function upsert_to_collection_resource(sdk, resource, item) {
   return fetchApiWithAuth(
     sdk, 
     `${resource}`,
@@ -155,14 +166,14 @@ export async function upsert(sdk, resource, item) {
 
 /**
  * 
- * @param {import('../index.js').StorecraftSDK} sdk
+ * @param {StorecraftSDK} sdk
  * @param {string} resource base path of resource
  * @param {string} handle_or_id `handle` or `id`
  * 
  * 
  * @returns {Promise<boolean>}
  */
-export async function remove(sdk, resource, handle_or_id) {
+export async function remove_from_collection_resource(sdk, resource, handle_or_id) {
   return fetchApiWithAuth(
     sdk, 
     `${resource}/${handle_or_id}`,
@@ -181,14 +192,14 @@ export async function remove(sdk, resource, handle_or_id) {
  * @template {any} G Get type
  * 
  * 
- * @param {import('../index.js').StorecraftSDK} sdk
+ * @param {StorecraftSDK} sdk
  * @param {string} resource base path of resource
- * @param {import('@storecraft/core/api').ApiQuery<G>} [query] 
+ * @param {ApiQuery<G>} [query] 
  * 
  * 
  * @returns {Promise<G[]>}
  */
-export async function list(sdk, resource, query={}) {
+export async function list_from_collection_resource(sdk, resource, query={}) {
   const sq = api_query_to_searchparams(query);
 
   // console.log('sq', sq.toString())
@@ -210,7 +221,7 @@ export async function list(sdk, resource, query={}) {
  */
 export class collection_base {
   
-  /** @type {import('../index.js').StorecraftSDK} */
+  /** @type {StorecraftSDK} */
   #sdk = undefined;
   
   /** @type {string} */
@@ -218,7 +229,7 @@ export class collection_base {
 
   /**
    * 
-   * @param {import('../index.js').StorecraftSDK} sdk storecraft sdk
+   * @param {StorecraftSDK} sdk storecraft sdk
    * @param {string} base_name base name of resource type
    */
   constructor(sdk, base_name) {
@@ -235,7 +246,7 @@ export class collection_base {
    * @returns {Promise<G>}
    */
   async get(handle_or_id) {
-    return get(this.sdk, this.base_name, handle_or_id);
+    return get_from_collection_resource(this.sdk, this.base_name, handle_or_id);
   }
 
   /**
@@ -246,7 +257,7 @@ export class collection_base {
    * @returns {Promise<string>} id
    */
   async upsert(item) {
-    return upsert(this.sdk, this.base_name, item);
+    return upsert_to_collection_resource(this.sdk, this.base_name, item);
   }
 
   /**
@@ -257,18 +268,18 @@ export class collection_base {
    * @returns {Promise<boolean>}
    */
   async remove(handle_or_id) {
-    return remove(this.sdk, this.base_name, handle_or_id);
+    return remove_from_collection_resource(this.sdk, this.base_name, handle_or_id);
   }
 
   /**
    * 
-   * @param {import('@storecraft/core/api').ApiQuery<G>} query Query object
+   * @param {ApiQuery<G>} query Query object
    * 
    * 
    * @returns {Promise<G[]>}
    */
   async list(query) {
-    return list(this.sdk, this.base_name, query);
+    return list_from_collection_resource(this.sdk, this.base_name, query);
   }
 
   get base_name() {

package/types.d.ts

@@ -1 +1,21 @@
-export * from './index.js';
+import type { ApiAuthResult, ApiKeyResult } from '@storecraft/core/api';
+
+export * from './index.js';
+
+/**
+ * @description The `storecraft` **SDK** 
+ * `auth` config, represents either `apikey` or `jwt` authentication
+ */
+export type SdkConfigAuth = ApiAuthResult | ApiKeyResult;
+
+/**
+ * @description The `storecraft` **SDK** config
+ */
+export type StorecraftSDKConfig = {
+
+  /** Endpoint of `backend` */
+  endpoint?: string;
+
+  /** `auth` info, may be either `apikey` or `jwt` results */
+  auth?: SdkConfigAuth;
+}