@storecraft/sdk 1.0.17 → 1.3.0

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,7 +211,7 @@ const sdk = new StorecraftSDK();
 
 const collections: CollectionType[] = await sdk.collections.list(
   {
-    equals: [['active': true]]
+    vql: 'active=true & (nintendo | playstation)'
     limit: 5,
   }
 );
@@ -195,7 +226,6 @@ 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

@@ -21,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 Chats from './src/chats.js'
 import { 
   fetchApiWithAuth, fetchOnlyApiResponseWithAuth 
 } from './src/utils.api.fetch.js'
@@ -45,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);
@@ -68,6 +70,7 @@ export class StorecraftSDK {
     this.reference = new Reference(this);
     this.notifications = new Notifications(this);
     this.emails = new Email(this);
+    this.chats = new Chats(this);
   }
 
   get fetcher() {
@@ -111,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;
+  }
 }
 
 /**
@@ -136,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.17",
+  "version": "1.3.0",
   "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/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) => {
@@ -70,7 +66,7 @@ export default class Checkout {
    * @description calculate the pricing of an `order`. 
    * Using auto-discounts, coupons, shipping and line-items.
    * @param {CheckoutCreateTypeAfterValidation} order 
-   * @returns {Promise<Partial<PricingData>>}
+   * @returns {Promise<Partial<Pick<OrderData, "pricing" | "validation">>>}
    */
   pricing = async (order) => {
 

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

@@ -7,7 +7,6 @@ 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/payments.js

@@ -6,7 +6,8 @@
 import { StorecraftSDK } from '../index.js'
 import { 
   fetchApiWithAuth, get_from_collection_resource, 
-  list_from_collection_resource 
+  list_from_collection_resource, 
+  url
 } from './utils.api.fetch.js';
 
 /**
@@ -94,6 +95,18 @@ export default class Payments {
     )
   }
     
+  /**
+   * Get an optional HTML Pay UI of the `payment gateway`
+   * @param {string} order_id the `id` of the `order`
+   * @returns {string} buy UI url
+   */
+  getBuyUiUrl(order_id) {
+    return url(
+      this.sdk.config, 
+      `/payments/buy_ui/${order_id}`
+    );
+  }
+  
   /**
    * invoke the webhook endpoint for async payment
    * @param {string} gateway_handle The handle of the `payment gateway`

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

@@ -1,5 +1,5 @@
 /**
- * @import { StorecraftConfig } from '@storecraft/core'
+ * @import { App, StorecraftConfig } from '@storecraft/core'
  * @import { StorecraftAppPublicInfo } from '@storecraft/core/api'
  */
 import { StorecraftSDK } from '../index.js'
@@ -24,7 +24,7 @@ export default class Reference {
     /** @type {StorecraftConfig} */
     const json = await fetchApiWithAuth(
       this.sdk,
-      'reference/settings',
+      'settings',
       { method: 'get' },
     );
     return json;
@@ -37,7 +37,7 @@ export default class Reference {
     /** @type {StorecraftAppPublicInfo} */
     const json = await fetchApiWithAuth(
       this.sdk,
-      'reference/info',
+      'info',
       { method: 'get' },
     );
     return json;

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

@@ -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 {