@proveanything/smartlinks 1.2.4 → 1.3.2

package/README.md

@@ -80,6 +80,79 @@ const jwt = await auth.requestAdminJWT('collectionId')
 const publicJwt = await auth.requestPublicJWT('collectionId', 'productId', 'proofId')
 ```
 
+## Error Handling
+
+The SDK throws `SmartlinksApiError` for all API errors, providing structured access to:
+- **HTTP status code** (`statusCode` / `code`) - Numeric HTTP status (400, 401, 500, etc.)
+- **Server error code** (`errorCode`) - String identifier ("NOT_AUTHORIZED", "broadcasts.topic.invalid", etc.)
+- **Error message** (`message`) - Human-readable description
+- **Additional details** (`details`) - Server-specific fields
+
+### Automatic Error Normalization
+
+The SDK automatically normalizes various server error response formats into a consistent structure:
+
+```ts
+// Server may return errors in different formats:
+// { errorText: "...", errorCode: "..." }
+// { error: "...", message: "..." }
+// { ok: false, error: "..." }
+// { error: "..." }
+
+// All are normalized to SmartlinksApiError with consistent access:
+import { SmartlinksApiError, product } from '@proveanything/smartlinks'
+
+try {
+  const item = await product.get('collectionId', 'productId', false)
+} catch (error) {
+  if (error instanceof SmartlinksApiError) {
+    console.error({
+      message: error.message,       // "Error 404: Product not found"
+      statusCode: error.statusCode, // 404 (HTTP status)
+      code: error.code,             // 404 (same as statusCode)
+      errorCode: error.errorCode,   // "NOT_FOUND" (server error code string)
+      details: error.details,       // Additional server details
+      url: error.url,               // Failed URL
+    })
+    
+    // Handle specific server error codes (primary identifier)
+    switch (error.errorCode) {
+      case 'NOT_AUTHORIZED':
+        // Invalid credentials
+        break
+      case 'broadcasts.topic.invalid':
+        // Invalid broadcast topic
+        break
+      default:
+        // Fall back to HTTP status code
+        if (error.isNotFound()) {
+          // Handle 404
+        } else if (error.isAuthError()) {
+          // Handle 401/403 - redirect to login
+        }
+    }
+    
+    // Use helper methods for HTTP status-based handling
+    if (error.isRateLimited()) {
+      // Handle 429 - implement retry logic
+    } else if (error.isServerError()) {
+      // Handle 5xx - show maintenance message
+    }
+  }
+}
+```
+
+### Helper Methods
+
+- `error.isClientError()` - 4xx status codes
+- `error.isServerError()` - 5xx status codes  
+- `error.isAuthError()` - 401 or 403
+- `error.isNotFound()` - 404
+- `error.isRateLimited()` - 429
+- `error.toJSON()` - Serializable object for logging
+
+For comprehensive error handling examples and migration guidance, see [examples/error-handling-demo.ts](examples/error-handling-demo.ts).
+
 ## Common tasks
 
 ### Products
@@ -481,7 +554,18 @@ setExtraHeaders({ 'X-Debug': '1' })
 
 Explore every function, parameter, and type here:
 
-- API Summary (API_SUMMARY.md)
+- [API_SUMMARY.md](docs/API_SUMMARY.md) - Complete API reference
+
+## Additional Documentation
+
+The SDK includes comprehensive guides for advanced features:
+
+- **[Liquid Templates](docs/liquid-templates.md)** - Dynamic templating for emails and notifications with personalized data
+- **[Real-Time Messaging](docs/realtime.md)** - Ably integration for live chat, presence, and real-time updates
+- **[Theme System](docs/theme.system.md)** - Dynamic theming for iframe apps with CSS variables and postMessage
+- **[Theme Defaults](docs/theme-defaults.md)** - Default theme configuration reference
+- **[Widgets](docs/widgets.md)** - React widget system for embeddable components
+- **[Internationalization](docs/i18n.md)** - Multi-language support and localization
 
 ## Requirements
 

package/{API_SUMMARY.md → dist/API_SUMMARY.md}

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.2.4  |  Generated: 2026-01-26T15:42:39.449Z
+Version: 1.3.1  |  Generated: 2026-01-30T18:16:59.130Z
 
 This is a concise summary of all available API functions and types.
 
@@ -51,6 +51,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **jobs** - Functions for jobs operations
 - **journeysAnalytics** - Functions for journeysAnalytics operations
 - **location** - Functions for location operations
+- **realtime** - Functions for realtime operations
 - **template** - Functions for template operations
 
 ## HTTP Utilities
@@ -118,6 +119,194 @@ Returns the common headers used for API requests, including apiKey and bearerTok
 **sendCustomProxyMessage**(request: string, params: any) → `Promise<T>`
 Sends a custom proxy message to the parent Smartlinks application when running in an iframe. This function is used to communicate with the parent window when the SDK is embedded in an iframe and proxyMode is enabled. It sends a message to the parent and waits for a response.
 
+## Error Handling
+
+All API functions throw `SmartlinksApiError` when requests fail. This error class provides structured access to HTTP status codes, server error codes, and additional context.
+
+### SmartlinksApiError
+
+**Properties:**
+- **message** `string` - Human-readable error message in English (e.g., "Error 400: Not Authorized")
+- **statusCode** `number` - HTTP status code (400, 401, 404, 500, etc.)
+- **code** `number` - Numeric error code (same as statusCode)
+- **details** `Record<string, any> | undefined` - Additional server response data, including string error codes
+- **url** `string | undefined` - The URL that was requested
+
+**Helper Methods:**
+- **isAuthError()** `boolean` - Returns true for 401 or 403 status codes
+- **isNotFound()** `boolean` - Returns true for 404 status code
+- **isRateLimited()** `boolean` - Returns true for 429 status code
+- **isClientError()** `boolean` - Returns true for 4xx status codes
+- **isServerError()** `boolean` - Returns true for 5xx status codes
+- **toJSON()** `object` - Returns a serializable object for logging
+
+### Error Format Normalization
+
+The SDK automatically normalizes various server error response formats into a consistent structure. The server may return errors in different formats, but they are all accessible through the same properties.
+
+**Server String Error Codes:**
+Server-specific error identifiers are preserved in `error.details`:
+- Access via: `error.details?.errorCode` or `error.details?.error`
+- Format examples: `"NOT_AUTHORIZED"`, `"broadcasts.topic.invalid"`, `"sendgrid.provision.failed"`
+- Use these for programmatic error handling (switch statements, conditional logic)
+
+### Usage Examples
+
+**Basic Error Handling:**
+```typescript
+import { SmartlinksApiError, product } from '@proveanything/smartlinks'
+
+try {
+  const item = await product.get('collectionId', 'productId')
+} catch (error) {
+  if (error instanceof SmartlinksApiError) {
+    console.error('Status:', error.statusCode)      // 404
+    console.error('Message:', error.message)        // "Error 404: Not found"
+    console.error('URL:', error.url)                // "/public/collection/..."
+  }
+}
+```
+
+**Using Helper Methods:**
+```typescript
+try {
+  await product.create('collectionId', data)
+} catch (error) {
+  if (error instanceof SmartlinksApiError) {
+    if (error.isAuthError()) {
+      // Handle 401/403 - redirect to login
+      redirectToLogin()
+    } else if (error.isNotFound()) {
+      // Handle 404
+      showNotFound()
+    } else if (error.isRateLimited()) {
+      // Handle 429 - implement retry with backoff
+      await retryAfterDelay()
+    } else if (error.isServerError()) {
+      // Handle 5xx
+      showMaintenanceMessage()
+    }
+  }
+}
+```
+
+**Accessing Server Error Codes:**
+```typescript
+try {
+  await broadcasts.send('collectionId', 'broadcastId', options)
+} catch (error) {
+  if (error instanceof SmartlinksApiError) {
+    // Extract server-defined string error code
+    const serverCode = error.details?.errorCode || error.details?.error
+    
+    switch (serverCode) {
+      case 'NOT_AUTHORIZED':
+        redirectToLogin()
+        break
+      case 'broadcasts.topic.invalid':
+        showTopicSelector()
+        break
+      case 'sendgrid.provision.failed':
+        alertAdmin('Email service error')
+        break
+      default:
+        showError(error.message)
+    }
+  }
+}
+```
+
+**Error Logging for Monitoring:**
+```typescript
+try {
+  await api.someMethod()
+} catch (error) {
+  if (error instanceof SmartlinksApiError) {
+    // Log structured error data
+    logger.error('API Error', error.toJSON())
+    
+    // Send to monitoring service
+    Sentry.captureException(error, {
+      extra: error.toJSON(),
+      tags: {
+        statusCode: error.statusCode,
+        serverErrorCode: error.details?.errorCode || error.details?.error,
+      }
+    })
+  }
+}
+```
+
+**Handling Validation Errors:**
+```typescript
+try {
+  await product.create('collectionId', formData)
+} catch (error) {
+  if (error instanceof SmartlinksApiError && error.statusCode === 400) {
+    // Access field-specific validation errors if available
+    if (error.details?.fields) {
+      Object.entries(error.details.fields).forEach(([field, message]) => {
+        showFieldError(field, String(message))
+      })
+    } else {
+      showError(error.message)
+    }
+  }
+}
+```
+
+**Retry Logic for Transient Errors:**
+```typescript
+async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await fn()
+    } catch (error) {
+      if (error instanceof SmartlinksApiError) {
+        // Only retry server errors and rate limiting
+        const shouldRetry = error.isServerError() || error.isRateLimited()
+        
+        if (!shouldRetry || attempt === maxRetries - 1) {
+          throw error
+        }
+        
+        // Exponential backoff
+        const delay = 1000 * Math.pow(2, attempt)
+        await new Promise(resolve => setTimeout(resolve, delay))
+      } else {
+        throw error
+      }
+    }
+  }
+  throw new Error('Max retries exceeded')
+}
+
+// Usage
+const collections = await withRetry(() => collection.list())
+```
+
+### Error Code Reference
+
+**HTTP Status Codes (numeric):**
+- `400` - Bad Request (invalid input)
+- `401` - Unauthorized (authentication required)
+- `403` - Forbidden (insufficient permissions)
+- `404` - Not Found (resource doesn't exist)
+- `429` - Too Many Requests (rate limited)
+- `500` - Internal Server Error
+- `502` - Bad Gateway
+- `503` - Service Unavailable
+
+**Server Error Codes (strings in `details.errorCode` or `details.error`):**
+Examples include:
+- `"NOT_AUTHORIZED"` - Not authorized for this action
+- `"broadcasts.topic.invalid"` - Invalid communication topic
+- `"broadcasts.manual.segment.missing"` - Missing required segment
+- `"sendgrid.provision.failed"` - Email service provisioning failed
+- `"validation.failed"` - Request validation failed
+
+*Note: Server error codes use either `UPPERCASE_UNDERSCORE` or `dotted.notation` format. Both are supported.*
+
 ## Types
 
 ### appConfiguration
@@ -1250,7 +1439,9 @@ interface ContactSchema {
 ```typescript
 interface ErrorResponse {
   code: number
+  errorCode?: string
   message: string
+  details?: Record<string, any>
 }
 ```
 
@@ -1830,6 +2021,31 @@ interface QrShortCodeLookupResponse {
 }
 ```
 
