@inneropen/marvin-sdk 2.0.0-next.13 → 2.0.0-next.15

package/README.md

@@ -24,37 +24,57 @@ The SDK provides:
 ## Installation
 
 ```bash
-# Copy into your project
-cp -r /path/to/marvin/packages/marvin-sdk src/lib/marvin
+npm install @inneropen/marvin-sdk
 ```
 
-Or symlink for development:
+## Entry Points
 
-```bash
-ln -s /path/to/marvin/packages/marvin-sdk src/lib/marvin
+The SDK provides three distinct entry points for different use cases:
+
+### 📖 Publishing API (`/publish`)
+Read-only access to published content (frontends, websites)
+```typescript
+import { createMarvinClient } from '@inneropen/marvin-sdk/publish';
+```
+**Auth:** Site client tokens (`MARVIN_SITE_CLIENT_TOKEN`)
+
+### ⚙️ Platform API (`/platform`)
+Full CRUD admin operations (backend, CLI, automation)
+```typescript
+import { createPlatformClient } from '@inneropen/marvin-sdk/platform';
+```
+**Auth:** User tokens (`MARVIN_USER_TOKEN`) or session cookies
+
+### 🔐 Auth API (Default export)
+Public registration, login, password reset
+```typescript
+import { createAuthClient } from '@inneropen/marvin-sdk';
 ```
+**Auth:** None required (public endpoints)
 
-## Quick Start
+📚 **[See complete authentication guide →](./AUTHENTICATION.md)**
+
+## Quick Start - Publishing API
 
 ### 1. Configure Environment
 
 ```env
 MARVIN_API_URL=https://marvin.example.com
-MARVIN_SITE_CLIENT_TOKEN=your-token-here
+MARVIN_SITE_CLIENT_TOKEN=your-site-client-token
 MARVIN_WORKSPACE_SLUG=your-workspace
 ```
 
 ### 2. Create Client
 
-```ts
-import { createMarvinClient } from './marvin-sdk';
+```typescript
+import { createMarvinClient } from '@inneropen/marvin-sdk/publish';
 
 const marvin = createMarvinClient();
 ```
 
 ### 3. Fetch Content
 
-```ts
+```typescript
 // Get workspace
 const workspace = await marvin.getWorkspace();
 console.log(workspace.site?.title);
