@storecraft/sdk 1.0.8 → 1.0.10

package/README.md

@@ -10,9 +10,36 @@ which means you can you it both at browser and at backend runtimes such (`node`
 
 It will allow you to fetch / mutate all of the resources at the `backend` in a 
 convenient manner with `javascript`, such as:
-`products`, `collections`, `authentication`, `customers`, `orders`, `discounts`,
-`storage`, `storefronts`, `shipping`, `statistics`, `tags`, `posts`, `notifications`,
-`templates`, `extensions` and more :)
+
+#### collections
+`products`, `collections`, `auth_users`, `customers`, `orders`, `discounts`,
+`storefronts`, `shipping`, `tags`, `posts`, `notifications`,
+`templates`, `extensions`, `images`
+
+#### Auth
+Perform authentication such as `signin` / `signup` / `api-key`
+
+#### Checkout
+Perform checkout `create` / `complete`
+
+#### Storage
+Perform storage operations such as `put` / `get` / `delete`
+
+#### Payments
+Perform payments `status-check` / `invoke-action`
+
+#### Statistics
+- Query some basic statistics about `orders` in a time span
+- Query count of items in collections
+
+#### AI
+Speak with a `storecraft` agent (Supports streaming :))
+
+<hr/>
+
+Start by installing, 
+
+Plus, everything is typed so you dont have to guess any parameter or queryable key
 
 ```bash
 npm i @storecraft/sdk
@@ -111,10 +138,14 @@ const auth_result = await sdk.auth.signout();
 ## Querying
 
 
-Here are some examples for querying
+Here are some examples for querying.
 
+- Every key and string in the example below is fully typed with `typescript`,
+- so you get **intellisense** out of the box for better developer experience
+- And, you don't have to guess anything
 
-```js
+
+```ts
 import { StorecraftSDK } from '@storecraft/sdk'
 
 const sdk = new StorecraftSDK();
@@ -122,10 +153,10 @@ const sdk = new StorecraftSDK();
 const products: ProductType[] = await sdk.products.list(
   {
     expand: ['collections', 'variants'],
-    sortBy: ['updated_at', 'id'],
+    sortBy: ['updated_at', 'id'], // all keys will show up in intellisense
     order: 'desc',
     startAt: [
-      ['updated_at': '2024-03-24']
+      ['updated_at': '2024-03-24'],
     ],
     limit: 5,
     vql: '(keyword1 | keyword2) -(keyword3)'
@@ -134,6 +165,21 @@ const products: ProductType[] = await sdk.products.list(
 
 ```
 
