@thinkingdifferently/core 1.1.0 → 1.3.0

package/dist/index.mjs

@@ -1,29 +1,172 @@
 // src/client.ts
 import axios from "axios";
 var TDClient = class {
-  constructor(apiKey) {
+  constructor(apiKey, securityKey, publicKey) {
+    this.adminToken = null;
+    this.apikey = apiKey;
+    this.securityKey = securityKey;
+    this.publicKey = publicKey;
     this.api = axios.create({
-      baseURL: "https://www.thinkingdifferently.dev/api/v1",
+      baseURL: "http://localhost:3000/api/v1",
+      // baseURL: "https://www.thinkingdifferently.dev/api/v1",
       headers: {
-        "x-api-key": apiKey,
+        "X-API-Key": apiKey,
         "Content-Type": "application/json"
-      }
+      },
+      withCredentials: true
+      // Enable browser cookie sharing automatically
     });
   }
-  async request(method, body) {
+  //what is hte use of withCredentials: true in axios config?
+  //The withCredentials: true option in the Axios configuration is used to indicate that cross-site Access-Control requests should be made using credentials such as cookies,
+  // authorization headers, or TLS client certificates. When this option is set to true, it allows the browser to include cookies and other credentials in requests made to
+  // a different domain than the one serving the web page. This is particularly important for maintaining sessions and authentication when making API calls to a backend server
+  // that is on a different domain than the frontend application.
+  setSecurityKey(key) {
+    this.securityKey = key;
+  }
+  setPublicKey(key) {
+    this.publicKey = key;
+  }
+  setAdminToken(token) {
+    this.adminToken = token;
+  }
+  getAdminToken() {
+    return this.adminToken;
+  }
+  getPublicKey() {
+    return this.publicKey;
+  }
+  /**
+   * Reusable private error formatting utility
+   */
+  // private handleError(error: any): Error {
+  //     if (error.response && error.response.data && error.response.data.error) {
+  //         const backendError = error.response.data.error;
+  //
+  //         let errorMessage = `[ThinkingDifferently SDK Error] ${backendError.code || error.response.status}: ${backendError.message}`;
+  //
+  //         if (backendError.details) {
+  //             errorMessage += `\nDetails: ${JSON.stringify(backendError.details, null, 2)}`;
+  //         }
+  //
+  //         return new Error(errorMessage);
+  //     }
+  //
+  //     return new Error(
+  //         `[ThinkingDifferently Network Error] ${error.message || "Could not connect to the API."}`
+  //     );
+  // }
+  //why if everything fails then we say that could not connect to the api? is it because we assume that if it's not a structured error from the backend, then it's likely a network or connectivity issue?
+  //explain: Yes, that's correct. The rationale behind returning a generic "Could not connect to the API" message when the error doesn't match the expected structured format from the backend is based on the assumption that if the error isn't coming from the API in a recognizable way, it's likely due to a network issue or some other problem preventing communication with the server.
+  // In a well-designed API, errors should be returned in a consistent format (e.g., with an "error" object containing "code" and "message").
+  // If the error doesn't conform to this structure, it suggests that the request may not have reached the server at all, or there was a failure in the network layer (like DNS issues, server downtime, CORS errors, etc.). Therefore, providing a generic message helps guide developers towards checking their network connection or server status when they encounter such unstructured errors.
+  //what if the developer of server forgets to send the error in this structured format? then the sdk will always say could not connect to the api even if the api is working fine but the error is not structured properly. so how can we improve this error handling to be more robust and informative?
+  // To improve the error handling and make it more robust and informative, we can implement a few strategies:
+  // 1. **Log the Raw Error**: Always log the raw error object to the console or a logging service. This way, developers can see the full context of the error, even if it's not structured.
+  // 2. **Check for Common Error Patterns**: Instead of only checking for a specific structured format, we can look for common patterns in error responses (like status codes, message fields, etc.) to provide more context.
+  // 3. **Fallback Messages**: If the error doesn't match the expected structure, we can provide a fallback message that includes any available information from the error object (like status code or message) instead of just saying "Could not connect to the API."
+  // 4. **Documentation and Guidelines**: Encourage backend developers to follow a consistent error response format through documentation and guidelines. This can help ensure that errors are structured properly, making it easier for the SDK to handle them effectively.
+  // Here's an improved version of the error handling method:
+  handleError(error) {
+    console.error("[ThinkingDifferently SDK] Raw Error:", error);
+    if (error.response) {
+      const status = error.response.status;
+      const data = error.response.data;
+      if (data && data.error) {
+        const backendError = data.error;
+        let errorMessage = `[ThinkingDifferently SDK Error] ${backendError.code || status}: ${backendError.message}`;
+        if (backendError.details) {
+          errorMessage += `
+Details: ${JSON.stringify(backendError.details, null, 2)}`;
+        }
+        return new Error(errorMessage);
+      }
+      return new Error(`[ThinkingDifferently SDK Error] HTTP ${status}: ${data.message || "An error occurred."}`);
+    }
+    return new Error(
+      `[ThinkingDifferently Network Error] ${error.message || "Could not connect to the API."}`
+    );
+  }
+  /**
+   * Handles authentication HTTP requests targeting /auth/admin/login
+   */
+  async adminLogin(adminEmail, password) {
+    try {
+      const response = await this.api.post("/auth/admin/login", {
+        adminEmail,
+        password
+      });
+      const { token } = response.data;
+      if (token) {
+        this.setAdminToken(token);
+      }
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error);
+    }
+  }
+  /**
+   * Determines if an API request is a database write operation.
+   */
+  isWriteOperation(method, body) {
+    if (method === "GET") return false;
+    if (method === "PATCH" || method === "DELETE") return true;
+    if (body) {
+      if (typeof FormData !== "undefined" && body instanceof FormData) {
+        return true;
+      }
+      const query = body.query;
+      if (query) {
+        const parsed = typeof query === "string" ? JSON.parse(query) : query;
+        if (parsed && parsed.operation === "find") {
+          return false;
+        }
+      }
+    }
+    return true;
+  }
+  /**
+   * Executes queries and mutations against /data endpoint.
+   */
+  async sendDataRequest(method, body) {
+    if (this.isWriteOperation(method, body)) {
+      const isBrowser = typeof window !== "undefined";
+      if (!isBrowser && !this.securityKey && !this.adminToken) {
+        throw new Error(
+          "[ThinkingDifferently SDK Error] Write operations require either a valid Security Key or an Admin Session Token."
+        );
+      }
+    }
     try {
-      const isFormData = body instanceof FormData;
+      const isFormData = typeof FormData !== "undefined" && body instanceof FormData;
+      const headers = {};
+      if (!isFormData) {
+        headers["Content-Type"] = "application/json";
+      }
+      if (this.securityKey) {
+        headers["x-security-key"] = this.securityKey;
+      }
+      if (this.adminToken) {
+        headers["x-admin-token"] = this.adminToken;
+      }
+      if (isFormData) {
+        body.append("key", this.apikey);
+      } else {
+        body = {
+          key: this.apikey,
+          query: body
+        };
+      }
       const response = await this.api.request({
         url: "/data",
         method,
-        headers: isFormData ? {} : { "Content-Type": "application/json" },
+        headers,
         ...method === "GET" ? { params: body } : { data: body }
       });
       return response.data;
     } catch (error) {
-      throw new Error(
-        error?.response?.data?.message || "Something went wrong"
-      );
+      throw this.handleError(error);
     }
   }
 };
