@storecraft/sdk 1.0.16 → 1.2.5

package/README.md

@@ -5,52 +5,78 @@
        width='90%' />
 </div><hr/><br/>
 
+# **Storecraft** Official Universal `Javascript` **SDK**
+
 This is the official `storecraft` universal javascript `SDK` which is `fetch` based,
-which means you can you it both at browser and at backend runtimes such (`node` / `bun` / `deno`)
+which means you can you it both at browser and at backend runtimes such as,
+- `node`
+- `bun`
+- `deno`
+- `cloudflare workers`
+
+Start by installing the package:
 
-It will allow you to fetch / mutate all of the resources at the `backend` in a 
-convenient manner with `javascript`, such as:
+```bash
+npm i @storecraft/sdk
+```
 
-#### collections
-`products`, `collections`, `auth_users`, `customers`, `orders`, `discounts`,
-`storefronts`, `shipping`, `tags`, `posts`, `notifications`,
-`templates`, `extensions`, `images`
+## Resources
+
+The SDK is a wrapper around the `storecraft` REST API, and it allows you to
+perform operations on the following resources:
+
+### collections
+- **products** - manage products
+- **collections** - manage collections
+- **auth_users** - manage auth users
+- **customers** - manage customers
+- **orders** - manage orders
+- **discounts** - manage discounts
+- **storefronts** - manage storefronts
+- **shipping** - manage shipping
+- **tags** - manage tags
+- **posts** - manage posts
+- **notifications** - manage notifications
+- **templates** - manage templates
+- **extensions** - manage extensions
+- **payments** - manage payment gateways
+- **images** - manage images
+
+### Auth
 
-#### Auth
 Perform authentication such as `signin` / `signup` / `api-key`
 
-#### Checkout
-Perform checkout `create` / `complete`
+### Checkout
+
+Perform checkout `create` / `complete` with payment gateways such as `stripe` / `paypal`.
+
+### Storage
 
-#### Storage
 Perform storage operations such as `put` / `get` / `delete`
 
-#### Payments
+### Payments
+
 Perform payments `status-check` / `invoke-action`
 
-#### Statistics
+### Statistics
+
 - Query some basic statistics about `orders` in a time span
 - Query count of items in collections
 
-#### AI
+### AI
+
 Speak with a `storecraft` agent (Supports streaming :))
 
-#### Semantic / Similarity Search
+### Semantic / Similarity Search
+
 Search Storecraft with AI for similar `products`, `discounts`, `collections`, `shipping` based on a prompt.
 
-#### Quick Search
+### Quick Search
+
 List super lite search results with `id`, `handle`, `title` over most resources 
 
 <hr/>
 
-Start by installing, 
-
-Plus, everything is typed so you dont have to guess any parameter or queryable key
-
-```bash
-npm i @storecraft/sdk
-```
-
 ## Authentication
 
 Authentication and authorization is required for some resources, such as:
