@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

npm install @thinkingdifferently/core

Quick Start

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:

type Animal = {
  name: string;
  age: number;
};

const animals = await sdk
  .collection("animals")
  .get<Animal>();

You can also inspect the generated query before sending it:

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

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

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

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

const query = sdk.collection("animals").sort("createdAt", "desc");

QueryBuilder.get<T>()

Executes the query and returns an array of typed results.

Signature

get<T = any>(): Promise<T[]>

Example

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

count(): Promise<number>

Example

const total = await sdk
  .collection("animals")
  .where("age", ">", 10)
  .count();

QueryBuilder.toJSON()

Returns a deep copy of the generated query object.

Example

const query = sdk.collection("animals").where("age", ">", 10);
console.log(query.toJSON());

types

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.

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

const animals = await sdk
  .collection("animals")
  .where("age", ">", 10)
  .where("price", "<", 50000)
  .limit(10)
  .sort("createdAt", "desc")
  .get();

Count matching documents

const total = await sdk
  .collection("animals")
  .where("age", ">", 10)
  .count();

Inspect the generated query

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