@seaverse/dataservice 1.1.0 → 1.3.0

package/README.md

@@ -1,6 +1,15 @@
-# SeaVerse Data Service SDK
+# @seaverse/dataservice
 
-TypeScript/JavaScript SDK for universal data storage with PostgREST.
+A TypeScript/JavaScript SDK for universal data storage with PostgREST backend. Store and query JSON data with automatic user isolation and type safety.
+
+## Features
+
+- **Type-safe**: Full TypeScript support with generic types
+- **Secure**: Built on PostgreSQL Row-Level Security (RLS)
+- **Flexible**: Store any JSON data structure
+- **Query builder**: Fluent API for complex queries
+- **Auto-extraction**: Automatically extracts app ID from URL
+- **UUID support**: Client-side or server-side ID generation
 
 ## Installation
 
@@ -13,169 +22,271 @@ npm install @seaverse/dataservice
 ```typescript
 import { createClient } from '@seaverse/dataservice';
 
-// appId is automatically extracted from current URL
+// Create client (Bearer prefix auto-added, uses default SeaVerse API, appId auto-extracted from URL)
 const client = createClient({
-  url: 'https://your-postgrest-api.example.com',
-  token: 'Bearer your-jwt-token-here',
+  token: 'your-jwt-token',
 });
 
-// Insert
-const order = await client.userData
-  .collection('orders')
-  .insert({
-    order_number: 'ORD-001',
-    status: 'pending',
-    total: 99.99,
-  });
+// Access user data table
+const orders = client.userData.collection('orders');
 
-// Get by ID
-const record = await client.userData
-  .collection('orders')
-  .get(order.id);
+// Insert data
+const order = await orders.insert({
+  order_number: 'ORD-001',
+  status: 'pending',
+  total: 99.99,
+});
 
-// Query
-const results = await client.userData
-  .collection('orders')
+// Query data
+const pending = await orders
   .select()
   .eq('data->>status', 'pending')
   .order('created_at', { descending: true })
-  .limit(10)
   .execute();
 
-// Update
-await client.userData
-  .collection('orders')
-  .patch(order.id, { status: 'completed' });
+// Update data
+await orders.patch(order.id, { status: 'completed' });
+
+// Delete single record
+await orders.delete(order.id);
 
-// Delete
-await client.userData
-  .collection('orders')
-  .delete(order.id);
+// Or delete all records in collection
+const deletedCount = await orders.deleteAll();
 ```
 
 ## Core Concepts
 
-### Hierarchy
+### Data Hierarchy
 
 ```
-Client → DataTable (user_data) → Collection (collection_name) → Data (JSONB)
+DataServiceClient
+  └── DataTable (e.g., userData)
+      └── Collection (e.g., "orders")
+          └── DataRecord (JSONB data + metadata)
 ```
 
-### Application ID (appId)
+### Application ID
 
-**Automatic Extraction**: The SDK automatically extracts `app_id` from the current URL:
+The SDK automatically extracts `app_id` from the current environment:
 
+**Browser**: Extracted from URL hostname
 ```
-URL: https://app_8e5e867e-user_f4ed2364ffcf24d6c6707d5ca5e4fe6d.app.seaverse.ai
-→ appId: app_8e5e867e-user_f4ed2364ffcf24d6c6707d5ca5e4fe6d
-
-URL: https://example.com
-→ appId: example.com
+https://app_8e5e867e-user_f4ed2364.app.seaverse.ai
+→ appId: "app_8e5e867e-user_f4ed2364"
 ```
 
-**Node.js Environment**: Set via environment variable:
+**Node.js**: Set via environment variable
 ```bash
 export SEAVERSE_APP_ID=my-app-id
 ```
 
-### Unique Constraint
+Access the extracted ID:
+```typescript
+console.log(client.appId); // "app_8e5e867e-user_f4ed2364"
+```
+
+### Data Tables
+
+The SDK provides access to different data tables with different permission scopes:
+
+- **`userData`**: User-specific data (isolated by user_id)
+- More tables coming soon (public data, shared data, etc.)
 
