# Tarobase JS SDK
Tarobase is the web3 alternative to firebase. It is a powerful platform that simplifies the integration of hybrid on-chain actions and data for modern web and mobile applications.

Welcome to the **Tarobase JavaScript SDK**! This SDK allows you to interact with the Tarobase platform seamlessly from your JavaScript or TypeScript applications. Whether you're building a web app, a Node.js service, or a React Native application (support coming soon), the Tarobase JS SDK provides the tools you need.


## Table of Contents
- [Installation](#installation)

- [Getting Started](#getting-started)

	- [Initialization](#initialization)

	- [Authentication](#authentication)

- [Usage Examples](#usage-examples)

	- [Initialize the SDK](#initialize-the-sdk)

	- [Authenticate a User](#authenticate-a-user)

	- [Get Current User](#get-current-user)

	- [Set Data](#set-data)

		- [On-Chain and Off-Chain Data](#on-chain-and-off-chain-data)

	- [Get Data](#get-data)

	- [Get Multiple Documents](#get-multiple-documents)

- [Additional Resources](#additional-resources)

- [React Native Support](#react-native-support)

- [Contributing](#contributing)

- [License](#license)

  

## Installation
  
Install the SDK via npm:

  
```bash
npm install @tarobase/js-sdk
```
  

Or with Yarn:
```bash
yarn add @tarobase/js-sdk
```

  

## Getting Started
### Initialization

  

Before using the SDK, initialize it with your **Application ID**. You can obtain your `appId` by creating an application on the [Tarobase Console](https://console.tarobase.com). The console also allows you to configure your application's policies, including data storage preferences (on-chain or off-chain) and data schemas.

  
```typescript
import { init } from '@tarobase/js-sdk';

init({appId: 'YOUR_APP_ID' });
```  

### Authentication

  
To authenticate users, use the `login` function:

```typescript
import { login } from '@tarobase/js-sdk';

// Start the login process
login();
```

You can also listen for authentication state changes:
  
```typescript
import { onAuthStateChanged } from '@tarobase/js-sdk';

onAuthStateChanged((user) => {
	if (user) {
		console.log('User logged in:', user.address);
	} else {
		console.log('User logged out');
	}
});
```

  

## Usage

### Get Current User


```typescript
import { getCurrentUser } from '@tarobase/js-sdk';

const user = await getCurrentUser();
if (user) {
	console.log('Current user:', user.address);
} else {
	console.log('No user is currently logged in.');
}
```

  

### Set Data
```typescript
import { set } from '@tarobase/js-sdk';

const path = 'path/to/data';
const data = { key: 'value' };

await set(path, data);

console.log(`Data set at ${path}`);
```
  

#### On-Chain and Off-Chain Data

The `set` and `get` functions automatically handle whether data is stored **on-chain** or **off-chain** based on your application's policy configuration in the [Tarobase Console](https://console.tarobase.com).
  

**On-Chain Data:**

- If the data path corresponds to on-chain storage defined in your application policy, the `set` function will store data on-chain.

- The data must adhere to the `fields` schema defined in your Tarobase policy.

- Transactions are handled automatically, and users may be prompted to approve blockchain transactions.

**Off-Chain Data:**

- If the data path corresponds to off-chain storage, the `set` function will store data off-chain.

  

**Important:**

  

- Manage your data storage preferences and define policies at the [Tarobase Console](https://console.tarobase.com).

- Ensure that for on-chain data, the parameters you provide to `set` match the `fields` specified in your Tarobase policy.

- The policy also controls what can be `set` or `get` in your application.

- For information on how to form your policy specifically for your app's use-cases, view the policy docs [here](https://docs.tarobase.com/policies).

  
### Subscribe

```typescript
await subscribe('path/to/data', {}, (data) => { 
	console.log('Data updated:', data); }
);
```


### Get Data

```typescript
import { get } from '@tarobase/js-sdk';

const path = 'messages/abc123';
const data = await get(path);

const collection = 'messages';
// For colletion queries, include a plain english prompt to filter your results accordingly,
// smart queries will be constructed on your behalf by tarobase.
const data = await get(path, { prompt: "where text starts with the letter f" });

console.log(`Data at ${path}:`, data);
```

**Note:** Similar to `set`, the `get` and `subscribe` functions will automatically retrieve data from on-chain or off-chain storage based on your application's configuration.

### Get Multiple Documents

Use `getMany` to efficiently fetch multiple documents in a single request:

```typescript
import { getMany } from '@tarobase/js-sdk';

// Fetch multiple documents at once (max 30 paths)
const results = await getMany([
  'users/123/profile',
  'users/456/profile',
  'posts/789'
]);

// Each result contains: { path, data, error? }
results.forEach(result => {
  if (result.error) {
    console.log(`Error for ${result.path}: ${result.error.message}`);
  } else {
    console.log(`Data for ${result.path}:`, result.data);
  }
});
```

The `getMany` function:
- Accepts up to 30 document paths per request
- Returns results in the same order as the input paths
- Includes per-document error handling (NOT_FOUND, UNAUTHORIZED)
- Automatically caches successful fetches


  

### Additional Resources
For more comprehensive examples, detailed guides, and API references, please visit our documentation site:

- [Tarobase Documentation](https://docs.tarobase.com)

- Quickstart Guide

- [API Reference](https://docs.tarobase.com/api)


### React Native Support  
Support for **React Native** is coming soon! Stay tuned for updates, and feel free to check back on our [documentation site](https://docs.tarobase.com) for the latest information.

### Contributing
Contributions are welcome! Please open an issue or submit a pull request on GitHub.

### License
This Tarobase JS SDK project is licensed under the MIT License.

* * * * *
  

Thank you for using the Tarobase JS SDK! If you have any questions or need further assistance, feel free to crete an issue.