+### realtime
+
+**RealtimeTokenRequest** (interface)
+```typescript
+interface RealtimeTokenRequest {
+  collectionId: string
+  appId?: string
+}
+```
+
+**AblyTokenRequest** (interface)
+```typescript
+interface AblyTokenRequest {
+  keyName: string
+  ttl: number
+  timestamp: number
+  capability: string
+  nonce: string
+  mac: string
+  clientId: string
+}
+```
+
+**RealtimeChannelPattern** = `string`
+
 ### segments
 
 **SegmentRecord** (interface)
@@ -2901,6 +3117,14 @@ Get proofs for a batch (admin only). GET /admin/collection/:collectionId/product
 **lookupShortCode**(shortId: string, code: string) → `Promise<QrShortCodeLookupResponse>`
 Resolve a short code to related resource identifiers.
 
+### realtime
+
+**getPublicToken**(params: RealtimeTokenRequest) → `Promise<AblyTokenRequest>`
+Get an Ably token for public (user-scoped) real-time communication. This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client with appropriate permissions for the specified collection and optional app. Requires user authentication (Bearer token). ```ts const tokenRequest = await realtime.getPublicToken({ collectionId: 'my-collection-id', appId: 'my-app-id' }) // Use with Ably const ably = new Ably.Realtime.Promise({ authCallback: async (data, callback) => { callback(null, tokenRequest) } }) // Subscribe to channels matching the pattern const channel = ably.channels.get('collection:my-collection-id:app:my-app-id:chat:general') await channel.subscribe('message', (msg) => console.log(msg.data)) ```
+
+**getAdminToken**() → `Promise<AblyTokenRequest>`
+Get an Ably token for admin real-time communication. This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client with admin permissions to receive system notifications and alerts. Admin users get subscribe-only (read-only) access to the interaction:{userId} channel pattern. Requires admin authentication (Bearer token). ```ts const tokenRequest = await realtime.getAdminToken() // Use with Ably const ably = new Ably.Realtime.Promise({ authCallback: async (data, callback) => { callback(null, tokenRequest) } }) // Subscribe to admin interaction channel const userId = 'my-user-id' const channel = ably.channels.get(`interaction:${userId}`) await channel.subscribe((message) => { console.log('Admin notification:', message.data) }) ```
+
 ### segments
 
 **create**(collectionId: string,