@bounded-sh/client 0.0.1

package/README.md

@@ -0,0 +1,298 @@
+
+# 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)
+
+	- [Subscribe](#subscribe)
+
+	- [Get Data](#get-data)
+
+	- [Counting, Aggregation, Search, and Joins](#counting-aggregation-search-and-joins)
+
+	- [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
+import { subscribe } from '@tarobase/js-sdk';
+
+// Subscribe to a single document
+const unsubscribe = await subscribe('users/123/profile', {
+	onData: (data) => console.log('Data updated:', data),
+	onError: (e) => console.error(e.message),
+});
+
+// Subscribe to a filtered, live collection feed
+await subscribe('orders', {
+	filter: { status: 'open', amount: { $gt: 100 } },
+	limit: 50,
+	onData: (orders) => console.log('Live open orders:', orders),
+});
+
+// Later, to stop receiving updates:
+await unsubscribe();
+```
+
+
+### Get Data
+
+```typescript
+import { get } from '@tarobase/js-sdk';
+
+// Read a single document
+const message = await get('messages/abc123');
+
+// Query a collection with a structured filter, sort, limit, and cursor pagination
+const recent = await get('messages', {
+	filter: { text: { $regex: '^f', $options: 'i' } }, // text starting with "f"
+	sort: { tarobase_created_at: -1 },
+	limit: 20,
+	// cursor: previousPage.nextCursor,  // opaque keyset cursor (no numeric offset)
+});
+
+console.log('Messages:', recent);
+```
+
+`filter` uses MongoDB-style operators (`$gt`, `$gte`, `$lt`, `$lte`, `$ne`,
+`$in`, `$nin`, `$all`, `$size`, `$elemMatch`, `$exists`, `$type`, `$regex`,
+`$and`, `$or`, `$nor`) evaluated server-side. See the
+[Querying reference](https://docs.tarobase.com/querying) for the full table.
+
+> **Note:** The older natural-language `prompt` option is legacy and no longer
+> filters results — always use the structured `filter` option above.
+
+**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.
+
+### Counting, Aggregation, Search, and Joins
+
+```typescript
+import { count, aggregate, queryAggregate, search, get } from '@tarobase/js-sdk';
+
+// Count matching documents
+const { value: openCount } = await count('orders', { filter: { status: 'open' } });
+
+// Single scalar aggregate: count | uniqueCount | sum | avg | min | max
+const { value: total } = await aggregate('orders', 'sum', { field: 'amount' });
+
+// Grouped aggregation → one row per group
+const byCategory = await queryAggregate('spend', { groupBy: ['category'], count: true, sum: ['amount'] });
+
+// Full-text search (collection must declare `search: { fields: [...] }` in policy)
+const docs = await search('orgs/o1/docs', 'quarterly report', { fields: ['title', 'body'] });
+
+// Relationship join via `shape` (collection must declare `links` in policy)
+const projects = await get('projects', { shape: { owner: {} } });
+```
+
+### 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.
+

package/dist/auth/hooks/useAuth.d.ts

@@ -0,0 +1,8 @@
+import { User } from '@bounded-sh/core';
+export interface UseAuthResult {
+    login: () => Promise<void>;
+    logout: () => Promise<void>;
+    loading: boolean;
+    user: User | null;
+}
+export declare function useAuth(): UseAuthResult;

package/dist/auth/index.d.ts

@@ -0,0 +1,73 @@
+import { AuthProvider, User, ClientConfig } from "@bounded-sh/core";
+/**
+ * Clears the session if it was created before auth method tracking (legacy session).
+ * Returns true if the session was cleared, false if the session is compatible.
+ *
+ * Dispatches to the correct session manager based on the current auth method
+ * so both web (WebSessionManager) and RN (ReactNativeSessionManager) sessions
+ * are properly cleared.
+ */
+export declare function clearIncompatibleSession(): boolean;
+export declare const SOLANA_DEVNET_RPC_URL = "https://idelle-8nxsep-fast-devnet.helius-rpc.com";
+export declare const SOLANA_MAINNET_RPC_URL = "https://celestia-cegncv-fast-mainnet.helius-rpc.com";
+export declare const SURFNET_RPC_URL = "https://surfpool.fly.dev";
+export declare function getAuthProvider(config?: Partial<ClientConfig>): Promise<AuthProvider>;
+/** Per-call overrides forwarded to the active auth provider's modal. */
+export interface LoginOptions {
+    /** Override the modal theme just for this login call: 'light' or 'dark'. */
+    theme?: 'light' | 'dark';
+    /** Override the modal title just for this login call. */
+    modalTitle?: string;
+    /** Override the modal subtitle just for this login call. */
+    modalSubtitle?: string;
+}
+/**
+ * Anonymous ("guest") sign-in: zero-friction auth backed by a device-local
+ * ed25519 keypair (no email, no wallet, no popup). The keypair is generated +
+ * persisted on the device; its public key becomes `@user.address`. Durable
+ * across reloads. Upgrade later by linking an email; transfer accounts via the
+ * ownership-as-data pattern. `init()` must have run first. Browser/RN only.
+ */
+export declare function signInAnonymously(): Promise<User | null>;
+/**
+ * Log in with Privy as a co-equal route — selectable at runtime alongside
+ * `login()` (email/wallet) and `signInAnonymously()`, without re-`init()`.
+ *
+ * On WEB it lazy-loads the @privy-io/react-auth-backed PrivyWalletProvider from
+ * `config.privyConfig`. On REACT NATIVE the host must have created a
+ * PrivyExpoProvider and bridged the Privy hooks via setPrivyMethods() (pass it as
+ * `config.privyExpoProvider` to init()) — RN can't construct it here because the
+ * Privy hooks live in the app's component tree.
+ *
+ * Either way the Privy Solana wallet signs the SIWS challenge, so the session is
+ * minted via the same wallet path as Phantom and shares the unified session store
+ * (web localStorage / RN storage) and identity model. `init()` must have run first.
+ */
+export declare function loginWithPrivy(options?: LoginOptions): Promise<User | null>;
+/**
+ * Send a 6-digit login code to `email` (Bounded Better Auth). Step 1 of the
+ * inline email flow — build your own email/code UI, or just call `login()` for
+ * the built-in modal. Works on web AND React Native (no DOM needed).
+ */
+export declare function sendEmailOtp(email: string): Promise<{
+    ok: true;
+    expiresInSeconds?: number;
+}>;
+/**
+ * Verify the `code` for `email`, establish the session, and return the user.
+ * Step 2 of the inline email flow. Coexists with signInAnonymously()/wallets.
+ */
+export declare function verifyEmailOtp(email: string, code: string): Promise<User | null>;
+/**
+ * UPGRADE the current anonymous (guest) session by linking an email — Firebase
+ * `linkWithCredential` parity. Send the code first with `sendEmailOtp(email)`,
+ * then call `linkEmail(email, code)`. If the email is brand-new the guest's
+ * `@user.id` (and its data) is preserved; if the email already exists the user
+ * just signs into it (no merge). After it resolves, `getCurrentUser().isAnonymous`
+ * is `false`. Requires an active guest session (`signInAnonymously()` first).
+ */
+export declare function linkEmail(email: string, code: string): Promise<User | null>;
+export declare function login(options?: LoginOptions): Promise<User | null>;
+export declare function getCurrentAuthMethod(): string | null;
+export declare function logout(): Promise<void>;
+export { loginWithRedirect, linkWithRedirect, completeLoginFromRedirect, loginWithPopup, completeLoginInPopup } from './oidc-auth';

package/dist/auth/oidc-auth.d.ts

@@ -0,0 +1,27 @@
+import type { User } from '@bounded-sh/core';
+/** Start login: navigate the whole page to the hosted Bounded login. Returns after redirect
+ *  to `redirectUri?code=...`, where you call completeLoginFromRedirect(). Web only. */
+export declare function loginWithRedirect(opts: {
+    redirectUri: string;
+}): Promise<void>;
+/** UPGRADE the current anonymous (guest) session by linking a SOCIAL/redirect login
+ *  (e.g. Google) — Firebase `linkWithPopup`/redirect parity. Stashes the guest token,
+ *  then runs the normal redirect login; `completeLoginFromRedirect()` on the callback
+ *  page finishes the link automatically (if the social account is brand-new the guest's
+ *  `@user.id` is preserved, else it stays separate). Requires an active guest session. */
+export declare function linkWithRedirect(opts: {
+    redirectUri: string;
+}): Promise<void>;
+/** Finish login on the redirect_uri page: exchange ?code= for a token (PKCE-verified), store
+ *  the session, and return the User. Idempotent: returns null if there's no ?code= in the URL. */
+export declare function completeLoginFromRedirect(): Promise<User | null>;
+/** Popup variant: open the hosted login in a popup; resolves with the User once the popup's
+ *  redirect_uri page posts the code back. The redirect_uri page must call completeLoginInPopup(). */
+export declare function loginWithPopup(opts: {
+    redirectUri: string;
+    width?: number;
+    height?: number;
+}): Promise<User>;
+/** Call this on the redirect_uri page when login was opened via loginWithPopup(): posts the
+ *  code back to the opener and closes. (For the redirect variant use completeLoginFromRedirect.) */
+export declare function completeLoginInPopup(openerOrigin: string): void;

package/dist/auth/providers/email-auth-provider.d.ts

@@ -0,0 +1,38 @@
+import type { AuthProvider, User, TransactionResult, SolTransaction, EVMTransaction, SetOptions } from '@bounded-sh/core';
+import { Transaction, VersionedTransaction } from '@solana/web3.js';
+/** Send a login code to `email`. Step 1 of the inline email-OTP flow. */
+export declare function sendEmailOtp(email: string): Promise<{
+    ok: true;
+    expiresInSeconds?: number;
+}>;
+/**
+ * Verify the code for `email` and establish the session. Step 2 of the flow.
+ * Stores the Bounded id token (the realtime bearer) and sets the current user.
+ */
+export declare function verifyEmailOtp(email: string, otp: string): Promise<User>;
+/**
+ * UPGRADE an anonymous (guest) session by LINKING an email credential — Firebase
+ * `linkWithCredential` parity. The guest's `guestToken` is sent to the auth issuer
+ * which, IF the email is brand-new, makes the new account ADOPT the guest's id so
+ * `@user.id` is preserved and the guest's data carries over. If the email already
+ * exists, the user just signs into it (stays separate; `linked:false`). On success
+ * the upgraded session replaces the guest session and the user is no longer
+ * anonymous. `guestToken` is captured by the caller BEFORE switching auth methods.
+ */
+export declare function linkEmailWithGuest(email: string, otp: string, guestToken: string): Promise<{
+    user: User;
+    linked: boolean;
+    isNewAccount: boolean;
+}>;
+export declare class EmailAuthProvider implements AuthProvider {
+    login(): Promise<User | null>;
+    restoreSession(): Promise<User | null>;
+    logout(): Promise<void>;
+    signMessage(_message: string): Promise<string>;
+    runTransaction(_evm?: EVMTransaction, _sol?: SolTransaction, _options?: SetOptions): Promise<TransactionResult>;
+    signTransaction(_t: Transaction | VersionedTransaction): Promise<Transaction | VersionedTransaction>;
+    signAndSubmitTransaction(): Promise<string>;
+    getNativeMethods(): Promise<any>;
+}
+declare const emailProviderSingleton: EmailAuthProvider;
+export { emailProviderSingleton };

package/dist/auth/providers/guest-auth-provider.d.ts

@@ -0,0 +1,14 @@
+import type { AuthProvider, User, TransactionResult, SolTransaction, EVMTransaction, SetOptions } from '@bounded-sh/core';
+import { Transaction, VersionedTransaction } from '@solana/web3.js';
+export declare class GuestAuthProvider implements AuthProvider {
+    login(): Promise<User | null>;
+    restoreSession(): Promise<User | null>;
+    logout(): Promise<void>;
+    /** Wipe the device key — the next login() is a brand-new guest identity. */
+    forgetGuest(): Promise<void>;
+    signMessage(message: string): Promise<string>;
+    runTransaction(_evm?: EVMTransaction, _sol?: SolTransaction, _options?: SetOptions): Promise<TransactionResult>;
+    signTransaction(_t: Transaction | VersionedTransaction): Promise<Transaction | VersionedTransaction>;
+    signAndSubmitTransaction(): Promise<string>;
+    getNativeMethods(): Promise<any>;
+}

package/dist/auth/providers/guest-keystore.d.ts

@@ -0,0 +1,12 @@
+export interface GuestKey {
+    /** base58 public key — the account address. */
+    address: string;
+    /** Sign a UTF-8 message; returns a base64 detached signature. */
+    sign(message: string): Promise<string>;
+    /** True when backed by a non-extractable WebCrypto key. */
+    nonExtractable: boolean;
+}
+/** Get (or create) this device's durable guest key. */
+export declare function getGuestKey(): Promise<GuestKey>;
+/** Forget the guest key on this device (a fresh signInAnonymously mints a new one). */
+export declare function clearGuestKey(): Promise<void>;

package/dist/auth/providers/mock-auth-provider.d.ts

@@ -0,0 +1,49 @@
+import { AuthProvider, User, TransactionResult, SolTransaction, EVMTransaction } from '@bounded-sh/core';
+import { SetOptions } from '@bounded-sh/core';
+import { Transaction, VersionedTransaction } from '@solana/web3.js';
+export declare const DEFAULT_TEST_ADDRESS = "HKbZbRR7jWWR5VRN8KFjvTCHEzJQgameYxKQxh2gPoof";
+/**
+ * MockAuthProvider bypasses real wallet authentication for testing purposes.
+ * Uses session storage to simulate logged-in user, with fallback to default test address.
+ *
+ * This is enabled by passing mockAuth: true to init()
+ */
+export declare class MockAuthProvider implements AuthProvider {
+    /**
+     * Mock login - reads user from session storage or uses default test address
+     */
+    login(): Promise<User | null>;
+    /**
+     * Mock transaction - returns fake signature without actual blockchain interaction
+     * The real transaction will be handled by the backend using test headers
+     */
+    runTransaction(evmTransactionData?: EVMTransaction, solTransactionData?: SolTransaction, options?: SetOptions): Promise<TransactionResult>;
+    /**
+     * Mock message signing
+     */
+    signMessage(message: string): Promise<string>;
+    signMessageMock(message: string): Promise<string>;
+    /**
+     * Mock transaction signing - returns the transaction as-is (no actual signing)
+     */
+    signTransaction(transaction: Transaction | VersionedTransaction): Promise<Transaction | VersionedTransaction>;
+    /**
+     * Sign and submit transaction - not supported in mock environment.
+     * See the real providers (PhantomWalletProvider, SolanaKeypairProvider)
+     * for the full implementation with blockhash handling and feePayer support.
+     */
+    signAndSubmitTransaction(_transaction: Transaction | VersionedTransaction, _feePayer?: any): Promise<string>;
+    /**
+     * Restore session - only restores if user previously called login() explicitly.
+     * This prevents auto-login on first page load, but allows session persistence after login.
+     */
+    restoreSession(): Promise<User | null>;
+    /**
+     * Mock logout - clears test user from session storage
+     */
+    logout(): Promise<void>;
+    /**
+     * Get native wallet methods (not needed for mock auth)
+     */
+    getNativeMethods(): Promise<any>;
+}

package/dist/auth/providers/offchain-auth-provider.d.ts

@@ -0,0 +1,56 @@
+import { AuthProvider, User, TransactionResult, EVMTransaction, SolTransaction } from "@bounded-sh/core";
+import { SetOptions } from "@bounded-sh/core";
+import { Transaction, VersionedTransaction } from "@solana/web3.js";
+export interface OffchainAuthProviderConfig {
+    onSigningStart?: () => void;
+    onSigningComplete?: (signature: string) => void;
+    onSigningError?: (error: Error) => void;
+}
+/**
+ * OffchainAuthProvider wraps a real auth provider (e.g., Phantom) for the poofnet environment.
+ *
+ * For signMessageMock, this shows a custom confirmation modal and generates a mock signature.
+ * This is used for offchain transaction signing. For real wallet signing, use signMessage
+ * which delegates to the wrapped provider.
+ */
+export declare class OffchainAuthProvider implements AuthProvider {
+    private wrappedProvider;
+    private config;
+    private modalContainer;
+    constructor(wrappedProvider: AuthProvider, config?: OffchainAuthProviderConfig);
+    login(): Promise<User | null>;
+    logout(): Promise<void>;
+    restoreSession(): Promise<User | null>;
+    runTransaction(evmTransactionData?: EVMTransaction, solTransactionData?: SolTransaction, options?: SetOptions): Promise<TransactionResult>;
+    signTransaction(tx: Transaction | VersionedTransaction): Promise<Transaction | VersionedTransaction>;
+    /**
+     * Sign and submit transaction - not supported in poofnet environment.
+     * See the real providers (PhantomWalletProvider, SolanaKeypairProvider)
+     * for the full implementation with blockhash handling and feePayer support.
+     */
+    signAndSubmitTransaction(_transaction: Transaction | VersionedTransaction, _feePayer?: any): Promise<string>;
+    getNativeMethods(): Promise<any>;
+    signMessage(message: string): Promise<string>;
+    signMessageMock(message: string): Promise<string>;
+    private showUnsupportedTransactionModal;
+    private getUnsupportedModalHTML;
+    private showTransactionModal;
+    private closeModal;
+    /**
+     * Escape a value for safe interpolation into an HTML string.
+     *
+     * Transaction messages are attacker-influenceable (they originate from
+     * server responses / app-supplied data), so every value derived from them
+     * MUST be escaped before being placed into innerHTML. Without this, a field
+     * key/value, path segment, document id, or raw message containing markup
+     * such as `<img src=x onerror=...>` would execute in the dApp origin and
+     * could exfiltrate the stored session (idToken/refreshToken).
+     */
+    private escapeHtml;
+    private formatPath;
+    private formatFieldValue;
+    private getActionDescription;
+    private getModalHTML;
+    private getModalStyles;
+    private generateMockSignature;
+}