+Or, 
+
+```ts
+import { StorecraftSDK } from '@storecraft/sdk'
+
+const sdk = new StorecraftSDK();
+
+const collections: CollectionType[] = await sdk.collections.list(
+  {
+    equals: [['active': true]]
+    limit: 5,
+  }
+);
+
+```
 
 ```text
 Author: Tomer Shalev (tomer.shalev@gmail.com)

package/index.js

@@ -16,6 +16,7 @@ import Payments from './src/payments.js'
 import Settings from './src/settings.js'
 import Notifications from './src/notifications.js'
 import Storage from './src/storage.js'
+import AI from './src/ai.js'
 
 
 /**
@@ -49,6 +50,7 @@ export class StorecraftSDK {
   constructor(config) {
     this.#_config = config;
 
+    this.ai = new AI(this);
     this.auth = new Auth(this);
     this.storage = new Storage(this);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storecraft/sdk",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Official storecraft Universal Javascript SDK",
   "license": "MIT",
   "author": "Tomer Shalev (https://github.com/store-craft)",
@@ -19,6 +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"
   },
   "type": "module",

package/src/ai.js

@@ -0,0 +1,171 @@
+/**
+ * @import { 
+ *  AgentRunParameters, AgentRunResponse 
+ * } from '@storecraft/core/ai/agents/types.js'
+ * @import { content } from '@storecraft/core/ai/types.public.js'
+ */
+
+import { HEADER_STORECRAFT_THREAD_ID } from '../../core/rest/con.ai.routes.js';
+import { StorecraftSDK } from '../index.js'
+import { url } from './utils.api.fetch.js';
+
+/**
+ * @description **AI**
+ * 
+ */
+export default class AI {
+
+  /**
+   * 
+   * @param {StorecraftSDK} sdk 
+   */
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * @description Speak with the main `storecraft` agent sync. It is
+   * recommended to use the streamed version {@link streamSpeak}
+   * @param {AgentRunParameters} params 
+   * @returns {Promise<AgentRunResponse>}
+   */
+  speak = async (params) => {
+    const response = await fetch(
+      url(this.sdk.config, 'ai/agent/run'),
+      {
+        method: 'post',
+        body: JSON.stringify(params),
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      }
+    );
+
+    return response.json();
+  }
+
+  /**
+   * @description Stream Speak with the main `storecraft` agent via Server-Sent Events
+   * @param {AgentRunParameters} params 
+   */
+  streamSpeak = async function(params) {
+    const response = await fetch(
+      url(this.sdk.config, 'ai/agent/stream'),
+      {
+        method: 'post',
+        body: JSON.stringify(params),
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      }
+    );
+
+    const threadId = response.headers.get(HEADER_STORECRAFT_THREAD_ID ?? 'X-Storecraft-Thread-Id');
+
+    if(!threadId) {
+      throw new Error(
+        `X-Storecraft-Thread-Id is missing, please tell the backend admin to 
+        change the cors' Access-Control-Expose-Headers to accept the header`
+      )
+    }
+    
+    return {
+      threadId,
+      generator: () => StreamSpeakGenerator(response.body)
+    }
+  }
+
+}
+
+const sleep = (ms=100) => {
+  return new Promise(
+    (resolve, reject) => {
+      setTimeout(
+        resolve, ms
+      )
+    }
+  )
+}
+
+/**
+ * @description Server Sent Events async generator
+ * @param {ReadableStream} stream web stream
+ */
+const StreamSpeakGenerator = async function *(stream) {
+  for await (const sse of SSEGenerator(stream)) {
+    await sleep(50);
+    yield ( /** @type {content} */ (JSON.parse(sse.data)));
+  }
+}
+
+/**
+ * @description Server Sent Events async generator
+ * @param {ReadableStream} stream web stream
+ */
+export const SSEGenerator = async function *(stream) {
+
+  let active_frame = [];
+  let residual_line = '';
+
+  const reader = stream.getReader();
+  let current = await reader.read();
+
+  while(!current.done) {
+    
+    let text = (new TextDecoder()).decode(current.value); 
+    // console.log('text \n\n', text)
+  
+    if(residual_line) {
+      text = residual_line + text;
+      residual_line = '';
+    }
+  
+    const lines = text.split(/\r\n|\n|\r/).map(l => l.trim());
+  
+    for(const line of lines) {
+      if(line==='' && active_frame.length) {
+        // console.log('frame \n\n', active_frame)
+        // empty line means processing and dispatch
+        yield parse_frame(active_frame);
+        active_frame = [];
+      } else {
+        active_frame.push(line);
+      }
+    }
+  
+    // if we got here and we have a line, then it
+    // was not finished (Otherwise, it would have been parsed and dispatched)
+    // I will need to prepend it to the next batch as it is incomplete
+    residual_line = active_frame.pop();
+
+    current = await reader.read();
+  }
+
+}
+
+
+
+/**
+ * @typedef {object} SSEFrame Server Sent Events frame
+ * @prop {string} [data]
+ * @prop {string} [event]
+ */
+
+/**
+ * 
+ * @param {string[]} lines 
+ * @returns {SSEFrame}
+ */
+const parse_frame = (lines) => {
+  return Object.fromEntries(
+    lines.map(
+      (l) => {
+        const delimiter = l.indexOf(':');
+        return [
+          l.slice(0, delimiter).trim(),
+          l.slice(delimiter + 1).trim(),
+        ]
+      }
+    )
+  );
+}

package/src/auth.js

@@ -1,3 +1,10 @@
+/**
+ * @import {
+ *  ApiAuthChangePasswordType, ApiAuthResult, ApiAuthSigninType, ApiAuthSignupType, 
+ *  ApiKeyResult, ApiQuery, AuthUserType, error
+ * } from '@storecraft/core/api'
+ */
+
 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';
@@ -136,7 +143,7 @@ export default class Auth {
         }
       );
 
