@proveanything/smartlinks 1.2.4 → 1.3.1

package/dist/api/realtime.d.ts

@@ -0,0 +1,103 @@
+import type { AblyTokenRequest, RealtimeTokenRequest } from "../types/realtime";
+/**
+ * Real-Time Communications API
+ *
+ * Provides access to real-time communication channels using Ably.
+ * Supports both public (user-scoped) and admin tokens for different permission levels.
+ *
+ * Channel Patterns:
+ * - With appId: collection:{collectionId}:app:{appId}:*
+ * - Without appId: collection:{collectionId}:*
+ *
+ * @example
+ * ```ts
+ * import { realtime } from '@proveanything/smartlinks'
+ *
+ * // Get token for public user
+ * const tokenRequest = await realtime.getPublicToken({
+ *   collectionId: 'abc123',
+ *   appId: 'xyz789'
+ * })
+ *
+ * // Initialize Ably client
+ * const ably = new Ably.Realtime.Promise({
+ *   authCallback: async (data, callback) => {
+ *     callback(null, tokenRequest)
+ *   }
+ * })
+ *
+ * // Subscribe to a channel
+ * const channel = ably.channels.get('collection:abc123:app:xyz789:chat:room-1')
+ * await channel.subscribe((message) => {
+ *   console.log('Received:', message.data)
+ * })
+ *
+ * // Publish a message
+ * await channel.publish('message', { text: 'Hello!', userId: '123' })
+ * ```
+ */
+/**
+ * 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).
+ *
+ * @param params - Token request parameters
+ * @param params.collectionId - The collection scope (required)
+ * @param params.appId - Optional app scope for more specific permissions
+ * @returns Ably TokenRequest that can be used with Ably.Realtime client
+ *
+ * @example
+ * ```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))
+ * ```
+ */
+export declare function getPublicToken(params: RealtimeTokenRequest): 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).
+ *
+ * @returns Ably TokenRequest that can be used with Ably.Realtime client
+ *
+ * @example
+ * ```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)
+ * })
+ * ```
+ */
+export declare function getAdminToken(): Promise<AblyTokenRequest>;

package/dist/api/realtime.js

@@ -0,0 +1,113 @@
+// src/api/realtime.ts
+import { request } from "../http";
+/**
+ * Real-Time Communications API
+ *
+ * Provides access to real-time communication channels using Ably.
+ * Supports both public (user-scoped) and admin tokens for different permission levels.
+ *
+ * Channel Patterns:
+ * - With appId: collection:{collectionId}:app:{appId}:*
+ * - Without appId: collection:{collectionId}:*
+ *
+ * @example
+ * ```ts
+ * import { realtime } from '@proveanything/smartlinks'
+ *
+ * // Get token for public user
+ * const tokenRequest = await realtime.getPublicToken({
+ *   collectionId: 'abc123',
+ *   appId: 'xyz789'
+ * })
+ *
+ * // Initialize Ably client
+ * const ably = new Ably.Realtime.Promise({
+ *   authCallback: async (data, callback) => {
+ *     callback(null, tokenRequest)
+ *   }
+ * })
+ *
+ * // Subscribe to a channel
+ * const channel = ably.channels.get('collection:abc123:app:xyz789:chat:room-1')
+ * await channel.subscribe((message) => {
+ *   console.log('Received:', message.data)
+ * })
+ *
+ * // Publish a message
+ * await channel.publish('message', { text: 'Hello!', userId: '123' })
+ * ```
+ */
+/**
+ * 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).
+ *
+ * @param params - Token request parameters
+ * @param params.collectionId - The collection scope (required)
+ * @param params.appId - Optional app scope for more specific permissions
+ * @returns Ably TokenRequest that can be used with Ably.Realtime client
+ *
+ * @example
+ * ```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))
+ * ```
+ */
+export async function getPublicToken(params) {
+    const queryParams = new URLSearchParams();
+    queryParams.append('collectionId', params.collectionId);
+    if (params.appId) {
+        queryParams.append('appId', params.appId);
+    }
+    return request(`/api/public/push/token?${queryParams.toString()}`);
+}
+/**
+ * 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).
+ *
+ * @returns Ably TokenRequest that can be used with Ably.Realtime client
+ *
+ * @example
+ * ```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)
+ * })
+ * ```
+ */
+export async function getAdminToken() {
+    return request('/api/admin/auth/push');
+}

package/{API_SUMMARY.md → dist/docs/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:12:23.404Z
 
 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,