-**Important**: Only ONE record per `(user_id, app_id, collection_name)`.
+### Collections
 
-For multiple records, use unique collection names:
+Collections are logical groupings within a table. Each collection stores one record per `(user_id, app_id, collection_name)` combination.
+
+**Important**: To store multiple records, use unique collection names:
 
 ```typescript
-// ✓ Correct
-await client.userData.collection('orders_1').insert(order1);
-await client.userData.collection('orders_2').insert(order2);
+// ✓ Correct: Unique collection names
+await client.userData.collection('order_1').insert(order1);
+await client.userData.collection('order_2').insert(order2);
+
+// ✓ Or use batch insert helper
+await client.userData.batchInsert('order', [order1, order2]);
+// Creates: order_0, order_1, order_2, ...
+
+// ✗ Wrong: Same collection name
+await client.userData.collection('order').insert(order1);
+await client.userData.collection('order').insert(order2); // Error: 409 Conflict
+```
 
-// ✓ Or use batch insert
-await client.userData.batchInsert('orders', [order1, order2]);
+### Data Records
 
-// ✗ Wrong - will fail
-await client.userData.collection('orders').insert(order1);
-await client.userData.collection('orders').insert(order2); // Error: 409 Conflict
+Each record contains:
+
+```typescript
+interface DataRecord<T> {
+  id: string;              // UUID primary key
+  user_id: string;         // Owner user ID
+  app_id: string;          // Application ID
+  collection_name: string; // Collection identifier
+  data: T;                 // Your JSON data
+  created_at: string;      // ISO timestamp
+  updated_at: string;      // ISO timestamp
+  deleted_at: string | null; // Soft delete timestamp
+}
 ```
 
 ## API Reference
 
-### Client
+### Client Creation
 
 ```typescript
-createClient(config: ClientConfig): DataServiceClient
+import { createClient } from '@seaverse/dataservice';
 
-interface ClientConfig {
-  url: string;           // PostgREST API URL
-  token: string;         // JWT token with user_id in payload
+const client = createClient({
+  token: string;            // JWT token (Bearer prefix optional, auto-added if missing)
+  url?: string;             // PostgREST API URL (default: https://dataservice-api.seaverse.ai)
   options?: {
-    timeout?: number;    // Request timeout (ms, default: 30000)
-    headers?: Record<string, string>;
+    timeout?: number;       // Request timeout in ms (default: 30000)
+    headers?: Record<string, string>; // Additional headers
   };
-}
+});
+```
 
-// Client properties
-client.appId: string     // Auto-extracted from URL
-client.userData: DataTable
+**Examples:**
+
+```typescript
+// Use default SeaVerse API (Bearer prefix auto-added)
+const client = createClient({
+  token: 'your-jwt-token',
+});
+
+// Or with explicit Bearer prefix (both work)
+const client = createClient({
+  token: 'Bearer your-jwt-token',
+});
+
+// Use custom API endpoint
+const client = createClient({
+  url: 'https://your-custom-api.example.com',
+  token: 'your-jwt-token',
+});
 ```
 
-### DataTable
+### DataTable Methods
 
 ```typescript
+// Get a collection
 client.userData.collection<T>(name: string): Collection<T>
-client.userData.batchInsert<T>(baseName: string, records: T[]): Promise<DataRecord<T>[]>
+
+// Batch insert multiple records
+client.userData.batchInsert<T>(
+  baseName: string,
+  records: T[]
+): Promise<DataRecord<T>[]>
 ```
 
