@seaverse/dataservice 1.6.1 → 1.6.2

package/README.md

@@ -17,19 +17,58 @@ A TypeScript/JavaScript SDK for universal data storage with PostgREST backend. S
 npm install @seaverse/dataservice
 ```
 
-## Quick Start
+## Package Exports
+
+This package uses a **factory pattern** for client creation. Here's what it exports:
+
+**Functions:**
+- `createClient(config)` - Factory function to create a client instance (async)
+- `debugSetToken(token)` - Set debug token for testing (call before createClient)
+
+**Types (TypeScript):**
+- `DataServiceClient` - Type of the client instance (**not a constructor**)
+- `DataRecord<T>` - Type of stored records
+- `Collection<T>` - Type of collection instances
+- `QueryBuilder<T>` - Type of query builder instances
+- `DataTable` - Type of data table instances
+- `ClientConfig` - Configuration options for createClient
+- `DataServiceError` - Error class for API errors
+
+**Constants:**
+- `VERSION` - SDK version string
+
+**Important:** Always use `createClient()` to create clients. `DataServiceClient` is a TypeScript type, not a class constructor.
 
 ```typescript
+// ✓ CORRECT
 import { createClient } from '@seaverse/dataservice';
+const client = await createClient({});
+
+// ✗ WRONG - DataServiceClient is not a constructor
+import { DataServiceClient } from '@seaverse/dataservice';
+const client = new DataServiceClient(); // This will fail!
+```
 
-// Auto-fetch token from parent page (iframe)
+## Quick Start
+
+### Creating a Client
+
+The SDK uses a **factory function pattern**. Always use `createClient()`:
+
+```typescript
+import { createClient, debugSetToken } from '@seaverse/dataservice';
+
+// Production: Auto-fetch token from parent page (when running in iframe)
 const client = await createClient({});
 
-// For development/testing, use debugSetToken
-import { debugSetToken } from '@seaverse/dataservice';
+// Development/Testing: Use debug token
 debugSetToken('your-test-token');
 const client = await createClient({});
