@thinkingdifferently/core 1.1.0 → 1.2.0

package/README.md

@@ -0,0 +1,321 @@
+# `@thinkingdifferently/core`
+
+Official TypeScript SDK for the Thinking Differently Backend-as-a-Service platform.
+
+The SDK provides a simple interface for interacting with Thinking Differently collections without manually managing HTTP requests, authentication headers, request formatting, or query serialization.
+
+## Features
+
+- TypeScript-first SDK
+- Collection querying with chained builders
+- Automatic API key authentication via `x-api-key`
+- Axios-based HTTP layer
+- Built-in validation for query inputs
+- `FormData` support for inserts
+- Query inspection with `toJSON()`
+
+## Installation
+
+```bash
+npm install @thinkingdifferently/core
+```
+
+## Quick Start
+
+```ts
+import { ThinkingDifferently } from "@thinkingdifferently/core";
+
+const sdk = new ThinkingDifferently({
+  apiKey: "YOUR_API_KEY"
+});
+
+const animals = await sdk
+  .collection("animals")
+  .where("age", ">", 10)
+  .limit(10)
+  .sort("createdAt", "desc")
+  .get();
+
+console.log(animals);
+```
+
+## TypeScript Usage
+
+The SDK is designed for TypeScript developers and supports generic response typing:
+
+```ts
+type Animal = {
+  name: string;
+  age: number;
+};
+
+const animals = await sdk
+  .collection("animals")
+  .get<Animal>();
+```
+
+You can also inspect the generated query before sending it:
+
+```ts
+const query = sdk
+  .collection("animals")
+  .where("age", ">", 10);
+
+console.log(query.toJSON());
+```
+
+## API Reference
+
+### `new ThinkingDifferently(config)`
+
+Creates an SDK instance.
+
+#### Parameters
+
+- `config.apiKey: string` — API key used for authenticated requests
+
+#### Example
+
+```ts
+const sdk = new ThinkingDifferently({
+  apiKey: "YOUR_API_KEY"
+});
+```
+
+### `sdk.collection(name)`
+
+Creates a query builder for a collection.
+
+#### Parameters
+
+- `name: string` — collection name
+
+#### Returns
+
+A `QueryBuilder` instance.
+
+### `QueryBuilder.where(field, operator, value)`
+
+Adds a filter to the query.
+
+#### Supported operators
+
+- `=`
+- `!=`
+- `>`
+- `<`
+- `>=`
+- `<=`
+- `in`
+- `contains`
+
+#### Notes
+
+- Empty field names are rejected
+- The `in` operator requires an array value
+- Multiple `where()` calls append filters
+
+#### Example
+
+```ts
+const query = sdk
+  .collection("animals")
+  .where("age", ">", 10)
+  .where("status", "=", "active");
+```
+
+### `QueryBuilder.limit(count)`
+
+Sets the maximum number of returned documents.
+
+#### Validation
+
+- Must be a positive integer
+- Subsequent calls overwrite the previous limit
+
+#### Example
+
+```ts
+const query = sdk.collection("animals").limit(20);
+```
+
+### `QueryBuilder.sort(field, direction)`
+
+Adds a sort clause to the query.
+
+#### Parameters
+
+- `field: string` — field to sort by
+- `direction: "asc" | "desc"` — sort direction
+
+#### Notes
+
+- Empty field names are rejected
+- Subsequent calls overwrite the previous sort
+
+#### Example
+
+```ts
+const query = sdk.collection("animals").sort("createdAt", "desc");
+```
+
+### `QueryBuilder.get<T>()`
+
+Executes the query and returns an array of typed results.
+
+#### Signature
+
+```ts
+get<T = any>(): Promise<T[]>
+```
+
+#### Example
+
+```ts
+const animals = await sdk
+  .collection("animals")
+  .where("age", ">", 10)
+  .get<{ name: string; age: number }>();
+```
+
+### `QueryBuilder.count()`
+
+Returns the number of documents matching the current query.
+
+#### Signature
+
+```ts
+count(): Promise<number>
+```
+
+#### Example
+
+```ts
+const total = await sdk
+  .collection("animals")
+  .where("age", ">", 10)
+  .count();
+```
+
+### `QueryBuilder.toJSON()`
+
+Returns a deep copy of the generated query object.
+
+#### Example
+
+```ts
+const query = sdk.collection("animals").where("age", ">", 10);
+console.log(query.toJSON());
+```
+
+### `types `
+
+```ts
+interface SDKConfig {
+  apiKey: string;
+}
+```
+
+## HTTP Details
+
+- Base URL: `https://www.thinkingdifferently.dev/api/v1`
+- Authentication header: `x-api-key: YOUR_API_KEY`
+- HTTP client: Axios
+- Supported methods: `GET`, `POST`, `PATCH`, `DELETE`
+
+## Error Handling
+
+The SDK throws JavaScript `Error` objects when requests fail or when query validation fails.
+
+### Request errors
+
+Backend errors are converted into `Error` messages.
+
+```ts
+try {
+  const animals = await sdk
+    .collection("animals")
+    .get();
+
+  console.log(animals);
+} catch (error) {
+  console.error(error);
+}
+```
+
+### Validation errors
+
+The SDK validates query input before sending requests:
+
+- Empty field names are rejected
+- Invalid limit values are rejected
+- The `in` operator requires an array
+- Query responses are validated before parsing
+
+## Examples
+
+### Filter, sort, and limit
+
+```ts
+const animals = await sdk
+  .collection("animals")
+  .where("age", ">", 10)
+  .where("price", "<", 50000)
+  .limit(10)
+  .sort("createdAt", "desc")
+  .get();
+```
+
+### Count matching documents
+
+```ts
+const total = await sdk
+  .collection("animals")
+  .where("age", ">", 10)
+  .count();
+```
+
+### Inspect the generated query
+
+```ts
+const query = sdk
+  .collection("animals")
+  .where("age", ">", 10);
+
+console.log(JSON.stringify(query.toJSON(), null, 2));
+```
+
+## FAQ
+
+### How do I authenticate?
+
+Pass your API key to `new ThinkingDifferently({ apiKey })`. The SDK automatically sends it using the `x-api-key` header.
+
+### What does `collection()` return?
+
+It returns a query builder that lets you chain `where()`, `limit()`, `sort()`, `get()`, `count()`, and `toJSON()`.
+
+### Can I inspect a query before executing it?
+
+Yes. Call `toJSON()` on the query builder to get a deep copy of the query object.
+
+### Does the SDK validate input?
+
+Yes. Empty field names, invalid limit values, and invalid `in` operator values are rejected.
+
+### What transport does the SDK use?
+
+The SDK uses Axios for network requests.
+
+## Roadmap
+
+The following items are listed in the current design notes as not yet implemented:
+
+- `update()`
+- `delete()`
+- `first()`
+- pagination helpers
+- aggregation queries
+- `OR` conditions
+- joins
+

