@thinkingdifferently/core 1.2.0 → 1.3.1

package/dist/index.d.mts

@@ -1,15 +1,55 @@
 interface SDKConfig {
     apiKey: string;
+    securityKey?: string;
+    publicKey?: string;
 }
 interface GetOptions {
     limit?: number;
 }
+interface CredentialParams {
+    adminEmail?: string;
+    password?: string;
+}
+interface LoginResponse {
+    message: string;
+    token: string;
+    admin: {
+        id: string;
+        adminName: string;
+        adminEmail: string;
+        projectId: string;
+        projectName: string;
+    };
+}
 
 declare class TDClient {
     private api;
     private apikey;
-    constructor(apiKey: string);
-    request(method: "POST" | "GET" | "PATCH" | "DELETE", body?: any): Promise<any>;
+    private securityKey?;
+    private publicKey?;
+    private adminToken;
+    constructor(apiKey: string, securityKey?: string, publicKey?: string);
+    setSecurityKey(key: string): void;
+    setPublicKey(key: string): void;
+    setAdminToken(token: string): void;
+    getAdminToken(): string | null;
+    getPublicKey(): string | undefined;
+    /**
+     * Reusable private error formatting utility
+     */
+    private handleError;
+    /**
+     * Handles authentication HTTP requests targeting /auth/admin/login
+     */
+    adminLogin(adminEmail?: string, password?: string): Promise<LoginResponse>;
+    /**
+     * Determines if an API request is a database write operation.
+     */
+    private isWriteOperation;
+    /**
+     * Executes queries and mutations against /data endpoint.
+     */
+    sendDataRequest(method: "POST" | "GET" | "PATCH" | "DELETE", body?: any): Promise<any>;
 }
 
 type Operator = "=" | "!=" | ">" | "<" | ">=" | "<=" | "in" | "contains";
@@ -48,13 +88,53 @@ declare class QueryBuilder {
     deleteMany(): Promise<any>;
 }
 
+declare class AdminAuth {
+    private client;
+    constructor(client: TDClient);
+    /**
+     * Authenticate an administrator using credentials.
+     * The token returned will be automatically stored in the SDK client.
+     */
+    credentials(adminEmail?: string, password?: string): Promise<LoginResponse>;
+    /**
+     * Get the currently active administrator JWT token.
+     */
+    getToken(): string | null;
+    /**
+     * Manually set the administrator JWT token (e.g. for server-side requests).
+     */
+    setToken(token: string): void;
+    /**
+     * Offline verification of Ed25519 (EdDSA) JWT admin token using public key.
+     * Supported in Node.js / Server-side environments.
+     */
+    verifyJwt(token: string, publicKeyPem?: string): any;
+}
+declare class AuthModule {
+    admin: AdminAuth;
+    constructor(client: TDClient);
+}
+
 declare class ThinkingDifferently {
     private client;
+    auth: AuthModule;
     constructor(config: SDKConfig);
+    /**
+     * Dynamically update the security key (useful for backend projects).
+     */
+    setSecurityKey(key: string): void;
+    /**
+     * Dynamically update the public key used for offline verification.
+     */
+    setPublicKey(key: string): void;
+    /**
+     * Helper to verify Ed25519 admin JWT token offline.
+     */
+    verifyJwt(token: string, publicKey?: string): any;
     collection(name: string): QueryBuilder;
     insert(key: string, data: any): Promise<any>;
     update(key: string, id: string, data: Record<string, any>): Promise<any>;
     delete(key: string, id: string): Promise<any>;
 }
 
-export { type GetOptions, type SDKConfig, TDClient, ThinkingDifferently };
+export { AdminAuth, AuthModule, type CredentialParams, type GetOptions, type LoginResponse, type SDKConfig, TDClient, ThinkingDifferently };

package/dist/index.d.ts

@@ -1,15 +1,55 @@
 interface SDKConfig {
     apiKey: string;
+    securityKey?: string;
+    publicKey?: string;
 }
 interface GetOptions {
     limit?: number;
 }