-### Collection
+### Collection Methods
+
+#### Create
 
 ```typescript
-// Create
-collection.insert(data: T, id?: string): Promise<DataRecord<T>>  // Optional UUID
+// Insert with auto-generated UUID
+collection.insert(data: T): Promise<DataRecord<T>>
 
-// Read
+// Insert with custom UUID
+collection.insert(data: T, id: string): Promise<DataRecord<T>>
+```
+
+#### Read
+
+```typescript
+// Get by ID
 collection.get(id: string): Promise<DataRecord<T> | null>
 collection.selectById(id: string): Promise<DataRecord<T> | null>
+
+// Query builder
 collection.select(): QueryBuilder<T>
+
+// Search by criteria
 collection.search(criteria: Partial<T>): Promise<DataRecord<T>[]>
+
+// Count records
 collection.count(): Promise<number>
+```
+
+#### Update
 
-// Update
+```typescript
+// Full update (replaces entire data object)
 collection.update(id: string, data: T): Promise<DataRecord<T>>
+
+// Partial update (merges with existing data)
 collection.patch(id: string, partial: Partial<T>): Promise<DataRecord<T>>
+```
+
+#### Delete
 
-// Delete
+```typescript
+// Hard delete single record (permanent)
 collection.delete(id: string): Promise<void>
+
+// Hard delete all records in collection (returns count of deleted records)
+collection.deleteAll(): Promise<number>
+
+// Soft delete (sets deleted_at timestamp)
 collection.softDelete(id: string): Promise<boolean>
+
+// Restore soft-deleted record
 collection.restore(id: string): Promise<boolean>
 ```
 
-**Note**: All IDs are UUIDs (strings). Database auto-generates if not provided.
-
 ### Query Builder
 
+Build complex queries with a fluent API:
+
 ```typescript
-query
-  .eq(field, value)      // Equal
-  .neq(field, value)     // Not equal
-  .gt(field, value)      // Greater than
-  .gte(field, value)     // Greater than or equal
-  .lt(field, value)      // Less than
-  .lte(field, value)     // Less than or equal
-  .like(field, pattern)  // Pattern match (case-sensitive)
-  .ilike(field, pattern) // Pattern match (case-insensitive)
-  .in(field, values)     // Value in array
-  .contains(value)       // JSONB contains
-  .order(field, options) // Sort
-  .limit(count)          // Limit results
-  .offset(count)         // Skip results
-  .execute()             // Get results
-  .count()               // Get count
+collection.select()
+  // Comparison operators
+  .eq(field: string, value: any)      // Equal
+  .neq(field: string, value: any)     // Not equal
+  .gt(field: string, value: any)      // Greater than
+  .gte(field: string, value: any)     // Greater than or equal
+  .lt(field: string, value: any)      // Less than
+  .lte(field: string, value: any)     // Less than or equal
+
+  // Pattern matching
+  .like(field: string, pattern: string)   // Case-sensitive
+  .ilike(field: string, pattern: string)  // Case-insensitive
+
+  // Array operations
+  .in(field: string, values: any[])   // Value in array
+
+  // JSONB operations
+  .contains(value: any)               // JSONB contains
+
+  // Sorting and pagination
+  .order(field: string, options?: { descending?: boolean })
+  .limit(count: number)
+  .offset(count: number)
+
+  // Execute
+  .execute(): Promise<DataRecord<T>[]>
+  .count(): Promise<number>
 ```
 
-### Client Methods
+**Field syntax for JSONB queries**:
+- Use `data->>field` for text comparison: `.eq('data->>status', 'pending')`
+- Use `data->field` for numeric comparison: `.gt('data->total', '100')`
+
+### Client Utility Methods
 
 ```typescript
-client.getStats(): Promise<UserDataStats>
-client.health(): Promise<{ status: string; user_id: string }>
+// Get user data statistics
+client.getStats(): Promise<{
+  total_records: number;
+  total_collections: number;
+  storage_bytes: number;
+}>
+
+// Health check
+client.health(): Promise<{
+  status: string;
+  user_id: string;
+}>
 ```
 
 ## Examples
