@nextplus/js-sdk 0.0.10 → 0.0.12

package/README.md

@@ -10,22 +10,55 @@ npm install @nextplus/js-sdk
 
 ## Usage
 
-### Basic Configuration
+### Authentication Methods
+
+The SDK supports two authentication methods:
+
+1. **Token-based authentication** - Use an existing access token (recommended for React/browser apps)
+2. **Credential-based authentication** - Provide email/username + password (SDK handles login automatically)
+
+### Token-Based Authentication (Recommended for React/Browser Apps)
+
+Perfect for apps where authentication is handled separately (e.g., OAuth, Firebase Auth, custom auth):
 
 ```typescript
 import { configure } from '@nextplus/js-sdk';
 
-// Configure with email authentication
+// With explicit baseURL
 const sdk = configure({
-  baseURL: 'https://your-nextplus-instance.com/api',
+  baseURL: 'https://your-nextplus-instance.com',
+  accessToken: 'your-existing-token',
+  returnType: 'data', // 'data' | 'raw'
+});
+
+// Auto-detect baseURL in browser (uses window.location.origin + '/api')
+const sdk = configure({
+  accessToken: userToken, // from your auth provider
+  returnType: 'data',
+});
+
+// Use the SDK
+const tables = await sdk.TableService.find({});
+```
+
+### Credential-Based Authentication
+
+The SDK automatically handles login and token refresh:
+
+```typescript
+import { configure } from '@nextplus/js-sdk';
+
+// With email
+const sdk = configure({
+  baseURL: 'https://your-nextplus-instance.com',
   email: 'your-email@example.com',
   password: 'your-password',
-  returnType: 'data', // 'data' | 'raw'
+  returnType: 'data',
 });
 
-// Or configure with username authentication
+// With username
 const sdk = configure({
-  baseURL: 'https://your-nextplus-instance.com/api',
+  baseURL: 'https://your-nextplus-instance.com',
   username: 'your-username',
   password: 'your-password',
   returnType: 'data',
@@ -37,38 +70,344 @@ const sdk = configure({
 - **`'data'`**: Returns only the response data (default behavior)
 - **`'raw'`**: Returns the full response object with `{ data, request, response }`
 
+**Important:** The `returnType` setting only applies when using service methods through the SDK instance (e.g., `sdk.TableService.find()`). When using `sdk.client` directly with individual service imports, responses are always in raw format (`{ data, request, response }`).
+
+### Error Handling
+
+**By default**, non-OK responses return `{ error: ... }` instead of throwing:
+
+```typescript
+const response = await TableService.find({ limit: 10 });
+
+if ('error' in response) {
+  console.error('API Error:', response.error);
+} else {
+  console.log('Success:', response.data);
+}
+```
+
+**To make errors throw automatically**, use `throwOnError: true`:
+
+```typescript
+configure({
+  accessToken: token,
+  throwOnError: true, // Errors will throw
+});
+
+try {
+  const response = await TableService.find({ limit: 10 });
+  // Only success responses reach here
+} catch (error) {
+  // All API errors throw here
+  console.error('API Error:', error);
+}
+```
+
+| Configuration                   | Error Behavior              |
+| ------------------------------- | --------------------------- |
+| `returnType: 'data'` (Full SDK) | ✅ Throws errors            |
+| `returnType: 'raw'` (Full SDK)  | ❌ Returns `{ error: ... }` |
+| `throwOnError: true`            | ✅ Throws errors            |
+| Default (tree-shakeable)        | ❌ Returns `{ error: ... }` |
+
+### Usage Patterns
+
+**All patterns use the same `configure()` function!**
+
+#### Pattern 1: Full SDK (Convenient, with return type control)
+
+```typescript
+import { configure } from '@nextplus/js-sdk';
+
+const sdk = configure({
+  accessToken: userToken,
+  returnType: 'data', // Returns just the data
+});
+
+// Use service methods through SDK - returns transformed data
+const tables = await sdk.TableService.find({ limit: 10 });
+// tables = [{ ... }, { ... }] - just the array
+```
+
+#### Pattern 2a: Automatic Global Client (Cleanest - Recommended)
+
+```typescript
+import { configure, TableService, UserModelService } from '@nextplus/js-sdk';
+
+// Configure once - automatically becomes global default!
+configure({
+  accessToken: userToken,
+  throwOnError: true, // Make errors throw (optional)
+});
+
+// Use anywhere in your app - no client parameter needed!
+try {
+  const response = await TableService.find({ limit: 10 });
+  const user = await UserModelService.findById({ path: { id: '123' } });
+
+  // Returns raw response format
+  console.log(response.data); // The actual data
+} catch (error) {
+  // With throwOnError: true, errors are thrown
+  console.error('API Error:', error);
+}
+```
+
+**Benefits:**
+
+- ✅ Automatic - `configure()` sets global client automatically
+- ✅ No client parameter needed anywhere
+- ✅ Tree-shakeable - only import services you use
+- ✅ Optional error throwing with `throwOnError: true`
+- ✅ Clean code everywhere in your app
+
+#### Pattern 2b: Bound Services (Per-component)
+
+```typescript
+import { configure, TableService, UserModelService } from '@nextplus/js-sdk';
+
+// Configure once
+const sdk = configure({ accessToken: userToken });
+
+// Bind services - no need to pass client every time!
+const Tables = sdk.service(TableService);
+const Users = sdk.service(UserModelService);
+
+// Use bound services
+const response = await Tables.find({ limit: 10 });
+const user = await Users.findById({ path: { id: '123' } });
+```
+
+#### Pattern 2c: Manual Client (Explicit control)
+
+```typescript
+const sdk = configure({ accessToken: userToken });
+
+// Pass client explicitly each time
+const response = await TableService.find({
+  client: sdk.client,
+  limit: 10,
+});
+```
+
+#### Pattern 3: Manual Client Setup (Maximum control)
+
+```typescript
+import { TableService } from '@nextplus/js-sdk/services';
+import { createClient } from '@nextplus/js-sdk/sdk/client';
+
+const client = createClient({
+  baseUrl: window.location.origin + '/api',
+});
+
+// Add auth interceptor manually
+client.interceptors.request.use((req) => {
+  req.headers.set('Authorization', myToken);
+  return req;
+});
+
+const response = await TableService.find({ client });
+```
+
+**Comparison:**
+
+| Feature             | Pattern 1: Full SDK | Pattern 2: Tree-shakeable | Pattern 3: Manual |
+| ------------------- | ------------------- | ------------------------- | ----------------- |
+| Function            | `configure()`       | `configure()`             | `createClient()`  |
+| Service access      | `sdk.ServiceName.*` | Direct `ServiceName.*`    | Direct            |
+| Bundle size         | Larger              | Smaller                   | Smallest          |
+| Return type control | ✅ `'data'`/`'raw'` | ❌ Always raw             | ❌ Always raw     |
+| Auto-login          | ✅ (credentials)    | ✅ (credentials)          | ❌                |
+| Complexity          | Simple              | Simple                    | More control      |
+| Best for            | Full apps           | Modern bundlers           | Advanced use      |
+
+### Automatic Global Client
+
+**`configure()` automatically sets the global default client** - no manual setup needed!
+
+```typescript
+import { configure, TableService, UserModelService } from '@nextplus/js-sdk';
+
+// Configure once - automatically becomes global default!
+configure({ accessToken: token });
+
+// Use anywhere in your app - no client needed!
+const tables = await TableService.find({ limit: 10 });
+const users = await UserModelService.find({ limit: 10 });
+
+// No client parameter needed! ✨
+```
+
+**Use Cases:**
+
+```typescript
+// React app initialization
+function App() {
+  useEffect(() => {
+    // configure() automatically sets global client
+    configure({ accessToken: getAuthToken() });
+
+    return () => clearDefaultClient(); // Cleanup on unmount
+  }, []);
+
+  return <Routes />;
+}
+
+// Any component can now use services
+function TableList() {
+  const [tables, setTables] = useState([]);
+
+  useEffect(() => {
+    // No client parameter needed!
+    TableService.find({ limit: 100 }).then(res => setTables(res.data));
+  }, []);
+
+  return <div>{/* render tables */}</div>;
+}
+```
+
+**Manual Control (Optional):**
+
+```typescript
+// Set global client manually
+setDefaultClient(client);
+
+// Get current global client
+const client = getDefaultClient();
+
+// Clear global client (useful for logout)
+clearDefaultClient();
+```
+
+**Client Override:**
+
+You can still pass a `client` parameter to override the global default:
+
+```typescript
+configure({ accessToken: token1 }); // Sets global client
+
+// Uses global client
+await TableService.find({ limit: 10 });
+
+// Uses specific client (overrides global)
+await TableService.find({ client: customClient, limit: 10 });
+```
+
+### Interceptors (Request/Response Middleware)
+
+Add custom logic to all requests and responses:
+
+```typescript
+import { configure } from '@nextplus/js-sdk';
+
+const sdk = configure({ accessToken: token });
+
+// Request interceptor - runs before every request
+sdk.client.interceptors.request.use((request) => {
+  console.log('Request:', request.url);
+  // Add custom headers
+  request.headers.set('X-Custom-Header', 'value');
+  // Modify request
+  return request;
+});
+
+// Response interceptor - runs after every successful response
+sdk.client.interceptors.response.use((response) => {
+  console.log('Response:', response.status);
+  // Log or transform responses
+  return response;
+});
+
+// Error interceptor - runs on any error
+sdk.client.interceptors.error.use((error) => {
+  console.error('API Error:', error);
+  // Custom error handling, logging, etc.
+  throw error; // Re-throw or handle
+});
+```
+
+**Common Use Cases:**
+
+```typescript
+// Add request ID to all requests
+sdk.client.interceptors.request.use((request) => {
+  request.headers.set('X-Request-ID', crypto.randomUUID());
+  return request;
+});
+
+// Add retry logic
+sdk.client.interceptors.error.use(async (error) => {
+  if (error.response?.status === 429) {
+    // Rate limited - wait and retry
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    // Retry logic here
+  }
+  throw error;
+});
+
+// Log all API calls
+sdk.client.interceptors.request.use((request) => {
+  console.log(`[API] ${request.method} ${request.url}`);
+  return request;
+});
+```
+
+**Works with all patterns:**
+
+```typescript
+// Pattern 1: Full SDK
+const sdk = configure({ accessToken: token });
+sdk.client.interceptors.request.use(/* ... */);
+await sdk.TableService.find({});
+
+// Pattern 2: Tree-shakeable
+const Tables = sdk.service(TableService);
+await Tables.find({}); // Interceptors still apply!
+
+// Pattern 3: Manual
+await TableService.find({ client: sdk.client }); // Interceptors apply!
+```
+
 ### API Usage Examples
 
 ```typescript