+interface CredentialParams {
+    adminEmail?: string;
+    password?: string;
+}
+interface LoginResponse {
+    message: string;
+    token: string;
+    admin: {
+        id: string;
+        adminName: string;
+        adminEmail: string;
+        projectId: string;
+        projectName: string;
+    };
+}
 
 declare class TDClient {
     private api;
     private apikey;
-    constructor(apiKey: string);
-    request(method: "POST" | "GET" | "PATCH" | "DELETE", body?: any): Promise<any>;
+    private securityKey?;
+    private publicKey?;
+    private adminToken;
+    constructor(apiKey: string, securityKey?: string, publicKey?: string);
+    setSecurityKey(key: string): void;
+    setPublicKey(key: string): void;
+    setAdminToken(token: string): void;
+    getAdminToken(): string | null;
+    getPublicKey(): string | undefined;
+    /**
+     * Reusable private error formatting utility
+     */
+    private handleError;
+    /**
+     * Handles authentication HTTP requests targeting /auth/admin/login
+     */
+    adminLogin(adminEmail?: string, password?: string): Promise<LoginResponse>;
+    /**
+     * Determines if an API request is a database write operation.
+     */
+    private isWriteOperation;
+    /**
+     * Executes queries and mutations against /data endpoint.
+     */
+    sendDataRequest(method: "POST" | "GET" | "PATCH" | "DELETE", body?: any): Promise<any>;
 }
 
 type Operator = "=" | "!=" | ">" | "<" | ">=" | "<=" | "in" | "contains";
@@ -48,13 +88,53 @@ declare class QueryBuilder {
     deleteMany(): Promise<any>;
 }
 
+declare class AdminAuth {
+    private client;
+    constructor(client: TDClient);
+    /**
+     * Authenticate an administrator using credentials.
+     * The token returned will be automatically stored in the SDK client.
+     */
+    credentials(adminEmail?: string, password?: string): Promise<LoginResponse>;
+    /**
+     * Get the currently active administrator JWT token.
+     */
+    getToken(): string | null;
+    /**
+     * Manually set the administrator JWT token (e.g. for server-side requests).
+     */
+    setToken(token: string): void;
+    /**
+     * Offline verification of Ed25519 (EdDSA) JWT admin token using public key.
+     * Supported in Node.js / Server-side environments.
+     */
+    verifyJwt(token: string, publicKeyPem?: string): any;
+}
+declare class AuthModule {
+    admin: AdminAuth;
+    constructor(client: TDClient);
+}
+
 declare class ThinkingDifferently {
     private client;
+    auth: AuthModule;
     constructor(config: SDKConfig);
+    /**
+     * Dynamically update the security key (useful for backend projects).
+     */
+    setSecurityKey(key: string): void;
+    /**
+     * Dynamically update the public key used for offline verification.
+     */
+    setPublicKey(key: string): void;
+    /**
+     * Helper to verify Ed25519 admin JWT token offline.
+     */
+    verifyJwt(token: string, publicKey?: string): any;
     collection(name: string): QueryBuilder;
     insert(key: string, data: any): Promise<any>;
     update(key: string, id: string, data: Record<string, any>): Promise<any>;
     delete(key: string, id: string): Promise<any>;
 }
 
-export { type GetOptions, type SDKConfig, TDClient, ThinkingDifferently };
+export { AdminAuth, AuthModule, type CredentialParams, type GetOptions, type LoginResponse, type SDKConfig, TDClient, ThinkingDifferently };

package/dist/index.js

@@ -30,6 +30,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AdminAuth: () => AdminAuth,
+  AuthModule: () => AuthModule,
   TDClient: () => TDClient,
   ThinkingDifferently: () => ThinkingDifferently
 });