@@ -183,102 +294,181 @@ client.health(): Promise<{ status: string; user_id: string }>
 ### E-Commerce Orders
 
 ```typescript
+import { createClient } from '@seaverse/dataservice';
+
 type Order = {
   order_number: string;
   customer_email: string;
-  items: Array<{ product_id: string; quantity: number; price: number }>;
+  items: Array<{
+    product_id: string;
+    quantity: number;
+    price: number;
+  }>;
   status: 'pending' | 'processing' | 'shipped' | 'delivered';
   total: number;
+  notes?: string;
 };
 
+const client = createClient({
+  token: process.env.JWT_TOKEN!,
+});
+
 const orders = client.userData.collection<Order>('orders');
 
-// Create
+// Create order
 const order = await orders.insert({
   order_number: `ORD-${Date.now()}`,
   customer_email: 'customer@example.com',
-  items: [{ product_id: 'PROD-001', quantity: 2, price: 29.99 }],
+  items: [
+    { product_id: 'PROD-001', quantity: 2, price: 29.99 },
+    { product_id: 'PROD-002', quantity: 1, price: 49.99 },
+  ],
   status: 'pending',
-  total: 59.98,
+  total: 109.97,
 });
 
-// Query
-const pending = await orders
+console.log('Order created:', order.id);
+
+// Query pending orders over $50
+const pendingOrders = await orders
   .select()
   .eq('data->>status', 'pending')
-  .gt('data->>total', '50')
+  .gt('data->total', '50')
   .order('created_at', { descending: true })
+  .limit(10)
   .execute();
 
-// Update
+console.log(`Found ${pendingOrders.length} pending orders`);
+
+// Update order status
 await orders.patch(order.id, { status: 'shipped' });
+
+// Search by customer email
+const customerOrders = await orders.search({
+  customer_email: 'customer@example.com',
+});
+
+// Delete a specific order
+await orders.delete(order.id);
+
+// Delete all orders (useful for cleanup)
+const deletedCount = await orders.deleteAll();
+console.log(`Deleted ${deletedCount} orders`);
 ```
 
-### GPT Conversations
+### Chat Conversations
 
 ```typescript
+type Message = {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  timestamp: string;
+};
+
 type Conversation = {
   title: string;
   model: string;
-  messages: Array<{
-    role: 'user' | 'assistant' | 'system';
-    content: string;
-    timestamp: string;
-  }>;
+  messages: Message[];
+  metadata?: {
+    tokens_used?: number;
+    cost?: number;
+  };
 };
 
 const conversations = client.userData.collection<Conversation>('chats');
 
+// Create conversation
 const conv = await conversations.insert({
-  title: 'Project Planning',
+  title: 'Project Planning Discussion',
   model: 'claude-3-opus',
   messages: [
     {
       role: 'user',
-      content: 'Help me plan a new feature',
+      content: 'Help me plan a new feature for my app',
       timestamp: new Date().toISOString(),
     },
   ],
 });
 
-// Add message
-const retrieved = await conversations.get(conv.id);
-await conversations.patch(conv.id, {
-  messages: [
-    ...retrieved!.data.messages,
-    {
-      role: 'assistant',
-      content: 'I can help you with that...',
-      timestamp: new Date().toISOString(),
-    },
-  ],
+// Add assistant response
+const current = await conversations.get(conv.id);
+if (current) {
+  await conversations.patch(conv.id, {
+    messages: [
+      ...current.data.messages,
+      {
+        role: 'assistant',
+        content: 'I can help you with that. What feature are you thinking about?',
+        timestamp: new Date().toISOString(),
+      },
+    ],
+  });
+}
+
+// List recent conversations
+const recent = await conversations
+  .select()
+  .order('updated_at', { descending: true })
+  .limit(20)
+  .execute();
+```
+
+### User Preferences
+
+```typescript
+type UserPreferences = {
+  theme: 'light' | 'dark' | 'auto';
+  language: string;
+  notifications: {
+    email: boolean;
+    push: boolean;
+    sms: boolean;
+  };
+  privacy: {
+    profile_visible: boolean;
+    show_activity: boolean;
+  };
+};
+
+const prefs = client.userData.collection<UserPreferences>('preferences');
+
+// Initialize preferences
+await prefs.insert({
+  theme: 'auto',
+  language: 'en',
+  notifications: {
+    email: true,
+    push: true,
+    sms: false,
+  },
+  privacy: {
+    profile_visible: true,
+    show_activity: false,
+  },
 });
+
+// Update theme only
+await prefs.patch(prefId, { theme: 'dark' });
 ```
 
 ## UUID Primary Keys
 