@@ -70,7 +96,7 @@ import { StorecraftSDK } from '@storecraft/sdk'
 
 const sdk = new StorecraftSDK(
   {
-    backend: 'http://localhost:8000', 
+    endpoint: 'http://localhost:8000', 
     auth: {
       apikey: <YOUR-API-KEY>
     }
@@ -90,7 +116,7 @@ import { StorecraftSDK } from '@storecraft/sdk'
 
 const sdk = new StorecraftSDK(
   {
-    backend: 'http://localhost:8000', 
+    endpoint: 'http://localhost:8000', 
   }
 );
 
@@ -106,7 +132,7 @@ import { StorecraftSDK } from '@storecraft/sdk'
 
 const sdk = new StorecraftSDK(
   {
-    backend: 'http://localhost:8000', 
+    endpoint: 'http://localhost:8000', 
     auth: {
       access_token: <OPTIONAL-ACCESS-TOKEN>,
       refresh_token: <OPTIONAL-REFRESH-TOKEN>,
@@ -125,7 +151,7 @@ import { StorecraftSDK } from '@storecraft/sdk'
 
 const sdk = new StorecraftSDK(
   {
-    backend: 'http://localhost:8000', 
+    endpoint: 'http://localhost:8000', 
   }
 );
 
@@ -143,7 +169,6 @@ const auth_result = await sdk.auth.signout();
 
 ## Querying
 
-
 Here are some examples for querying.
 
 - Every key and string in the example below is fully typed with `typescript`,
@@ -159,13 +184,19 @@ const sdk = new StorecraftSDK();
 const products: ProductType[] = await sdk.products.list(
   {
     expand: ['collections', 'variants'],
-    sortBy: ['updated_at', 'id'], // all keys will show up in intellisense
+    sortBy: ['updated_at', 'id'],
     order: 'desc',
-    startAt: [
-      ['updated_at': '2024-03-24'],
-    ],
+    vql: {
+      updated_at: {
+        $gte: '2024-03-24',
+      },
+      active: true,
+      $or: [
+        { $search: 'tag:genre_action' },
+        { $search: 'tag:genre_sports' },
+      ],
+    }
     limit: 5,
-    vql: '(keyword1 | keyword2) -(keyword3)'
   }
 )
 
@@ -180,13 +211,21 @@ const sdk = new StorecraftSDK();
 
 const collections: CollectionType[] = await sdk.collections.list(
   {
-    equals: [['active': true]]
+    vql: 'active=true & (nintendo | playstation)'
     limit: 5,
   }
 );
 
 ```
 
+## Testing
+
+most of the tests for this package are done in the `storecraft` `core` package,
+as part of the **REST API** tests.
+
+This package will hold more `unit` tests for the `sdk` itself, which include
+side effects and particular behaviours.
+
 ```text
 Author: Tomer Shalev (tomer.shalev@gmail.com)
 ```

package/index.js

@@ -16,18 +16,20 @@ import Images from './src/images.js'
 import Posts from './src/posts.js'
 import Checkout from './src/checkout.js'
 import Payments from './src/payments.js'
-import Settings from './src/settings.js'
+import Reference from './src/reference.js'
 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 Chats from './src/chats.js'
 import { 
   fetchApiWithAuth, fetchOnlyApiResponseWithAuth 
 } from './src/utils.api.fetch.js'
 import Email from './src/email.js'
 
 /**
- * @description The official `storecraft` universal **SDK** for `javascript`
+ * @description The official `storecraft` universal 
+ * **SDK** for `javascript`
  */
 export class StorecraftSDK {
 
@@ -44,7 +46,8 @@ export class StorecraftSDK {
    */  
   constructor(config, fetcher) {
     this.#config = config;
-    this.#fetcher = fetcher ?? ((input, init) => fetch(input, init));
+    this.#fetcher = fetcher ?? 
+      ((input, init) => fetch(input, init));
 
     this.ai = new AI(this);
     this.search = new Search(this);
@@ -64,13 +67,14 @@ export class StorecraftSDK {
     this.posts = new Posts(this);
     this.payments = new Payments(this);
     this.checkout = new Checkout(this);
-    this.settings = new Settings(this);
+    this.reference = new Reference(this);
     this.notifications = new Notifications(this);
     this.emails = new Email(this);
+    this.chats = new Chats(this);
   }
 
   get fetcher() {
-    return this.#fetcher
+    return this.#fetcher;
   }
   
   /**
@@ -110,17 +114,31 @@ export class StorecraftSDK {
   }
 
   /**
+   * @description Update / override config with
+   * new properties.
    * @param {StorecraftSDKConfig} [config] 
    */  
   updateConfig(config) {
     this.#config = {
-      ...config
+      ...(this.#config ?? {}),
+      ...(config ?? {})
     };
   }
 
+  /**
+   * @description get the current config
+   */
   get config() {
     return this.#config
   }
+
+  /**
+   * @description set a config
+   * @param {StorecraftSDKConfig} config 
+   */  
+  set config(config) {
+    this.#config = config;
+  }
 }
 
 /**
@@ -135,6 +153,7 @@ export const validateConfig = (config) => {
  */  
 export const create = (config) => { 
   const sdk = new StorecraftSDK(config);
+  
   return sdk;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storecraft/sdk",
-  "version": "1.0.16",
+  "version": "1.2.5",
   "description": "Official storecraft Universal Javascript SDK",
   "license": "MIT",
   "author": "Tomer Shalev (https://github.com/store-craft)",
@@ -19,8 +19,7 @@
   "scripts": {
     "sdk:test": "echo \"Error: no test specified\" && exit 1",
     "test": "npm run sdk:test",
-    "sc-publish": "npm publish",
-    "prepublishOnly": "npm version patch --force"
+    "sc-publish": "npm publish"
   },
   "type": "module",
   "types": "./types.d.ts",

package/src/ai.js

@@ -56,7 +56,7 @@ export default class AI {
    * @param {AgentRunParameters} params 
    */
   streamSpeak = async (agent_handle, params) => {
-    
+    // console.log({config: this.sdk.config})
     const response = await this.sdk.fetcher(
       url(this.sdk.config, `ai/agents/${agent_handle}/stream`),
       {
@@ -68,6 +68,13 @@ export default class AI {
       }
     );
 
+    if(!response.ok) {
+      const error = await response.json();
+      throw new Error(
+        `Error ${response.status}: ${error.message}`
+      );
+    }
+
     const threadId = response.headers.get(
       HEADER_STORECRAFT_THREAD_ID ?? 'X-Storecraft-Thread-Id'
     );

package/src/auth.js

@@ -10,7 +10,7 @@
 
 import { 
   api_query_to_searchparams 
-} from '@storecraft/core/api/utils.query.js';
+} from '@storecraft/core/api/query.js';
 import { StorecraftSDK } from '../index.js';
 import { 
   count_query_of_resource, fetchApiWithAuth, url 

package/src/chats.js

@@ -0,0 +1,50 @@
+/**
+ * @import { ChatTypeUpsert, ChatType, ChatHistoryType } from '@storecraft/core/api'
+ * @import { StorageSignedOperation } from '@storecraft/core/storage'
+ */
+import { StorecraftSDK } from '../index.js'
+import { collection_base, fetchApiWithAuth } from './utils.api.fetch.js';
+
+/**
+ * @description Base `chats` metadata **CRUD**
+ * @extends {collection_base<ChatTypeUpsert, ChatType>}
+ */
+export default class Chats extends collection_base {
+
+  /**
+   * @param {StorecraftSDK} sdk 
+   */
+  constructor(sdk) {
+    super(sdk, 'chats');
+  }
+
+  /**
+   * @description Download chat contents and metadata.
+   * @template {true | false} [PRESIGNED=false]
+   * @param {string} thread_id the chat thread id 
+   * @param {PRESIGNED} [prefers_presigned_urls=false] Do you 
+   * prefer presigned urls?
+   * @returns {Promise<
+   *  PRESIGNED extends false ? 
+   *    ChatHistoryType : 
+   *    StorageSignedOperation
+   * >}
+   */
+  download = async (
+    thread_id, 
+    prefers_presigned_urls=/** @type {PRESIGNED} */(false)
+  ) => {
+
+    const result = await fetchApiWithAuth(
+      this.sdk,
+      `chats/download/${thread_id}?signed=${prefers_presigned_urls}`,
+      {
+        method: 'get',
+      }
+    );
+
+    return result
+  }
+  
+
+}

package/src/checkout.js

@@ -23,10 +23,8 @@ export default class Checkout {
 
   /**
    * @description Create a `checkout`
-   * 
    * @param {CheckoutCreateType} input 
    * @param {string} gateway_handle 
-   * 
    * @returns {Promise<Partial<OrderData>>}
    */
   create = async (input, gateway_handle) => {
@@ -48,9 +46,7 @@ export default class Checkout {
 
   /**
    * @description Complete a `checkout`
-   * 
    * @param {string} order_id 
-   * 
    * @returns {Promise<Partial<OrderData>>}
    */
   complete = async (order_id) => {

package/src/collections.js

@@ -11,7 +11,6 @@ import {
 
 /**
  * @description Base `collections` **CRUD**
- * 
  * @extends {collection_base<CollectionTypeUpsert, CollectionType>}
  */
 export default class Collections extends collection_base {

package/src/customers.js

@@ -11,7 +11,6 @@ import {
 
 /**
  * @description Base `customers` **CRUD**
- * 
  * @extends {collection_base<CustomerTypeUpsert, CustomerType>}
  */
 export default class Customers extends collection_base {

package/src/discounts.js

@@ -13,7 +13,6 @@ import {
 
 /**
  * @description Base `discounts` **CRUD**
- * 
  * @extends {collection_base<DiscountTypeUpsert, DiscountType>}
  */
 export default class Discounts extends collection_base {

package/src/notifications.js

@@ -10,7 +10,6 @@ import {
 
 /**
  * @description Base `notifications` **CRUD**
- * 
  * @extends {collection_base<NotificationTypeUpsert, NotificationType>}
  */
 export default class Notifications extends collection_base {

package/src/orders.js

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

package/src/posts.js

@@ -6,7 +6,6 @@ import { collection_base } from './utils.api.fetch.js';
 
 /**
  * @description Base `posts` **CRUD**
- * 
  * @extends {collection_base<PostTypeUpsert, PostType>}
  */
 export default class Posts extends collection_base {

package/src/products.js

@@ -8,7 +8,6 @@ import {
 
 /**
  * @description Base `products` **CRUD**
- * 
  * @extends {collection_base<ProductTypeUpsert, ProductType>}
  */
 export default class Products extends collection_base {

package/src/reference.js

@@ -0,0 +1,46 @@
+/**
+ * @import { App, StorecraftConfig } from '@storecraft/core'
+ * @import { StorecraftAppPublicInfo } from '@storecraft/core/api'
+ */
+import { StorecraftSDK } from '../index.js'
+import { fetchApiWithAuth } from './utils.api.fetch.js';
+
+/**
+ * @description Reference
+ */
+export default class Reference {
+
+  /**
+   * @param {StorecraftSDK} sdk 
+   */
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * @returns {Promise<StorecraftConfig>}
+   */
+  settings = async () => {
+    /** @type {StorecraftConfig} */
+    const json = await fetchApiWithAuth(
+      this.sdk,
+      'settings',
+      { method: 'get' },
+    );
+    return json;
+  }
+
+  /**
+   * @returns {Promise<StorecraftAppPublicInfo>}
+   */
+  info = async () => {
+    /** @type {StorecraftAppPublicInfo} */
+    const json = await fetchApiWithAuth(
+      this.sdk,
+      'info',
+      { method: 'get' },
+    );
+    return json;
+  }
+
+}

package/src/search.js

@@ -6,10 +6,10 @@
 
 import { 
   api_query_to_searchparams, object_to_search_params, 
-  string_array_to_string 
-} from '@storecraft/core/api/utils.query.js';
+} from '@storecraft/core/api/query.js';
 import { StorecraftSDK } from '../index.js'
 import { fetchApiWithAuth, url } from './utils.api.fetch.js';
+import { string_array_to_string } from '@storecraft/core/api/query.utils.js';
 
 /**
  * @description **Search** API (two options):

package/src/shipping.js

@@ -6,7 +6,6 @@ import { collection_base } from './utils.api.fetch.js';
 
 /**
  * @description Base `shipping` **CRUD**
- * 
  * @extends {collection_base<ShippingMethodTypeUpsert, ShippingMethodType>}
  */
 export default class Shipping extends collection_base {

package/src/statistics.js

@@ -6,7 +6,7 @@ import { StorecraftSDK } from '../index.js'
 import { fetchApiWithAuth } from './utils.api.fetch.js';
 import { 
   api_query_to_searchparams 
-} from '@storecraft/core/api/utils.query.js';
+} from '@storecraft/core/api/query.js';
 
 /**
  * @description statistics endpoint
@@ -58,7 +58,7 @@ export default class Statistics  {
 
   /**
    * @description Load **count** `statistics`
-   * @param {keyof App["db"]["resources"]} table 
+   * @param {keyof App["__show_me_everything"]["db"]["resources"]} table 
    * @param {ApiQuery} [query]
    * @returns {Promise<number>}
    * @throws

package/src/storefronts.js

@@ -7,7 +7,6 @@ import { collection_base, fetchApiWithAuth } from './utils.api.fetch.js';
 
 /**
  * @description Base `storefronts` **CRUD**
- * 
  * @extends {collection_base<StorefrontTypeUpsert, StorefrontType>}
  */
 export default class Storefronts extends collection_base {

package/src/tags.js

@@ -6,7 +6,6 @@ import { collection_base } from './utils.api.fetch.js';
 
 /**
  * @description Base `tags` **CRUD**
- * 
  * @extends {collection_base<TagTypeUpsert, TagType>}
  */
 export default class Tags extends collection_base {

package/src/templates.js

@@ -6,7 +6,6 @@ import { collection_base } from './utils.api.fetch.js';
 
 /**
  * @description Base `templates` **CRUD**
- * 
  * @extends {collection_base<TemplateTypeUpsert, TemplateType>}
  */
 export default class Templates extends collection_base {

package/src/utils.api.fetch.js

@@ -5,7 +5,7 @@
  */
 import { 
   api_query_to_searchparams 
-} from '@storecraft/core/api/utils.query.js';
+} from '@storecraft/core/api/query.js';
 
 
 /**

package/src/settings.js

@@ -1,18 +0,0 @@
-import { StorecraftSDK } from '../index.js'
-import { collection_base } from './utils.api.fetch.js';
-
-/**
- * @description Base `settings` **CRUD**
- * 
- * @extends {collection_base<any, any>}
- */
-export default class Settings extends collection_base {
-
-  /**
-   * @param {StorecraftSDK} sdk 
-   */
-  constructor(sdk) {
-    super(sdk, 'reference/settings');
-  }
-
-}