-// Find tables with filters
+// Find with filters
+const tables = await sdk.TableService.find({
+  where: { name: 'my-table' },
+  limit: 10,
+  order: 'createdAt DESC',
+});
+
+// Find with filter object
 const tables = await sdk.TableService.find({
   filter: {
-    name: {
-      eq: 'my-table'
-    }
-  }
+    where: { name: 'my-table' },
+    limit: 10,
+  },
 });
 
-// Create a new table
+// Create a record
 const newTable = await sdk.TableService.create({
-  body: {
-    name: 'New Table',
-    // ... other table properties
-  }
+  name: 'New Table',
+  description: 'Table description',
+});
+
+// Update a record
+const updated = await sdk.TableService.prototypePatchAttributes({
+  path: { id: 'table-id' },
+  name: 'Updated Name',
 });
 
 // With raw response type
 const sdk = configure({
-  baseURL: 'https://api.example.com',
-  email: 'user@example.com',
-  password: 'password',
-  returnType: 'raw'
+  accessToken: 'token',
+  returnType: 'raw',
 });
 
 const response = await sdk.TableService.find({});
-console.log(response.data);      // Response data
-console.log(response.request);   // Request object
-console.log(response.response);  // Full HTTP response
+console.log(response.data); // Response data
+console.log(response.request); // Request object
+console.log(response.response); // Full HTTP response
 ```
 
 ## Development
@@ -116,36 +455,65 @@ Generated files are located in `src/sdk/` and should not be manually edited.
 
 ## Testing
 
-### Smoke Tests
-
-Run the smoke test to verify the SDK works correctly:
+### Test Commands
 
 ```bash