-All records use UUID strings as primary keys:
+All records use UUID strings as primary keys.
+
+### Auto-generated UUIDs
 
 ```typescript
-// Database auto-generates UUID
 const order = await orders.insert({
   order_number: 'ORD-001',
   status: 'pending',
 });
-console.log(order.id); // "550e8400-e29b-41d4-a716-446655440000"
-
-// Or provide your own UUID
-import { randomUUID } from 'crypto';
 
-const customId = randomUUID();
-const order2 = await orders.insert(
-  { order_number: 'ORD-002', status: 'pending' },
-  customId
-);
-console.log(order2.id === customId); // true
+console.log(order.id); // "550e8400-e29b-41d4-a716-446655440000"
 ```
 
-**Client-side UUID generation** (recommended for offline-first apps):
+### Custom UUIDs
+
+Useful for offline-first applications or client-side ID generation:
 
 ```typescript
 // Node.js
@@ -288,29 +478,40 @@ const id = randomUUID();
 // Browser
 const id = crypto.randomUUID();
 
-// TypeScript with uuid library
+// With uuid library
 import { v4 as uuidv4 } from 'uuid';
 const id = uuidv4();
+
+// Use custom ID
+const order = await orders.insert(
+  { order_number: 'ORD-002', status: 'pending' },
+  id
+);
 ```
 
 ## TypeScript Support
 
+Full type safety with generic types:
+
 ```typescript
-type MyData = {
+type Product = {
   name: string;
-  count: number;
+  price: number;
+  in_stock: boolean;
 };
 
-const collection = client.userData.collection<MyData>('items');
+const products = client.userData.collection<Product>('products');
 
-const record = await collection.insert({
-  name: 'Item 1',
-  count: 42,
+const product = await products.insert({
+  name: 'Widget',
+  price: 29.99,
+  in_stock: true,
 });
 
 // TypeScript knows the shape
-console.log(record.data.name);    // ✓ OK
-console.log(record.data.invalid); // ✗ TypeScript error
+console.log(product.data.name);     // ✓ string
+console.log(product.data.price);    // ✓ number
+console.log(product.data.invalid);  // ✗ TypeScript error
 ```
 
 ## Error Handling
