@storecraft/sdk 0.1.0

package/README.md

@@ -0,0 +1,132 @@
+# **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`)
+
+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 :)
+
+
+## Authentication
+
+Authentication and authorization is required for some resources, such as:
+- Upserting / Removing (mutations) resources
+- Querying a customer orders
+
+Besides that, most of the resources are public and do not require authentication.
+
+
+There are two strategies for `authentication`:
+
+
+### **Api Key** Authentication
+
+```js
+import { StorecraftSDK } from '@storecraft/sdk'
+
+const sdk = new StorecraftSDK(
+  {
+    backend: 'http://localhost:8000', 
+    auth: {
+      apikey: <YOUR-API-KEY>
+    }
+  }
+)
+
+```
+
+### **JWT** Authentication
+
+You can `sign in`, and the `sdk` will save the `auth` result ans
+will re-authenticate with `refresh token` when needed.
+
+
+```js
+import { StorecraftSDK } from '@storecraft/sdk'
+
+const sdk = new StorecraftSDK(
+  {
+    backend: 'http://localhost:8000', 
+  }
+);
+
+const auth_result = await sdk.auth.signin(email, password);
+
+```
+
+You, can also instantiate the `sdk` with previous authentication 
+information like so:
+
+```js
+import { StorecraftSDK } from '@storecraft/sdk'
+
+const sdk = new StorecraftSDK(
+  {
+    backend: 'http://localhost:8000', 
+    auth: {
+      access_token: <OPTIONAL-ACCESS-TOKEN>,
+      refresh_token: <OPTIONAL-REFRESH-TOKEN>,
+    }
+  }
+)
+
+```
+
+### subscribe to **JWT** auth updates
+
+You can subscribe to auth updates like so:
+
+```js
+import { StorecraftSDK } from '@storecraft/sdk'
+
+const sdk = new StorecraftSDK(
+  {
+    backend: 'http://localhost:8000', 
+  }
+);
+
+sdk.auth.add_sub(
+  ({ auth: ApiAuthResult, isAuthenticated: boolean }) => {
+    // Do something, like save locally
+  }
+);
+
+const auth_result = await sdk.auth.signin(email, password);
+const auth_result = await sdk.auth.signout();
+
+```
+
+
+## Querying
+
+
+Here are some examples for querying
+
+
+```js
+import { StorecraftSDK } from '@storecraft/sdk'
+
+const sdk = new StorecraftSDK();
+
+const products: ProductType[] = await sdk.products.list(
+  {
+    expand: ['collections', 'variants'],
+    sortBy: ['updated_at', 'id'],
+    order: 'desc',
+    startAt: [
+      ['updated_at': '2024-03-24']
+    ],
+    limit: 5,
+    vql: '(keyword1 | keyword2) -(keyword3)'
+  }
+)
+
+```
+
+
+```text
+Author: Tomer Shalev (tomer.shalev@gmail.com)
+```

package/index.js