+```
 
+### Basic Operations
+
+```typescript
 // Store user preferences (single record)
 const userPrefs = client.userData.collection('user_preferences');
 await userPrefs.insert({

package/dist/index.d.mts

@@ -214,7 +214,27 @@ interface DataTable {
 /**
  * Main client interface
  *
+ * **IMPORTANT:** This is a TypeScript type definition, NOT a class constructor.
+ * Use the `createClient()` factory function to create client instances.
+ *
  * AI-friendly: Entry point with clear hierarchy
+ *
+ * @example Correct Usage
+ * ```typescript
+ * import { createClient } from '@seaverse/dataservice';
+ *
+ * // ✓ CORRECT - Use factory function
+ * const client = await createClient({});
+ * console.log(client.appId);
+ * ```
+ *
+ * @example INCORRECT Usage
+ * ```typescript
+ * import { DataServiceClient } from '@seaverse/dataservice';
+ *
+ * // ✗ WRONG - DataServiceClient is NOT a constructor
+ * const client = new DataServiceClient(); // This will throw an error!
+ * ```
  */
 interface DataServiceClient {
     /** Automatically extracted application ID from current URL */
@@ -293,13 +313,15 @@ declare function createClient(config?: ClientConfig): Promise<DataServiceClient>
  *
  * AI-Friendly Universal Data Storage for TypeScript/JavaScript
  *
+ * **IMPORTANT:** This SDK uses a factory pattern. Use `createClient()` to create instances.
+ *
  * @packageDocumentation
  *
  * @example Basic Usage with Auto Token Fetch
  * ```typescript
  * import { createClient, debugSetToken } from '@seaverse/dataservice';
  *
- * // Auto-fetch token from parent page (iframe)
+ * // ✓ CORRECT - Use factory function
  * const client = await createClient({});
  *
  * // For development/testing, use debugSetToken
@@ -323,8 +345,15 @@ declare function createClient(config?: ClientConfig): Promise<DataServiceClient>
  *   .limit(10)
  *   .execute();
  * ```
+ *
+ * @example INCORRECT Usage - Do NOT do this
+ * ```typescript
+ * // ✗ WRONG - DataServiceClient is a type, not a constructor
+ * import { DataServiceClient } from '@seaverse/dataservice';
+ * const client = new DataServiceClient(); // This will fail!
+ * ```
  */
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.6.2";
 
 export { type APIError, type ClientConfig, type Collection, type DataRecord, type DataServiceClient, DataServiceError, type DataTable, type OrderOptions, type QueryBuilder, type QueryFilter, type UserDataStats, VERSION, createClient, debugSetToken };

package/dist/index.d.ts

@@ -214,7 +214,27 @@ interface DataTable {
 /**
  * Main client interface
  *
+ * **IMPORTANT:** This is a TypeScript type definition, NOT a class constructor.
+ * Use the `createClient()` factory function to create client instances.
+ *
  * AI-friendly: Entry point with clear hierarchy
+ *
+ * @example Correct Usage
+ * ```typescript
+ * import { createClient } from '@seaverse/dataservice';
+ *
+ * // ✓ CORRECT - Use factory function
+ * const client = await createClient({});
+ * console.log(client.appId);
+ * ```
+ *
+ * @example INCORRECT Usage
+ * ```typescript
+ * import { DataServiceClient } from '@seaverse/dataservice';
+ *
+ * // ✗ WRONG - DataServiceClient is NOT a constructor
+ * const client = new DataServiceClient(); // This will throw an error!
+ * ```
  */
 interface DataServiceClient {
     /** Automatically extracted application ID from current URL */
@@ -293,13 +313,15 @@ declare function createClient(config?: ClientConfig): Promise<DataServiceClient>
  *
  * AI-Friendly Universal Data Storage for TypeScript/JavaScript
  *
+ * **IMPORTANT:** This SDK uses a factory pattern. Use `createClient()` to create instances.
+ *
  * @packageDocumentation
  *
  * @example Basic Usage with Auto Token Fetch
  * ```typescript
  * import { createClient, debugSetToken } from '@seaverse/dataservice';
  *
- * // Auto-fetch token from parent page (iframe)
+ * // ✓ CORRECT - Use factory function
  * const client = await createClient({});
  *
  * // For development/testing, use debugSetToken
@@ -323,8 +345,15 @@ declare function createClient(config?: ClientConfig): Promise<DataServiceClient>
  *   .limit(10)
  *   .execute();
  * ```
+ *
+ * @example INCORRECT Usage - Do NOT do this
+ * ```typescript
+ * // ✗ WRONG - DataServiceClient is a type, not a constructor
+ * import { DataServiceClient } from '@seaverse/dataservice';
+ * const client = new DataServiceClient(); // This will fail!
+ * ```
  */
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.6.2";
 
 export { type APIError, type ClientConfig, type Collection, type DataRecord, type DataServiceClient, DataServiceError, type DataTable, type OrderOptions, type QueryBuilder, type QueryFilter, type UserDataStats, VERSION, createClient, debugSetToken };

package/dist/index.js

@@ -425,7 +425,7 @@ async function createClient(config = {}) {
 }
 
 // src/index.ts
-var VERSION = "1.0.0";
+var VERSION = "1.6.2";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DataServiceError,

package/dist/index.mjs

@@ -396,7 +396,7 @@ async function createClient(config = {}) {
 }
 
 // src/index.ts
-var VERSION = "1.0.0";
+var VERSION = "1.6.2";
 export {
   DataServiceError,
   VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seaverse/dataservice",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "AI-Friendly Universal Data Storage SDK for TypeScript/JavaScript",
   "main": "dist/index.js",
   "module": "dist/index.mjs",