@@ -38,19 +40,155 @@ module.exports = __toCommonJS(index_exports);
 // src/client.ts
 var import_axios = __toESM(require("axios"));
 var TDClient = class {
-  constructor(apiKey) {
+  constructor(apiKey, securityKey, publicKey) {
+    this.adminToken = null;
     this.apikey = apiKey;
+    this.securityKey = securityKey;
+    this.publicKey = publicKey;
     this.api = import_axios.default.create({
+      // 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 isFormData = body instanceof FormData;
+      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 = 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 {
@@ -62,14 +200,12 @@ var TDClient = class {
       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);
     }
   }
 };
@@ -121,7 +257,7 @@ var QueryBuilder = class {
     console.log("\n================ COUNT REQUEST ================");
     console.log("[SDK] Final Query:", this.query);
     try {
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "POST",
         this.query
       );
@@ -136,11 +272,16 @@ var QueryBuilder = class {
     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
       );
@@ -181,14 +322,14 @@ var QueryBuilder = class {
           JSON.stringify(this.query)
         );
         console.log("[SDK] Query:", this.query);
-        return await this.client.request(
+        return await this.client.sendDataRequest(
           "POST",
           payload
         );
       }
       this.query.data = data;
       console.log("[SDK] Final Query:", this.query);
-      return await this.client.request(
+      return await this.client.sendDataRequest(
         "POST",
         this.query
       );
@@ -205,7 +346,7 @@ var QueryBuilder = class {
     console.log("\n================ UPDATE REQUEST ================");
     console.log("[SDK] Final Query:", this.query);
     try {
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "PATCH",
         this.query
       );
@@ -226,7 +367,7 @@ var QueryBuilder = class {
     console.log("\n================ UPDATE MANY REQUEST ================");
     console.log("[SDK] Final Query:", this.query);
     try {
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "PATCH",
         this.query
       );
@@ -244,7 +385,7 @@ var QueryBuilder = class {
     console.log("\n================ DELETE REQUEST ================");
     console.log("[SDK] Final Query:", this.query);
     try {
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "DELETE",
         this.query
       );
@@ -264,7 +405,7 @@ var QueryBuilder = class {
     console.log("\n================ DELETE MANY REQUEST ================");
     console.log("[SDK] Final Query:", this.query);
     try {
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "DELETE",
         this.query
       );
@@ -278,11 +419,139 @@ var QueryBuilder = class {
   }
 };
 
+// src/auth.ts
+var crypto = __toESM(require("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);
+  }
+};
+
 // src/index.ts
 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(
@@ -316,7 +585,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
         );
@@ -326,7 +595,7 @@ var ThinkingDifferently = class {
         key,
         data
       });
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "POST",
         {
           key,
@@ -347,7 +616,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,
@@ -368,7 +637,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,
@@ -386,6 +655,8 @@ var ThinkingDifferently = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AdminAuth,
+  AuthModule,
   TDClient,
   ThinkingDifferently
 });

package/dist/index.mjs

@@ -1,19 +1,155 @@
 // 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: "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 isFormData = body instanceof FormData;
+      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 = 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 {
@@ -25,14 +161,12 @@ var TDClient = class {
       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);
     }
   }
 };
@@ -84,7 +218,7 @@ var QueryBuilder = class {
     console.log("\n================ COUNT REQUEST ================");
     console.log("[SDK] Final Query:", this.query);
     try {
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "POST",
         this.query
       );
@@ -99,11 +233,16 @@ var QueryBuilder = class {
     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
       );
@@ -144,14 +283,14 @@ var QueryBuilder = class {
           JSON.stringify(this.query)
         );
         console.log("[SDK] Query:", this.query);
-        return await this.client.request(
+        return await this.client.sendDataRequest(
           "POST",
           payload
         );
       }
       this.query.data = data;
       console.log("[SDK] Final Query:", this.query);
-      return await this.client.request(
+      return await this.client.sendDataRequest(
         "POST",
         this.query
       );
@@ -168,7 +307,7 @@ var QueryBuilder = class {
     console.log("\n================ UPDATE REQUEST ================");
     console.log("[SDK] Final Query:", this.query);
     try {
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "PATCH",
         this.query
       );
@@ -189,7 +328,7 @@ var QueryBuilder = class {
     console.log("\n================ UPDATE MANY REQUEST ================");
     console.log("[SDK] Final Query:", this.query);
     try {
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "PATCH",
         this.query
       );
@@ -207,7 +346,7 @@ var QueryBuilder = class {
     console.log("\n================ DELETE REQUEST ================");
     console.log("[SDK] Final Query:", this.query);
     try {
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "DELETE",
         this.query
       );
@@ -227,7 +366,7 @@ var QueryBuilder = class {
     console.log("\n================ DELETE MANY REQUEST ================");
     console.log("[SDK] Final Query:", this.query);
     try {
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "DELETE",
         this.query
       );
@@ -241,11 +380,139 @@ var QueryBuilder = class {
   }
 };
 
+// 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);
+  }
+};
+
 // src/index.ts
 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(
@@ -279,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
         );
@@ -289,7 +556,7 @@ var ThinkingDifferently = class {
         key,
         data
       });
-      const response = await this.client.request(
+      const response = await this.client.sendDataRequest(
         "POST",
         {
           key,
@@ -310,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,
@@ -331,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,
@@ -348,6 +615,8 @@ var ThinkingDifferently = class {
   }
 };
 export {
+  AdminAuth,
+  AuthModule,
   TDClient,
   ThinkingDifferently
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingdifferently/core",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "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",