@@ -0,0 +1,103 @@
+import Auth from './src/auth.js'
+import Customers from './src/customers.js'
+import Tags from './src/tags.js'
+import Templates from './src/templates.js'
+import Products from './src/products.js'
+import Orders from './src/orders.js'
+import Discounts from './src/discounts.js'
+import Collections from './src/collections.js'
+import ShippingMethods from './src/shipping.js'
+import StoreFronts from './src/storefronts.js'
+import Statistics from './src/statistics.js'
+import Images from './src/images.js'
+import Posts from './src/posts.js'
+import Payments from './src/payments.js'
+import Settings from './src/settings.js'
+import Notifications from './src/notifications.js'
+import Bots from './src/bots.js'
+import Storage from './src/storage.js'
+
+
+/**
+ * @typedef {import('@storecraft/core/v-api').ApiAuthResult |
+ *  import('@storecraft/core/v-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
+ */
+
+/**
+ * The official `storecraft` admin **SDK** for `javascript`
+ */
+export class StorecraftSDK {
+
+  /**@type {StorecraftSDKConfig} */
+  #_config = undefined;
+
+  /**
+   * @param {StorecraftSDKConfig} [config] 
+   */  
+  constructor(config) {
+    this.#_config = config;
+
+    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);
+    this.products = new Products(this);
+    this.orders = new Orders(this);
+    this.collections = new Collections(this);
+    this.discounts = new Discounts(this);
+    this.shipping = new ShippingMethods(this);
+    this.storefronts = new StoreFronts(this);
+    this.statistics = new Statistics(this);
+    this.images = new Images(this);
+    this.posts = new Posts(this);
+    this.payments = new Payments(this);
+    this.settings = new Settings(this);
+    this.notifications = new Notifications(this);
+    this.bots = new Bots(this);
+  }
+
+  /**
+   * @param {StorecraftSDKConfig} [config] 
+   */  
+  updateConfig(config) {
+    this.#_config = config;
+  }
+
+  get config() {
+    return this.#_config
+  }
+
+}
+
+/**
+ * @param {StorecraftSDKConfig} config 
+ */
+export const validateConfig = (config) => {
+  return true;
+}
+
+/**
+ * @param {StorecraftSDKConfig} [config] 
+ */  
+export const create = (config) => { 
+  const sdk = new StorecraftSDK(config);
+  
+  return sdk;
+}
+
+
+

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@storecraft/sdk",
+  "version": "0.1.0",
+  "description": "Official storecraft Universal Javascript SDK",
+  "license": "MIT",
+  "author": "Tomer Shalev (https://github.com/store-craft)",
+  "homepage": "https://github.com/store-craft/storecraft",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/store-craft/storecraft.git",
+    "directory": "packages/sdk"
+  },
+  "keywords": [
+    "commerce",
+    "dashboard",
+    "code",
+    "storecraft"
+  ],
+  "scripts": {
+    "sdk:test": "echo \"Error: no test specified\" && exit 1",
+    "sdk:publish": "npm publish --access public"
+  },
+  "type": "module",
+  "types": "./types.d.ts",
+  "main": "./index.js",
+  "dependencies": {
+    "@storecraft/core": "^1.0.0"
+  }
+}

package/src/auth.js