@@ -33,6 +176,7 @@ var QueryBuilder = class {
   constructor(collection, client) {
     this.client = client;
     this.query = {
+      operation: null,
       collection,
       filters: [],
       limit: null,
@@ -66,11 +210,39 @@ var QueryBuilder = class {
   // build() {
   //     return this.query;
   // }
+  //to do writing the count method for the query builder
+  //the conditions are specified , so now the count method should return the number of documents that match the specified conditions in the query builder
+  //means count will first get the data based on the filters and then return the length of the data array as the count of matching documents
+  async count() {
+    this.query.operation = "count";
+    console.log("\n================ COUNT REQUEST ================");
+    console.log("[SDK] Final Query:", this.query);
+    try {
+      const response = await this.client.sendDataRequest(
+        "POST",
+        this.query
+      );
+      return response.count;
+    } catch (error) {
+      console.error("[SDK] COUNT ERROR");
+      console.error(error);
+      throw error;
+    }
+  }
+  toJSON() {
+    return structuredClone(this.query);
+  }
   async get() {
+    if (arguments.length > 0) {
+      throw new Error(
+        "[ThinkingDifferently SDK Error] The .get() method takes no arguments. Please use chainable methods like .where() and .limit()."
+      );
+    }
+    this.query.operation = "find";
     console.log("\n================ GET REQUEST ================");
     console.log("[SDK] Final Query:", this.query);
     try {
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "POST",
         this.query
       );
@@ -78,45 +250,242 @@ var QueryBuilder = class {
       if (!Array.isArray(response.data)) {
         throw new Error("Invalid response format");
       }
-      const parsed = response.data.map(
-        (item) => item.data
-      );
-      console.log("[SDK] Parsed Data:", parsed);
-      return parsed;
+      console.log("sdk response ", response);
+      console.log("[SDK] Data:", response.data);
+      return response.data;
     } catch (error) {
       console.error("[SDK] GET ERROR");
       console.error(error);
       throw error;
     }
   }
-  //to do writing the count method for the query builder
-  //the conditions are specified , so now the count method should return the number of documents that match the specified conditions in the query builder
-  //means count will first get the data based on the filters and then return the length of the data array as the count of matching documents
-  async count() {
-    console.log("\n================ COUNT REQUEST ================");
-    console.log("[SDK] Final Query for Count:", this.query);
+  async insert(data) {
+    this.query.operation = "insert";
+    console.log("\n================ INSERT REQUEST ================");
     try {
-      const response = await this.client.request(
-        "POST",
-        {
-          ...this.query,
-          countOnly: true
-          // Indicate we only want the count
+      if (data instanceof FormData) {
+        console.log("[SDK] FormData detected");
+        const payload = new FormData();
+        const extractedData = {};
+        for (const [key, value] of data.entries()) {
+          if (value instanceof File) {
+            payload.append(
+              key,
+              value
+            );
+          } else {
+            extractedData[key] = value;
+          }
         }
-      );
-      console.log("[SDK] Count Response:", response);
-      if (typeof response.count !== "number") {
-        throw new Error("Invalid count response from API");
+        this.query.data = extractedData;
+        payload.append(
+          "query",
+          JSON.stringify(this.query)
+        );
+        console.log("[SDK] Query:", this.query);
+        return await this.client.sendDataRequest(
+          "POST",
+          payload
+        );
       }
-      return response.count;
+      this.query.data = data;
+      console.log("[SDK] Final Query:", this.query);
+      return await this.client.sendDataRequest(
+        "POST",
+        this.query
+      );
     } catch (error) {
-      console.error("[SDK] COUNT ERROR");
+      console.error("[SDK] INSERT ERROR");
       console.error(error);
       throw error;
     }
   }
-  toJSON() {
-    return structuredClone(this.query);
+  async UpdateById(id, data) {
+    this.query.operation = "update";
+    this.query.id = id;
+    this.query.data = data;
+    console.log("\n================ UPDATE REQUEST ================");
+    console.log("[SDK] Final Query:", this.query);
+    try {
+      const response = await this.client.sendDataRequest(
+        "PATCH",
+        this.query
+      );
+      console.log("[SDK] Update Response:", response);
+      return response;
+    } catch (error) {
+      console.error("[SDK] UPDATE ERROR");
+      console.error(error);
+      throw error;
+    }
+  }
+  //updateMany
+  // its just like the get() it will call hte client
+  //example sdk.collection("animals").where("price", ">", 1000).updateMany({status : "expensive"}) it will update all the animals whose price is greater than 1000 and set their status to expensive
+  async updateMany(data) {
+    this.query.operation = "updateMany";
+    this.query.data = data;
+    console.log("\n================ UPDATE MANY REQUEST ================");
+    console.log("[SDK] Final Query:", this.query);
+    try {
+      const response = await this.client.sendDataRequest(
+        "PATCH",
+        this.query
+      );
+      console.log("[SDK] Update Many Response:", response);
+      return response;
+    } catch (error) {
+      console.error("[SDK] UPDATE MANY ERROR");
+      console.error(error);
+      throw error;
+    }
+  }
+  async DeleteById(id) {
+    this.query.operation = "delete";
+    this.query.id = id;
+    console.log("\n================ DELETE REQUEST ================");
+    console.log("[SDK] Final Query:", this.query);
+    try {
+      const response = await this.client.sendDataRequest(
+        "DELETE",
+        this.query
+      );
+      console.log("[SDK] Delete Response:", response);
+      return response;
+    } catch (error) {
+      console.error("[SDK] DELETE ERROR");
+      console.error(error);
+      throw error;
+    }
+  }
+  //deleteMany
+  //  its just like the get() it will call hte client
+  //example sdk.collection("animals").where("price", ">", 1000).deleteMany() it will delete all the animals whose price is greater than 1000
+  async deleteMany() {
+    this.query.operation = "deleteMany";
+    console.log("\n================ DELETE MANY REQUEST ================");
+    console.log("[SDK] Final Query:", this.query);
+    try {
+      const response = await this.client.sendDataRequest(
+        "DELETE",
+        this.query
+      );
+      console.log("[SDK] Delete Many Response:", response);
+      return response;
+    } catch (error) {
+      console.error("[SDK] DELETE MANY ERROR");
+      console.error(error);
+      throw error;
+    }
+  }
+};
+
+// src/auth.ts
+import * as crypto from "crypto";
+var AdminAuth = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Authenticate an administrator using credentials.
+   * The token returned will be automatically stored in the SDK client.
+   */
+  async credentials(adminEmail, password) {
+    return this.client.adminLogin(adminEmail, password);
+  }
+  /**
+   * Get the currently active administrator JWT token.
+   */
+  getToken() {
+    return this.client.getAdminToken();
+  }
+  /**
+   * Manually set the administrator JWT token (e.g. for server-side requests).
+   */
+  setToken(token) {
+    this.client.setAdminToken(token);
+  }
+  /**
+   * Offline verification of Ed25519 (EdDSA) JWT admin token using public key.
+   * Supported in Node.js / Server-side environments.
+   */
+  //detailed explaination of the verifyJwt function:
+  // The verifyJwt function is designed to validate a JWT (JSON Web Token) using
+  // the Ed25519 signature algorithm (EdDSA). It takes a JWT token as input and an optional public key in PEM format.
+  // The function performs several steps to ensure the token's integrity and authenticity:
+  // 1. It first determines which public key to use for verification, either from the argument or from the client's configuration.
+  // 2. It checks if the runtime environment supports the necessary crypto capabilities for JWT verification.
+  // 3. It splits the JWT into its three components: header, payload, and signature.
+  // 4. It decodes the signature from base64url format into a Buffer.
+  // 5. It imports the public key using Node.js's crypto module.
+  // 6. It verifies the signature against the message (header + payload) using the Ed25519 algorithm.
+  // 7. If verification succeeds, it decodes and parses the payload JSON.
+  // 8. It checks for token expiration based on the "exp" claim in the payload.
+  // 9. Finally, it returns the decoded payload if all checks pass,
+  //    or throws descriptive errors if any step fails.
+  verifyJwt(token, publicKeyPem) {
+    const keyToUse = publicKeyPem || this.client.getPublicKey();
+    if (!keyToUse) {
+      throw new Error(
+        "[ThinkingDifferently SDK Error] Public key is required for JWT verification. Please configure it in SDKConfig or pass it as an argument."
+      );
+    }
+    if (typeof crypto === "undefined" || !crypto.createPublicKey || !crypto.verify) {
+      throw new Error(
+        "[ThinkingDifferently SDK Error] JWT verification is only supported in Node.js / Server-side environments."
+      );
+    }
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      throw new Error("Invalid JWT format");
+    }
+    const [headerB64, payloadB64, signatureB64] = parts;
+    const message = `${headerB64}.${payloadB64}`;
+    let signature;
+    try {
+      signature = Buffer.from(signatureB64, "base64url");
+    } catch (err) {
+      throw new Error("Invalid JWT signature encoding");
+    }
+    let publicKey;
+    try {
+      publicKey = crypto.createPublicKey({
+        key: keyToUse,
+        format: "pem",
+        type: "spki"
+      });
+    } catch (err) {
+      throw new Error(`Failed to import public key: ${err.message}`);
+    }
+    const verified = crypto.verify(
+      void 0,
+      // Algorithm must be undefined for Ed25519 (EdDSA) in Node
+      Buffer.from(message),
+      publicKey,
+      signature
+    );
+    if (!verified) {
+      throw new Error("Invalid JWT signature");
+    }
+    let payload;
+    try {
+      const payloadJson = Buffer.from(payloadB64, "base64url").toString("utf8");
+      payload = JSON.parse(payloadJson);
+    } catch (err) {
+      throw new Error("Invalid JWT payload JSON");
+    }
+    if (payload.exp && typeof payload.exp === "number") {
+      const currentTime = Math.floor(Date.now() / 1e3);
+      if (payload.exp < currentTime) {
+        throw new Error("JWT has expired");
+      }
+    }
+    return payload;
+  }
+};
+var AuthModule = class {
+  constructor(client) {
+    this.admin = new AdminAuth(client);
   }
 };
 
@@ -124,7 +493,26 @@ var QueryBuilder = class {
 var ThinkingDifferently = class {
   constructor(config) {
     console.log("[ThinkingDifferently SDK] Initializing SDK");
-    this.client = new TDClient(config.apiKey);
+    this.client = new TDClient(config.apiKey, config.securityKey, config.publicKey);
+    this.auth = new AuthModule(this.client);
+  }
+  /**
+   * Dynamically update the security key (useful for backend projects).
+   */
+  setSecurityKey(key) {
+    this.client.setSecurityKey(key);
+  }
+  /**
+   * Dynamically update the public key used for offline verification.
+   */
+  setPublicKey(key) {
+    this.client.setPublicKey(key);
+  }
+  /**
+   * Helper to verify Ed25519 admin JWT token offline.
+   */
+  verifyJwt(token, publicKey) {
+    return this.auth.admin.verifyJwt(token, publicKey);
   }
   collection(name) {
     return new QueryBuilder(
@@ -158,7 +546,7 @@ var ThinkingDifferently = class {
         for (const [k, v] of payload.entries()) {
           console.log(k, v);
         }
-        return this.client.request(
+        return this.client.sendDataRequest(
           "POST",
           payload
         );
@@ -168,7 +556,7 @@ var ThinkingDifferently = class {
         key,
         data
       });
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "POST",
         {
           key,
@@ -189,7 +577,7 @@ var ThinkingDifferently = class {
     console.log("[SDK] Document ID:", id);
     console.log("[SDK] Update Data:", data);
     try {
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "PATCH",
         {
           key,
@@ -210,7 +598,7 @@ var ThinkingDifferently = class {
     console.log("[SDK] Collection Key:", key);
     console.log("[SDK] Document ID:", id);
     try {
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "DELETE",
         {
           key,
@@ -227,6 +615,8 @@ var ThinkingDifferently = class {
   }
 };
 export {
+  AdminAuth,
+  AuthModule,
   TDClient,
   ThinkingDifferently
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingdifferently/core",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Official SDK for Thinking Differently API",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -21,7 +21,8 @@
   "author": "Krrish Savlani",
   "license": "MIT",
   "dependencies": {
-    "axios": "^1.16.0"
+    "axios": "^1.16.0",
+    "crypto-js": "^4.2.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.2",