package/dist/index.d.mts

@@ -7,17 +7,20 @@ interface GetOptions {
 
 declare class TDClient {
     private api;
+    private apikey;
     constructor(apiKey: string);
     request(method: "POST" | "GET" | "PATCH" | "DELETE", body?: any): Promise<any>;
 }
 
 type Operator = "=" | "!=" | ">" | "<" | ">=" | "<=" | "in" | "contains";
+type Operation = "find" | "count" | "insert" | "update" | "delete" | "updateMany" | "deleteMany";
 type Filter = {
     field: string;
     operator: Operator;
     value: unknown;
 };
 type Query = {
+    operation: Operation | null;
     collection: string;
     filters: Filter[];
     limit: number | null;
@@ -25,6 +28,8 @@ type Query = {
         field: string;
         direction: "asc" | "desc";
     } | null;
+    id?: string;
+    data?: unknown;
 };
 declare class QueryBuilder {
     private query;
@@ -33,9 +38,14 @@ declare class QueryBuilder {
     where(field: string, operator: Operator, value: unknown): this;
     limit(count: number): this;
     sort(field: string, direction: "asc" | "desc"): this;
-    get<T = any>(): Promise<T[]>;
     count(): Promise<number>;
     toJSON(): Query;
+    get<T = any>(): Promise<T[]>;
+    insert(data: unknown): Promise<any>;
+    UpdateById(id: string, data: Record<string, any>): Promise<any>;
+    updateMany(data: Record<string, any>): Promise<any>;
+    DeleteById(id: string): Promise<any>;
+    deleteMany(): Promise<any>;
 }
 
 declare class ThinkingDifferently {

package/dist/index.d.ts

@@ -7,17 +7,20 @@ interface GetOptions {
 
 declare class TDClient {
     private api;
+    private apikey;
     constructor(apiKey: string);
     request(method: "POST" | "GET" | "PATCH" | "DELETE", body?: any): Promise<any>;
 }
 
 type Operator = "=" | "!=" | ">" | "<" | ">=" | "<=" | "in" | "contains";
+type Operation = "find" | "count" | "insert" | "update" | "delete" | "updateMany" | "deleteMany";
 type Filter = {
     field: string;
     operator: Operator;
     value: unknown;
 };
 type Query = {
+    operation: Operation | null;
     collection: string;
     filters: Filter[];
     limit: number | null;
@@ -25,6 +28,8 @@ type Query = {
         field: string;
         direction: "asc" | "desc";
     } | null;
+    id?: string;
+    data?: unknown;
 };
 declare class QueryBuilder {
     private query;
@@ -33,9 +38,14 @@ declare class QueryBuilder {
     where(field: string, operator: Operator, value: unknown): this;
     limit(count: number): this;
     sort(field: string, direction: "asc" | "desc"): this;
-    get<T = any>(): Promise<T[]>;
     count(): Promise<number>;
     toJSON(): Query;
+    get<T = any>(): Promise<T[]>;
+    insert(data: unknown): Promise<any>;
+    UpdateById(id: string, data: Record<string, any>): Promise<any>;
+    updateMany(data: Record<string, any>): Promise<any>;
+    DeleteById(id: string): Promise<any>;
+    deleteMany(): Promise<any>;
 }
 
 declare class ThinkingDifferently {

package/dist/index.js

@@ -39,6 +39,7 @@ module.exports = __toCommonJS(index_exports);
 var import_axios = __toESM(require("axios"));
 var TDClient = class {
   constructor(apiKey) {
+    this.apikey = apiKey;
     this.api = import_axios.default.create({
       baseURL: "https://www.thinkingdifferently.dev/api/v1",
       headers: {
@@ -50,6 +51,14 @@ var TDClient = class {
   async request(method, body) {
     try {
       const isFormData = body instanceof FormData;
+      if (isFormData) {
+        body.append("key", this.apikey);
+      } else {
+        body = {
+          key: this.apikey,
+          query: body
+        };
+      }
       const response = await this.api.request({
         url: "/data",
         method,
@@ -70,6 +79,7 @@ var QueryBuilder = class {
   constructor(collection, client) {
     this.client = client;
     this.query = {
+      operation: null,
       collection,
       filters: [],
       limit: null,
@@ -103,7 +113,30 @@ 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.request(
+        "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() {
+    this.query.operation = "find";
     console.log("\n================ GET REQUEST ================");
     console.log("[SDK] Final Query:", this.query);
     try {
@@ -115,45 +148,133 @@ 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.request(
+          "POST",
+          payload
+        );
       }
-      return response.count;
+      this.query.data = data;
+      console.log("[SDK] Final Query:", this.query);
+      return await this.client.request(
+        "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.request(
+        "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.request(
+        "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.request(
+        "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.request(
+        "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;
+    }
   }
 };
 

package/dist/index.mjs

@@ -2,6 +2,7 @@
 import axios from "axios";
 var TDClient = class {
   constructor(apiKey) {
+    this.apikey = apiKey;
     this.api = axios.create({
       baseURL: "https://www.thinkingdifferently.dev/api/v1",
       headers: {
@@ -13,6 +14,14 @@ var TDClient = class {
   async request(method, body) {
     try {
       const isFormData = body instanceof FormData;
+      if (isFormData) {
+        body.append("key", this.apikey);
+      } else {
+        body = {
+          key: this.apikey,
+          query: body
+        };
+      }
       const response = await this.api.request({
         url: "/data",
         method,
@@ -33,6 +42,7 @@ var QueryBuilder = class {
   constructor(collection, client) {
     this.client = client;
     this.query = {
+      operation: null,
       collection,
       filters: [],
       limit: null,
@@ -66,7 +76,30 @@ 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.request(
+        "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() {
+    this.query.operation = "find";
     console.log("\n================ GET REQUEST ================");
     console.log("[SDK] Final Query:", this.query);
     try {
@@ -78,45 +111,133 @@ 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.request(
+          "POST",
+          payload
+        );
       }
-      return response.count;
+      this.query.data = data;
+      console.log("[SDK] Final Query:", this.query);
+      return await this.client.request(
+        "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.request(
+        "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.request(
+        "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.request(
+        "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.request(
+        "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;
+    }
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingdifferently/core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Official SDK for Thinking Differently API",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",