@@ -71,6 +91,35 @@ const projects = await marvin.collection('projects');
 const projectEntries = await projects.entries();
 ```
 
+## Quick Start - Platform API
+
+### Programmatic Admin Access
+
+```typescript
+import { createPlatformClient } from '@inneropen/marvin-sdk/platform';
+
+// From environment (MARVIN_USER_TOKEN)
+const platform = createPlatformClient();
+
+// Or explicit token
+const platform = createPlatformClient({
+  userToken: 'your-user-token'
+});
+
+// Full CRUD operations
+await platform.entries.create({
+  title: 'New Post',
+  content: 'Content here...',
+  collection_id: collectionId
+});
+
+await platform.entries.update(entryId, {
+  title: 'Updated Title'
+});
+
+await platform.entries.delete(entryId);
+```
+
 ## Architecture
 
 ### Workspace-First Design

package/dist/{HttpClient-BX5Gqd0w.d.cts → HttpClient-CdF3IHM1.d.cts}

@@ -33,11 +33,22 @@ declare class BearerTokenAuth implements AuthStrategy {
 /**
  * Session-based authentication (Platform/Admin APIs in browser)
  * Relies on HTTP-only cookies set by the server
+ * Optionally supports CSRF token protection
  */
 declare class SessionAuth implements AuthStrategy {
     private sessionToken?;
     private onUnauthorized?;
+    private csrfToken?;
     constructor(sessionToken?: string | undefined, onUnauthorized?: (() => Promise<void>) | undefined);
+    /**
+     * Set CSRF token for cross-site request forgery protection
+     * The token should be obtained from the server after login
+     */
+    setCsrfToken(token: string): void;
+    /**
+     * Get current CSRF token
+     */
+    getCsrfToken(): string | undefined;
     injectAuth(headers: Headers): void;
     handleUnauthorized(): Promise<void>;
     getDescription(): string;
@@ -54,6 +65,16 @@ declare class NoAuth implements AuthStrategy {
  * Base HTTP client for Marvin APIs
  */
 
+interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries: number;
+    /** Initial delay in ms before first retry (default: 1000) */
+    initialDelay: number;
+    /** Maximum delay in ms between retries (default: 10000) */
+    maxDelay: number;
+    /** HTTP status codes that should trigger a retry (default: [408, 429, 500, 502, 503, 504]) */
+    retryableStatuses: number[];
+}
 interface HttpClientConfig {
     baseUrl: string;
     auth: AuthStrategy;
@@ -61,6 +82,7 @@ interface HttpClientConfig {
     credentials?: RequestCredentials;
     timeout?: number;
     debug?: boolean;
+    retry?: Partial<RetryConfig>;
     logger?: {
         log: (message: string, ...args: unknown[]) => void;
         warn: (message: string, ...args: unknown[]) => void;
@@ -74,8 +96,13 @@ declare class HttpClient {
     private credentials;
     private timeout;
     private debug;
+    private retryConfig;
     private logger;
     constructor(config: HttpClientConfig);
+    /**
+     * Validate path parameter to prevent path traversal attacks
+     */
+    validatePathParam(param: string | number, paramName?: string): string;
     /**
      * Build full URL from endpoint
      */
@@ -89,13 +116,25 @@ declare class HttpClient {
      */
     buildQueryString(params: Record<string, string | number | boolean | undefined>): string;
     /**
-     * Perform HTTP request
+     * Sanitize data for logging by redacting sensitive fields
+     */
+    private sanitizeForLogging;
+    /**
+     * Calculate delay for retry with exponential backoff
+     */
+    private calculateRetryDelay;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+    /**
+     * Perform HTTP request with automatic retry on transient failures
      */
     request<T>(method: string, endpoint: string, options?: {
         body?: unknown;
         headers?: Record<string, string>;
         params?: Record<string, string | number | boolean | undefined>;
-    }): Promise<T>;
+    }, retryAttempt?: number): Promise<T>;
     /**
      * GET request
      */

package/dist/{HttpClient-BX5Gqd0w.d.ts → HttpClient-CdF3IHM1.d.ts}

@@ -33,11 +33,22 @@ declare class BearerTokenAuth implements AuthStrategy {
 /**
  * Session-based authentication (Platform/Admin APIs in browser)
  * Relies on HTTP-only cookies set by the server
+ * Optionally supports CSRF token protection
  */
 declare class SessionAuth implements AuthStrategy {
     private sessionToken?;
     private onUnauthorized?;
+    private csrfToken?;
     constructor(sessionToken?: string | undefined, onUnauthorized?: (() => Promise<void>) | undefined);
+    /**
+     * Set CSRF token for cross-site request forgery protection
+     * The token should be obtained from the server after login
+     */
+    setCsrfToken(token: string): void;
+    /**
+     * Get current CSRF token
+     */
+    getCsrfToken(): string | undefined;
     injectAuth(headers: Headers): void;
     handleUnauthorized(): Promise<void>;
     getDescription(): string;
@@ -54,6 +65,16 @@ declare class NoAuth implements AuthStrategy {
  * Base HTTP client for Marvin APIs
  */
 
+interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries: number;
+    /** Initial delay in ms before first retry (default: 1000) */
+    initialDelay: number;
+    /** Maximum delay in ms between retries (default: 10000) */
+    maxDelay: number;
+    /** HTTP status codes that should trigger a retry (default: [408, 429, 500, 502, 503, 504]) */
+    retryableStatuses: number[];
+}
 interface HttpClientConfig {
     baseUrl: string;
     auth: AuthStrategy;
@@ -61,6 +82,7 @@ interface HttpClientConfig {
     credentials?: RequestCredentials;
     timeout?: number;
     debug?: boolean;
+    retry?: Partial<RetryConfig>;
     logger?: {
         log: (message: string, ...args: unknown[]) => void;
         warn: (message: string, ...args: unknown[]) => void;
@@ -74,8 +96,13 @@ declare class HttpClient {
     private credentials;
     private timeout;
     private debug;
+    private retryConfig;
     private logger;
     constructor(config: HttpClientConfig);
+    /**
+     * Validate path parameter to prevent path traversal attacks
+     */
+    validatePathParam(param: string | number, paramName?: string): string;
     /**
      * Build full URL from endpoint
      */
@@ -89,13 +116,25 @@ declare class HttpClient {
      */
     buildQueryString(params: Record<string, string | number | boolean | undefined>): string;
     /**
-     * Perform HTTP request
+     * Sanitize data for logging by redacting sensitive fields
+     */
+    private sanitizeForLogging;
+    /**
+     * Calculate delay for retry with exponential backoff
+     */
+    private calculateRetryDelay;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+    /**
+     * Perform HTTP request with automatic retry on transient failures
      */
     request<T>(method: string, endpoint: string, options?: {
         body?: unknown;
         headers?: Record<string, string>;
         params?: Record<string, string | number | boolean | undefined>;
-    }): Promise<T>;
+    }, retryAttempt?: number): Promise<T>;
     /**
      * GET request
      */