-      /** @type {import('@storecraft/core/api').ApiAuthResult} */
+      /** @type {ApiAuthResult} */
       let payload = undefined;
 
       if(auth_res.ok) {
@@ -203,7 +210,7 @@ export default class Auth {
 
   /**
    * 
-   * @param {import('@storecraft/core/api').ApiAuthResult} user 
+   * @param {ApiAuthResult} user 
    */
   #_update_and_notify_subscribers = (user) => {
     this.currentAuth = user
@@ -217,12 +224,12 @@ export default class Auth {
    * @param {string} password 
    * 
    * 
-   * @returns {Promise<import('@storecraft/core/api').ApiAuthResult>}
+   * @returns {Promise<ApiAuthResult>}
    */
   signin = async (email, password) => {
     // console.log('ep ', email, password)
 
-    /** @type {import('@storecraft/core/api').ApiAuthSigninType} */
+    /** @type {ApiAuthSigninType} */
     const info = {
       email, password
     }
@@ -239,7 +246,7 @@ export default class Auth {
     );
     
     if(!res.ok) {
-      /** @type {import('@storecraft/core/api').error} */
+      /** @type {error} */
       let error_payload = {
         messages: [
           {
@@ -257,7 +264,7 @@ export default class Auth {
     }    
     // assert(res.ok, 'auth/error2');
 
-    /** @type {import('@storecraft/core/api').ApiAuthResult} */
+    /** @type {ApiAuthResult} */
     const payload = await res.json();
 
     // console.log('auth_result', payload)
@@ -278,7 +285,7 @@ export default class Auth {
    * @param {string} [lastname] 
    */
   signup = async (email, password, firstname, lastname) => {
-    /** @type {import('@storecraft/core/api').ApiAuthSignupType} */
+    /** @type {ApiAuthSignupType} */
     const info = {
       email, password,
       firstname, lastname
@@ -297,7 +304,7 @@ export default class Auth {
     
     assert(res.ok, 'auth/error');
 
-    /** @type {import('@storecraft/core/api').ApiAuthResult} */
+    /** @type {ApiAuthResult} */
     const payload = await res.json();
 
     this.#_update_and_notify_subscribers(
@@ -310,7 +317,7 @@ export default class Auth {
 
   /**
    * 
-   * @param {import('@storecraft/core/api').ApiAuthChangePasswordType} params 
+   * @param {ApiAuthChangePasswordType} params 
    */
   
   changePassword = async (params) => {
@@ -327,7 +334,7 @@ export default class Auth {
     );
     
     if(!res.ok) {
-      /** @type {import('@storecraft/core/api').error} */
+      /** @type {error} */
       let error_payload = {
         messages: [
           {
@@ -344,7 +351,7 @@ export default class Auth {
       throw error_payload;
     }
 
-    /** @type {import('@storecraft/core/api').ApiAuthResult} */
+    /** @type {ApiAuthResult} */
     const payload = await res.json();
 
     this.#_update_and_notify_subscribers(
@@ -367,7 +374,7 @@ export default class Auth {
 
 
   create_api_key = async () => {
-    /** @type {import('@storecraft/core/api').ApiKeyResult} */
+    /** @type {ApiKeyResult} */
     const item = await fetchApiWithAuth(
       this.#sdk,
       '/auth/apikeys',
@@ -386,7 +393,7 @@ export default class Auth {
    * @param {string} email_or_id
    */
   get_auth_user = async (email_or_id) => {
-    /** @type {import('@storecraft/core/api').AuthUserType} */
+    /** @type {AuthUserType} */
     const item = await fetchApiWithAuth(
       this.#sdk,
       `/auth/users/${email_or_id}`,
@@ -417,25 +424,26 @@ export default class Auth {
   /**
    * 
    * 
-   * @param {import('@storecraft/core/api').ApiQuery} query
+   * @param {ApiQuery<AuthUserType>} query
    * 
    */
   list_auth_users = async (query) => {
     const sq = api_query_to_searchparams(query);
-
-    return fetchApiWithAuth(
+    /** @type {AuthUserType[]} */
+    const items = await fetchApiWithAuth(
       this.#sdk,
       `/auth/users?${sq.toString()}`,
       {
         method: 'get'
       }
     );
+    return items;
   }
 
 
   list_api_keys_auth_users = async () => {
 
-    /** @type {import('@storecraft/core/api').AuthUserType[]} */
+    /** @type {AuthUserType[]} */
     const items = await fetchApiWithAuth(
       this.#sdk,
       '/auth/apikeys',

package/src/payments.js

@@ -62,7 +62,8 @@ export default class Payments {
   
   /**
    * 
-   * Invoke a `payment gateway` action on `order`
+   * Invoke a `payment gateway` action on `order`. The list of available actions can be found
+   * using {@link get} or {@link paymentStatusOfOrder}
    * 
    * 
    * @param {string} action_handle The `action` handle at the gateway

package/src/utils.api.fetch.js

@@ -183,7 +183,7 @@ export async function remove(sdk, resource, handle_or_id) {
  * 
  * @param {import('../index.js').StorecraftSDK} sdk
  * @param {string} resource base path of resource
- * @param {import('@storecraft/core/api').ApiQuery} [query] 
+ * @param {import('@storecraft/core/api').ApiQuery<G>} [query] 
  * 
  * 
  * @returns {Promise<G[]>}
@@ -262,7 +262,7 @@ export class collection_base {
 
   /**
    * 
-   * @param {import('@storecraft/core/api').ApiQuery} query Query object
+   * @param {import('@storecraft/core/api').ApiQuery<G>} query Query object
    * 
    * 
    * @returns {Promise<G[]>}

package/src/utils.functional.js

@@ -89,7 +89,9 @@ export const text2tokens = (text) => {
   // let tokens = text?.toString().toLowerCase().match(/[^\W_]+/g)
   let tokens = text?.toString().toLowerCase().match(/[\p{L}\d]+/gu)
 
+  // @ts-ignore
   tokens = tokens ?? []
+  // @ts-ignore
   tokens = tokens.filter(
     t => !STOP_WORDS.includes(t)
   )