@thinkingdifferently/core 1.1.0 → 1.3.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

@@ -1,23 +1,66 @@
 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;
-    constructor(apiKey: string);
-    request(method: "POST" | "GET" | "PATCH" | "DELETE", body?: any): Promise<any>;
+    private apikey;
+    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";
+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 +68,8 @@ type Query = {
         field: string;
         direction: "asc" | "desc";
     } | null;
+    id?: string;
+    data?: unknown;
 };
 declare class QueryBuilder {
     private query;
@@ -33,18 +78,63 @@ 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 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,23 +1,66 @@
 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;
-    constructor(apiKey: string);
-    request(method: "POST" | "GET" | "PATCH" | "DELETE", body?: any): Promise<any>;
+    private apikey;
+    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";
+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 +68,8 @@ type Query = {
         field: string;
         direction: "asc" | "desc";
     } | null;
+    id?: string;
+    data?: unknown;
 };
 declare class QueryBuilder {
     private query;
@@ -33,18 +78,63 @@ 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 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 };