@@ -322,26 +523,64 @@ try {
   await collection.insert(data);
 } catch (error) {
   if (error instanceof DataServiceError) {
-    console.error('Code:', error.code);
+    console.error('Error code:', error.code);
     console.error('Message:', error.message);
-    console.error('Status:', error.statusCode);
-
-    if (error.code === '23505') {
-      // Unique constraint violation
-      console.log('Collection name already exists');
+    console.error('HTTP status:', error.statusCode);
+
+    // Handle specific errors
+    switch (error.code) {
+      case '23505':
+        console.log('Duplicate collection name - use a different name');
+        break;
+      case 'PGRST301':
+        console.log('Authentication failed - check your token');
+        break;
+      default:
+        console.log('Unexpected error:', error.message);
     }
+  } else {
+    console.error('Unknown error:', error);
   }
 }
 ```
 
+Common error codes:
+- `23505`: Unique constraint violation (duplicate collection name)
+- `PGRST301`: JWT authentication failed
+- `PGRST204`: No rows returned
+- `PGRST116`: Invalid query syntax
+
+## Security
+
+The SDK is built on PostgreSQL Row-Level Security (RLS):
+
+- **JWT Authentication**: User identity from JWT token payload
+- **Automatic Isolation**: Each user can only access their own data
+- **No Admin Bypass**: Even database admins respect RLS policies
+- **Secure by Default**: No configuration needed
+
+Your JWT token must include a `user_id` claim:
+
+```json
+{
+  "user_id": "user_f4ed2364ffcf24d6c6707d5ca5e4fe6d",
+  "exp": 1735689600
+}
+```
+
 ## Development
 
 ### Setup
 
 ```bash
+# Clone repository
 git clone https://github.com/seaverse/dataservice
 cd dataservice
+
+# Install dependencies
 npm install
+
+# Build
 npm run build
 ```
 
@@ -351,7 +590,7 @@ npm run build
 # Copy environment template
 cp .env.example .env
 
-# Edit .env with your credentials
+# Configure your credentials
 # POSTGREST_URL=https://your-api.example.com
 # JWT_TOKEN=Bearer your-token-here
 
@@ -364,26 +603,15 @@ npm run test:examples
 - `npm run build` - Build the SDK
 - `npm run dev` - Build in watch mode
 - `npm run test:examples` - Run integration tests
-- `npm run lint` - Lint code
-- `npm run format` - Format code
-
-## Security
-
-Built on PostgreSQL Row-Level Security (RLS):
-- JWT authentication with user_id in payload
-- Automatic data isolation per user
-- No admin bypass
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md)
+- `npm run lint` - Lint code with ESLint
+- `npm run format` - Format code with Prettier
 
 ## License
 
-MIT - See [LICENSE](LICENSE)
+MIT
 
 ## Links
 
-- [GitHub](https://github.com/seaverse/dataservice)
-- [Issues](https://github.com/seaverse/dataservice/issues)
-- [AI Usage Guide](AI-USAGE-GUIDE.md)
+- [GitHub Repository](https://github.com/seaverse/dataservice)
+- [Report Issues](https://github.com/seaverse/dataservice/issues)
+- [SeaVerse Platform](https://seaverse.ai)

package/dist/index.d.mts

@@ -12,14 +12,13 @@
  * @example
  * ```typescript
  * const config: ClientConfig = {
- *   url: 'https://your-postgrest-api.example.com',
  *   token: 'Bearer your-jwt-token-here',
  * };
  * ```
  */
 interface ClientConfig {
-    /** PostgREST API base URL */
-    url: string;
+    /** PostgREST API base URL (default: https://dataservice-api.seaverse.ai) */
+    url?: string;
     /** JWT token containing user_id in payload.user_id */
     token: string;
     /** Optional configuration */
@@ -196,6 +195,8 @@ interface Collection<T = any> {
     patch(id: string, partial: Partial<T>): Promise<DataRecord<T>>;
     /** Hard delete a record by ID */
     delete(id: string): Promise<void>;
+    /** Hard delete all records in this collection */
+    deleteAll(): Promise<number>;
     /** Soft delete a record by ID (sets deleted_at) */
     softDelete(id: string): Promise<boolean>;
     /** Restore a soft-deleted record */
@@ -250,16 +251,27 @@ interface DataServiceClient {
  *
  * AI-friendly: Single entry point with clear configuration
  *
- * @param config - Client configuration with URL and JWT token
+ * @param config - Client configuration with JWT token (URL defaults to https://dataservice-api.seaverse.ai)
  * @returns DataServiceClient instance
  *
  * @example
  * ```typescript
+ * // Use default SeaVerse API endpoint (Bearer prefix auto-added)
+ * const client = createClient({
+ *   token: 'your-jwt-token-here',
+ * });
+ *
+ * // Or with explicit Bearer prefix (both work)
  * const client = createClient({
- *   url: 'https://your-postgrest-api.example.com',
  *   token: 'Bearer your-jwt-token-here',
  * });
  *
+ * // Or specify custom endpoint
+ * const client = createClient({
+ *   url: 'https://your-postgrest-api.example.com',
+ *   token: 'your-jwt-token-here',
+ * });
+ *
  * // appId is automatically extracted from current URL
  * // Direct access to collections - clean and simple
  * const order = await client.userData.collection('orders').insert({ ... });
@@ -277,15 +289,15 @@ declare function createClient(config: ClientConfig): DataServiceClient;
  *
  * @example Basic Usage
  * ```typescript
- * import { createClient } from '@seaverse/data-service-sdk';
+ * import { createClient } from '@seaverse/dataservice';
  *
- * // appId is automatically extracted from current URL
+ * // Create client (Bearer prefix auto-added, uses default SeaVerse API)
  * const client = createClient({
- *   url: 'https://postgrest.example.com',
  *   token: 'your-jwt-token',
  * });
  *
- * // Insert data - appId is automatically included
+ * // appId is automatically extracted from current URL
+ * // Insert data
  * const order = await client.userData.collection('orders').insert({
  *   order_number: 'ORD-123',
  *   status: 'pending',
@@ -296,7 +308,7 @@ declare function createClient(config: ClientConfig): DataServiceClient;
  * const orders = await client.userData
  *   .collection('orders')
  *   .select()
- *   .eq('status', 'pending')
+ *   .eq('data->>status', 'pending')
  *   .order('created_at', { descending: true })
  *   .limit(10)
  *   .execute();

package/dist/index.d.ts

@@ -12,14 +12,13 @@
  * @example
  * ```typescript
  * const config: ClientConfig = {
- *   url: 'https://your-postgrest-api.example.com',
  *   token: 'Bearer your-jwt-token-here',
  * };
  * ```
  */
 interface ClientConfig {
-    /** PostgREST API base URL */
-    url: string;
+    /** PostgREST API base URL (default: https://dataservice-api.seaverse.ai) */
+    url?: string;
     /** JWT token containing user_id in payload.user_id */
     token: string;
     /** Optional configuration */
@@ -196,6 +195,8 @@ interface Collection<T = any> {
     patch(id: string, partial: Partial<T>): Promise<DataRecord<T>>;
     /** Hard delete a record by ID */
     delete(id: string): Promise<void>;
+    /** Hard delete all records in this collection */
+    deleteAll(): Promise<number>;
     /** Soft delete a record by ID (sets deleted_at) */
     softDelete(id: string): Promise<boolean>;
     /** Restore a soft-deleted record */
@@ -250,16 +251,27 @@ interface DataServiceClient {
  *
  * AI-friendly: Single entry point with clear configuration
  *
- * @param config - Client configuration with URL and JWT token
+ * @param config - Client configuration with JWT token (URL defaults to https://dataservice-api.seaverse.ai)
  * @returns DataServiceClient instance
  *
  * @example
  * ```typescript
+ * // Use default SeaVerse API endpoint (Bearer prefix auto-added)
+ * const client = createClient({
+ *   token: 'your-jwt-token-here',
+ * });
+ *
+ * // Or with explicit Bearer prefix (both work)
  * const client = createClient({
- *   url: 'https://your-postgrest-api.example.com',
  *   token: 'Bearer your-jwt-token-here',
  * });
  *
+ * // Or specify custom endpoint
+ * const client = createClient({
+ *   url: 'https://your-postgrest-api.example.com',
+ *   token: 'your-jwt-token-here',
+ * });
+ *
  * // appId is automatically extracted from current URL
  * // Direct access to collections - clean and simple
  * const order = await client.userData.collection('orders').insert({ ... });
@@ -277,15 +289,15 @@ declare function createClient(config: ClientConfig): DataServiceClient;
  *
  * @example Basic Usage
  * ```typescript
- * import { createClient } from '@seaverse/data-service-sdk';
+ * import { createClient } from '@seaverse/dataservice';
  *
- * // appId is automatically extracted from current URL
+ * // Create client (Bearer prefix auto-added, uses default SeaVerse API)
  * const client = createClient({
- *   url: 'https://postgrest.example.com',
  *   token: 'your-jwt-token',
  * });
  *
- * // Insert data - appId is automatically included
+ * // appId is automatically extracted from current URL
+ * // Insert data
  * const order = await client.userData.collection('orders').insert({
  *   order_number: 'ORD-123',
  *   status: 'pending',
@@ -296,7 +308,7 @@ declare function createClient(config: ClientConfig): DataServiceClient;
  * const orders = await client.userData
  *   .collection('orders')
  *   .select()
- *   .eq('status', 'pending')
+ *   .eq('data->>status', 'pending')
  *   .order('created_at', { descending: true })
  *   .limit(10)
  *   .execute();

package/dist/index.js

@@ -57,11 +57,12 @@ var HTTPClient = class {
   fetchFn;
   timeout;
   constructor(config) {
-    this.baseUrl = config.url.replace(/\/$/, "");
+    this.baseUrl = (config.url || "https://dataservice-api.seaverse.ai").replace(/\/$/, "");
     this.fetchFn = config.options?.fetch || globalThis.fetch;
     this.timeout = config.options?.timeout || 3e4;
+    const token = config.token.startsWith("Bearer ") ? config.token : `Bearer ${config.token}`;
     this.headers = {
-      "Authorization": config.token,
+      "Authorization": token,
       "Content-Type": "application/json",
       "Prefer": "return=representation",
       ...config.options?.headers
@@ -285,6 +286,18 @@ var CollectionImpl = class {
       `/user_data?id=eq.${id}&app_id=eq.${this.appId}&collection_name=eq.${this.collectionName}`
     );
   }
+  async deleteAll() {
+    const records = await this.client.get(
+      `/user_data?app_id=eq.${this.appId}&collection_name=eq.${this.collectionName}`
+    );
+    const count = records.length;
+    if (count > 0) {
+      await this.client.delete(
+        `/user_data?app_id=eq.${this.appId}&collection_name=eq.${this.collectionName}`
+      );
+    }
+    return count;
+  }
   async softDelete(id) {
     const response = await this.client.post("/rpc/soft_delete_user_data", {
       p_id: id

package/dist/index.mjs

@@ -29,11 +29,12 @@ var HTTPClient = class {
   fetchFn;
   timeout;
   constructor(config) {
-    this.baseUrl = config.url.replace(/\/$/, "");
+    this.baseUrl = (config.url || "https://dataservice-api.seaverse.ai").replace(/\/$/, "");
     this.fetchFn = config.options?.fetch || globalThis.fetch;
     this.timeout = config.options?.timeout || 3e4;
+    const token = config.token.startsWith("Bearer ") ? config.token : `Bearer ${config.token}`;
     this.headers = {
-      "Authorization": config.token,
+      "Authorization": token,
       "Content-Type": "application/json",
       "Prefer": "return=representation",
       ...config.options?.headers
@@ -257,6 +258,18 @@ var CollectionImpl = class {
       `/user_data?id=eq.${id}&app_id=eq.${this.appId}&collection_name=eq.${this.collectionName}`
     );
   }
+  async deleteAll() {
+    const records = await this.client.get(
+      `/user_data?app_id=eq.${this.appId}&collection_name=eq.${this.collectionName}`
+    );
+    const count = records.length;
+    if (count > 0) {
+      await this.client.delete(
+        `/user_data?app_id=eq.${this.appId}&collection_name=eq.${this.collectionName}`
+      );
+    }
+    return count;
+  }
   async softDelete(id) {
     const response = await this.client.post("/rpc/soft_delete_user_data", {
       p_id: id

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seaverse/dataservice",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "AI-Friendly Universal Data Storage SDK for TypeScript/JavaScript",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -35,13 +35,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/seaverseai/sv-sdk.git",
-    "directory": "packages/dataservice"
+    "url": "https://github.com/seaverse/dataservice.git"
   },
   "bugs": {
-    "url": "https://github.com/seaverseai/sv-sdk/issues"
+    "url": "https://github.com/seaverse/dataservice/issues"
   },
-  "homepage": "https://github.com/seaverseai/sv-sdk/tree/main/packages/dataservice#readme",
+  "homepage": "https://github.com/seaverse/dataservice#readme",
   "devDependencies": {
     "@types/node": "^20.11.0",
     "@typescript-eslint/eslint-plugin": "^6.19.0",