-# Make sure your NextPlus instance is running on localhost:3000
-npm run test
+# Run full test suite (builds first, then runs tests)
+npm test
+
+# Run tests directly from TypeScript (faster for development)
+npm run test:dev
+
+# Run tests in watch mode (re-runs on file changes)
+npm run test:watch
 ```
 
-The smoke test (`src/smoke.ts`) demonstrates:
+### Test Suite
+
+Make sure your NextPlus instance is running on `localhost:3000` before running tests.
+
+The test suite (`src/smoke.ts`) uses Node's built-in test runner and validates:
+
+- Token-based authentication
 - Email and username authentication
 - Different return types (`data` vs `raw`)
+- Tree-shakeable service imports
 - API calls to the TableService
-- Error handling
+- Configuration validation and error handling
 
 ### Manual Testing
 
 ```typescript
-// Create a test file
+// Test with token authentication
 import { configure } from '@nextplus/js-sdk';
 
 const sdk = configure({
-  baseURL: 'http://localhost:3000/api',
-  email: 'test@example.com',
-  password: 'password',
+  baseURL: 'http://localhost:3000',
+  accessToken: 'your-test-token',
 });
 
-// Test your API calls
 const result = await sdk.TableService.find({});
 console.log(result);
+
+// Test with credentials
+const sdk2 = configure({
+  baseURL: 'http://localhost:3000',
+  email: 'test@example.com',
+  password: 'password',
+});
+
+const result2 = await sdk2.TableService.find({});
+console.log(result2);
+
+// Test tree-shakeable imports
+import { configure, TableService } from '@nextplus/js-sdk';
+
+const sdk = configure({
+  accessToken: 'your-test-token',
+});
+
+const tables = await TableService.find({ client: sdk.client });
+console.log(tables);
 ```
 
 ## Publishing
@@ -205,6 +573,7 @@ export default {
 ### TypeScript
 
 The project uses modern TypeScript with:
+
 - ES2020 target
 - ESNext modules
 - Strict type checking

package/dist/{chunk-GMJM2AK6.js → chunk-ASHZA665.js}

@@ -104,7 +104,7 @@ import {
   WorkorderStatusService,
   WorkorderStatusTransitionService,
   WorkorderTemplateService
-} from "./chunk-O65NPNYE.js";
+} from "./chunk-PEBCO4EJ.js";
 import {
   __export
 } from "./chunk-FXXZNC42.js";