@@ -0,0 +1,382 @@
+import { api_query_to_searchparams } from '@storecraft/core/v-api/utils.query.js';
+import { StorecraftSDK } from '../index.js';
+import { fetchApiWithAuth, url } from './utils.api.fetch.js';
+import { assert } from './utils.functional.js';
+
+
+/**
+ * 
+ * @typedef {import('../index.js').SdkConfigAuth} SdkConfigAuth
+ * 
+ * 
+ * @typedef {object} SubscriberCallbackPayload
+ * @prop {SdkConfigAuth} auth
+ * @prop {boolean} isAuthenticated
+ * 
+ * 
+ * @typedef {(payload: SubscriberCallbackPayload) => void
+ * } SubscriberCallback Subscribe to `auth` updates for `JWT` auth
+ * 
+ */
+  
+  
+/**
+ * `Storecraft` authentication module:
+ * - Supports `subscribtion` to `auth` events
+ * 
+ */
+export default class Auth {
+
+  /**@type {Set<SubscriberCallback>} */
+  #subscribers = new Set();
+
+  /** @type {StorecraftSDK} */
+  #sdk;
+
+  /**
+   * 
+   * @param {StorecraftSDK} sdk 
+   */
+  constructor(sdk) {
+    this.#sdk = sdk
+  }
+
+  /**
+   * 
+   * Get the current `auth` config, which is one of:
+   * 
+   * 1. `JWT` with `access_token`, `refresh_token`, `claims`
+   * 2. `Api Key` with a single value, which can be used as is in:
+   *    - `Authorization: Basic <api-key>`, or
+   *    - `X-API-KEY: <api-key>`
+   * 
+   * Notes:
+   * 
+   * **JWT** is always recommended and is performing faster once you gain an
+   * `access_token`.
+   * 
+   * **Api Key** represents a user which always makes the `backend` to verify
+   * the authentication and authorization and therefore may be slower, because
+   * the `backend` will verify against the database.
+   * 
+   */
+  get currentAuth() {
+    return this.#sdk?.config?.auth;
+  }
+
+  /**
+   * @param {import('../index.js').SdkConfigAuth} value 
+   */
+  set currentAuth(value) {
+    this.#sdk.config.auth = value;
+  }
+
+
+  init() {
+  }
+
+  /**
+   * 
+   * Get a working token, by the following strategy:
+   * 
+   * - If you are in `JWT` strategy:
+   *    - If the current `access_token` will expire soon or is already expired
+   *    - then, use `refresh_token` to re-authenticate
+   * 
+   * - If you are in `Api Key` strategy, simply returns the `apikey`
+   * 
+   * @param {boolean} [force_reauth=false] 
+   * 
+   */
+  async working_auth_token(force_reauth=false) {
+    if(this.currentAuth) {
+      if('apikey' in this.currentAuth) {
+        return this.currentAuth.apikey;
+      }
+      else if('access_token' in this.currentAuth) {
+        if(force_reauth || !this.isAuthenticated)
+          await this.reAuthenticateIfNeeded(force_reauth);
+        return this.currentAuth.access_token.token;
+      }
+    }
+
+    return undefined;
+  }
+
+
+  /**
+   * 
+   * Perform re-authentication for `JWT` auth, which means:
+   * 
+   * - use the `refresh_token` to gain a new `access_token`
+   * 
+   * @param {boolean} [force=false] 
+   * 
+   */
+  async reAuthenticateIfNeeded(force=false) {
+    if(!this.currentAuth)
+      return;
+    
+    if(this.isAuthenticated && !force)
+      return;
+
+    if('access_token' in this.currentAuth) {
+      const auth_res = await fetch(
+        url(this.#sdk.config, '/auth/refresh'),
+        {
+          method: 'post',
+          body: JSON.stringify(
+            {
+              refresh_token: this.currentAuth.refresh_token.token
+            }
+          ),
+          headers: {
+            'Content-Type': 'application/json'
+          }
+        }
+      );
+
+      /** @type {import('@storecraft/core/v-api').ApiAuthResult} */
+      let payload = undefined;
+
+      if(auth_res.ok) {
+        payload = await auth_res.json();
+      }
+
+      this.#_update_and_notify_subscribers(payload);
+
+      return payload;
+    }
+  }
+
+  notify_subscribers = () => {
+    // console.log('this.isAuthenticated', this.isAuthenticated)
+    for(let s of this.#subscribers) {
+      s(
+        {
+          auth: this.currentAuth, 
+          isAuthenticated: this.isAuthenticated
+        }
+      );
+    
+    }
+  }
+  
+  /**
+   * @param {SubscriberCallback} cb 
+   * @returns {() => void} unsubscribe function
+   */
+  add_sub = cb => {
+    this.#subscribers.add(cb);
+
+    return () => {
+      this.#subscribers.delete(cb)
+    }
+  }
+
+  get authStrategy() {
+    if(this.currentAuth) {
+      if('apikey' in this.currentAuth)
+        return 'apikey';
+      else if('access_token' in this.currentAuth)
+        return 'jwt';
+    }
+
+    return 'unknown';
+  }
+
+  get isAuthenticated() {
+    
+    if(this.currentAuth) {
+      if('apikey' in this.currentAuth) {
+        return Boolean(this.currentAuth.apikey);
+      }
+      else if('access_token' in this.currentAuth) {
+        const exp = this.currentAuth?.access_token?.claims?.exp;
+        
+        return exp && (Date.now() < (exp - 60)*1000);
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * 
+   * @param {import('@storecraft/core/v-api').ApiAuthResult} user 
+   */
+  #_update_and_notify_subscribers = (user) => {
+    this.currentAuth = user
+    this.notify_subscribers();
+  }
+
+
+  /**
+   * 
+   * @param {string} email 
+   * @param {string} password 
+   * 
+   * 
+   * @returns {Promise<import('@storecraft/core/v-api').ApiAuthResult>}
+   */
+  signin = async (email, password) => {
+    // console.log('ep ', email, password)
+
+    /** @type {import('@storecraft/core/v-api').ApiAuthSigninType} */
+    const info = {
+      email, password
+    }
+
+    const res = await fetch(
+      url(this.#sdk.config, `/auth/signin`),
+      { 
+        method: 'post',
+        body: JSON.stringify(info),
+        headers: {
+          'Content-Type' : 'application/json'
+        }
+      }
+    );
+    
+    assert(res.ok, 'auth/error');
+
+    /** @type {import('@storecraft/core/v-api').ApiAuthResult} */
+    const payload = await res.json();
+
+    // console.log('auth_result', payload)
+
+    this.#_update_and_notify_subscribers(
+      payload
+    );
+
+    return payload;
+  }
+
+
+  /**
+   * 
+   * @param {string} email 
+   * @param {string} password 
+   */
+  signup = async (email, password) => {
+    /** @type {import('@storecraft/core/v-api').ApiAuthSignupType} */
+    const info = {
+      email, password
+    }
+
+    const res = await fetch(
+      url(this.#sdk.config, `/auth/signup`),
+      { 
+        method: 'post',
+        body: JSON.stringify(info),
+        headers: {
+          'Content-Type' : 'application/json'
+        }
+      }
+    );
+    
+    assert(res.ok, 'auth/error');
+
+    /** @type {import('@storecraft/core/v-api').ApiAuthResult} */
+    const payload = await res.json();
+
+    this.#_update_and_notify_subscribers(
+      payload
+    );
+
+    return payload;
+  }
+
+
+  signout = async () => {
+    console.log('signout');
+
+    this.#_update_and_notify_subscribers(
+      undefined
+    );
+
+  }
+
+
+  create_api_key = async () => {
+    /** @type {import('@storecraft/core/v-api').ApiKeyResult} */
+    const item = await fetchApiWithAuth(
+      this.#sdk,
+      '/auth/apikeys',
+      {
+        method: 'post'
+      }
+    );
+
+    return item.apikey;
+  }
+
+
+  /**
+   * 
+   * 
+   * @param {string} email_or_id
+   */
+  get_auth_user = async (email_or_id) => {
+    /** @type {import('@storecraft/core/v-api').AuthUserType} */
+    const item = await fetchApiWithAuth(
+      this.#sdk,
+      `/auth/users/${email_or_id}`,
+      {
+        method: 'get'
+      }
+    );
+
+    return item;
+  }
+
+  /**
+   * 
+   * 
+   * @param {string} email_or_id
+   * 
+   */
+  remove_auth_user = async (email_or_id) => {
+    return fetchApiWithAuth(
+      this.#sdk,
+      `/auth/users/${email_or_id}`,
+      {
+        method: 'delete'
+      }
+    );
+  }
+
+  /**
+   * 
+   * 
+   * @param {import('@storecraft/core/v-api').ApiQuery} query
+   * 
+   */
+  list_auth_users = async (query) => {
+    const sq = api_query_to_searchparams(query);
+
+    return fetchApiWithAuth(
+      this.#sdk,
+      `/auth/users?${sq.toString()}`,
+      {
+        method: 'get'
+      }
+    );
+  }
+
+
+  list_api_keys_auth_users = async () => {
+
+    /** @type {import('@storecraft/core/v-api').AuthUserType[]} */
+    const items = await fetchApiWithAuth(
+      this.#sdk,
+      '/auth/apikeys',
+      {
+        method: 'get'
+      }
+    );
+
+    return items;
+  }
+
+}