@proveanything/smartlinks 1.2.4 → 1.3.2

package/dist/http.js

@@ -2,6 +2,18 @@
 // This module replaces the ApiClient constructor. It keeps baseURL, apiKey, bearerToken
 // in module-scope variables, and provides a shared `request<T>(path)` helper that will
 // be used by all namespaced files (collection.ts, product.ts, etc.).
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { SmartlinksApiError } from "./types/error";
 let baseURL = null;
 let apiKey = undefined;
 let bearerToken = undefined;
@@ -63,6 +75,88 @@ function safeBodyPreview(body) {
     }
     return body;
 }
+/**
+ * Normalizes various server error response formats into a consistent ErrorResponse shape.
+ * Handles multiple formats:
+ * - { code: number, message: string } (standard)
+ * - { errorCode: string, errorText: string }
+ * - { error: string, message: string }
+ * - { error: string } (just error field)
+ * - { ok: false, error: string }
+ * - Plain string
+ *
+ * @param responseBody - The parsed JSON response body from the server
+ * @param statusCode - HTTP status code
+ * @returns Normalized ErrorResponse object
+ */
+function normalizeErrorResponse(responseBody, statusCode) {
+    if (!responseBody || typeof responseBody !== 'object') {
+        // Plain string or non-object response
+        const message = typeof responseBody === 'string' ? responseBody : 'Request failed';
+        return {
+            code: statusCode,
+            message,
+        };
+    }
+    // Extract all possible fields from the response
+    const { code, errorCode, error, message, errorText, ok } = responseBody, rest = __rest(responseBody
+    // Determine the error code (prefer numeric code, fall back to errorCode or error string)
+    , ["code", "errorCode", "error", "message", "errorText", "ok"]);
+    // Determine the error code (prefer numeric code, fall back to errorCode or error string)
+    let normalizedCode = statusCode;
+    if (typeof code === 'number') {
+        normalizedCode = code;
+    }
+    else if (typeof errorCode === 'string' || typeof error === 'string') {
+        // Keep statusCode as numeric code, but preserve the string code in details
+    }
+    // Determine the error message
+    let normalizedMessage;
+    if (message) {
+        normalizedMessage = String(message);
+    }
+    else if (errorText) {
+        normalizedMessage = String(errorText);
+    }
+    else if (error) {
+        normalizedMessage = String(error);
+    }
+    else if (ok === false) {
+        normalizedMessage = 'Request failed';
+    }
+    else {
+        normalizedMessage = `Request failed with status ${statusCode}`;
+    }
+    // Extract the server-specific error code string (distinct from HTTP status code)
+    let normalizedErrorCode;
+    if (errorCode && typeof errorCode === 'string') {
+        normalizedErrorCode = errorCode;
+    }
+    else if (error && typeof error === 'string') {
+        normalizedErrorCode = error;
+    }
+    // Collect any additional details
+    const details = Object.assign({}, rest);
+    // Preserve error fields in details for backward compatibility
+    if (errorCode && typeof errorCode === 'string') {
+        details.errorCode = errorCode;
+    }
+    if (error && typeof error === 'string') {
+        details.error = error;
+    }
+    if (errorText && errorText !== normalizedMessage) {
+        details.errorText = errorText;
+    }
+    if (ok === false) {
+        details.ok = ok;
+    }
+    return {
+        code: normalizedCode,
+        errorCode: normalizedErrorCode,
+        message: normalizedMessage,
+        details: Object.keys(details).length > 0 ? details : undefined,
+    };
+}
 /**
  * Call this once (e.g. at app startup) to configure baseURL/auth.
  *
@@ -336,14 +430,18 @@ export async function request(path) {
     });
     logDebug('[smartlinks] GET response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
-        // Try to parse ErrorResponse; if that fails, throw generic
+        // Try to parse error response body and normalize it
+        let responseBody;
         try {
-            const errBody = (await response.json());
-            throw new Error(`Error ${errBody.code}: ${errBody.message}`);
+            responseBody = await response.json();
         }
         catch (_a) {
-            throw new Error(`Request to ${url} failed with status ${response.status}`);
+            // Failed to parse JSON, use status code only
+            responseBody = null;
         }
+        const errBody = normalizeErrorResponse(responseBody, response.status);
+        const message = `Error ${errBody.code}: ${errBody.message}`;
+        throw new SmartlinksApiError(message, response.status, errBody, url);
     }
     return (await response.json());
 }
@@ -384,13 +482,16 @@ export async function post(path, body, extraHeaders) {
     });
     logDebug('[smartlinks] POST response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
+        let responseBody;
         try {
-            const errBody = (await response.json());
-            throw new Error(`Error ${errBody.code}: ${errBody.message}`);
+            responseBody = await response.json();
         }
         catch (_a) {
-            throw new Error(`Request to ${url} failed with status ${response.status}`);
+            responseBody = null;
         }
+        const errBody = normalizeErrorResponse(responseBody, response.status);
+        const message = `Error ${errBody.code}: ${errBody.message}`;
+        throw new SmartlinksApiError(message, response.status, errBody, url);
     }
     return (await response.json());
 }
@@ -431,13 +532,16 @@ export async function put(path, body, extraHeaders) {
     });
     logDebug('[smartlinks] PUT response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
+        let responseBody;
         try {
-            const errBody = (await response.json());
-            throw new Error(`Error ${errBody.code}: ${errBody.message}`);
+            responseBody = await response.json();
         }
         catch (_a) {
-            throw new Error(`Request to ${url} failed with status ${response.status}`);
+            responseBody = null;
         }
+        const errBody = normalizeErrorResponse(responseBody, response.status);
+        const message = `Error ${errBody.code}: ${errBody.message}`;
+        throw new SmartlinksApiError(message, response.status, errBody, url);
     }
     return (await response.json());
 }
@@ -478,13 +582,16 @@ export async function patch(path, body, extraHeaders) {
     });
     logDebug('[smartlinks] PATCH response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
+        let responseBody;
         try {
-            const errBody = (await response.json());
-            throw new Error(`Error ${errBody.code}: ${errBody.message}`);
+            responseBody = await response.json();
         }
         catch (_a) {
-            throw new Error(`Request to ${url} failed with status ${response.status}`);
+            responseBody = null;
         }
+        const errBody = normalizeErrorResponse(responseBody, response.status);
+        const message = `Error ${errBody.code}: ${errBody.message}`;
+        throw new SmartlinksApiError(message, response.status, errBody, url);
     }
     return (await response.json());
 }
@@ -528,13 +635,16 @@ export async function requestWithOptions(path, options) {
     const response = await fetch(url, Object.assign(Object.assign({}, options), { headers }));
     logDebug('[smartlinks] requestWithOptions response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
+        let responseBody;
         try {
-            const errBody = (await response.json());
-            throw new Error(`Error ${errBody.code}: ${errBody.message}`);
+            responseBody = await response.json();
         }
         catch (_a) {
-            throw new Error(`Request to ${url} failed with status ${response.status}`);
+            responseBody = null;
         }
+        const errBody = normalizeErrorResponse(responseBody, response.status);
+        const message = `Error ${errBody.code}: ${errBody.message}`;
+        throw new SmartlinksApiError(message, response.status, errBody, url);
     }
     return (await response.json());
 }
@@ -569,13 +679,16 @@ export async function del(path, extraHeaders) {
     });
     logDebug('[smartlinks] DELETE response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
+        let responseBody;
         try {
-            const errBody = (await response.json());
-            throw new Error(`Error ${errBody.code}: ${errBody.message}`);
+            responseBody = await response.json();
         }
         catch (_a) {
-            throw new Error(`Request to ${url} failed with status ${response.status}`);
+            responseBody = null;
         }
+        const errBody = normalizeErrorResponse(responseBody, response.status);
+        const message = `Error ${errBody.code}: ${errBody.message}`;
+        throw new SmartlinksApiError(message, response.status, errBody, url);
     }
     // If the response is empty, just return undefined
     if (response.status === 204)

package/dist/i18n.md

@@ -0,0 +1,287 @@
+# Internationalization (i18n) System
+
+This document explains the i18n system for SmartLinks apps, covering URL-based language selection, static translations, and dynamic overrides.
+
+---
+
+## Overview
+
+The i18n system supports:
+
+- **URL parameter language selection** (`?lang=de`) - Ideal for iframe embedding
+- **Static translations** in JSON files - Fast, no API calls
+- **Dynamic overrides** via SmartLinks appConfig - Customer-configurable
+- **Type-safe translation keys** - Compile-time safety
+- **Widget support** - Translations can be passed to embedded widgets
+
+---
+
+## Quick Start
+
+### Using Translations in Components
+
+```typescript
+import { useLanguage } from '@/i18n';
+
+export const MyComponent = () => {
+  const { t, lang } = useLanguage();
+  
+  return (
+    <div>
+      <h1>{t('public.title')}</h1>
+      <p>{t('public.description')}</p>
+      <small>Language: {lang}</small>
+    </div>
+  );
+};
+```
+
+### With Parameter Interpolation
+
+```typescript
+const { t } = useLanguage();
+
+// Translation: "Hello, {{name}}!"
+t('greeting', { name: 'John' }); // "Hello, John!"
+```
+
+---
+
+## Language Detection Priority
+
+The system detects language from multiple sources (in order):
+
+| Priority | Source | Example |
+|----------|--------|---------|
+| 1 | URL parameter | `?lang=de` |
+| 2 | localStorage | `smartlinks-lang` key |
+| 3 | Browser language | `navigator.language` |
+| 4 | Default | `en` |
+
+For iframe apps, the SmartLinks platform passes the language via URL parameter.
+
+---
+
+## File Structure
+
+```text
+src/i18n/
+├── index.ts              # Main exports
+├── LanguageContext.tsx   # React context + provider
+├── types.ts              # TypeScript types
+└── locales/
+    ├── en.json           # English translations
+    ├── de.json           # German translations
+    └── fr.json           # French translations
+```
+
+---
+
+## Adding New Translations
+
+### 1. Add the Key to Types
+
+```typescript
+// src/i18n/types.ts
+export type TranslationKey =
+  | 'common.loading'
+  | 'common.error'
+  | 'myFeature.title'      // Add new key
+  | 'myFeature.description';
+```
+
+### 2. Add Translations to All Locales
+
+```json
+// src/i18n/locales/en.json
+{
+  "myFeature.title": "My Feature",
+  "myFeature.description": "Description of my feature"
+}
+
+// src/i18n/locales/de.json
+{
+  "myFeature.title": "Meine Funktion",
+  "myFeature.description": "Beschreibung meiner Funktion"
+}
+```
+
+### 3. Use in Components
+
+```typescript
+const { t } = useLanguage();
+return <h1>{t('myFeature.title')}</h1>;
+```
+
+---
+
+## Adding New Languages
+
+### 1. Create the Locale File
+
+```json
+// src/i18n/locales/es.json
+{
+  "common.loading": "Cargando...",
+  "common.error": "Algo salió mal",
+  // ... all other keys
+}
+```
+
+### 2. Import in LanguageContext
+
+```typescript
+// src/i18n/LanguageContext.tsx
+import es from './locales/es.json';
+
+const staticTranslations: Record<string, PartialTranslations> = {
+  en: en as PartialTranslations,
+  de: de as PartialTranslations,
+  fr: fr as PartialTranslations,
+  es: es as PartialTranslations,  // Add new language
+};
+
+const SUPPORTED_LANGUAGES = ['en', 'de', 'fr', 'es'];  // Add to list
+```
+
+---
+
+## Dynamic Translations (SmartLinks appConfig)
+
+For customer-configurable translations, store them in SmartLinks appConfig:
+
+### Config Structure
+
+```json
+{
+  "i18n": {
+    "supportedLanguages": ["en", "de"],
+    "defaultLanguage": "en",
+    "translations": {
+      "en": {
+        "public.title": "Custom Brand Title",
+        "public.description": "Custom brand description"
+      },
+      "de": {
+        "public.title": "Benutzerdefinierter Markentitel",
+        "public.description": "Benutzerdefinierte Markenbeschreibung"
+      }
+    }
+  }
+}
+```
+
+### Loading Dynamic Translations
+
+```typescript
+import { useCollectionAppConfig } from '@/hooks/useSmartLinksData';
+import { LanguageProvider } from '@/i18n';
+
+const App = () => {
+  const { data: config } = useCollectionAppConfig(collectionId, appId);
+  
+  return (
+    <LanguageProvider dynamicTranslations={config?.i18n?.translations}>
+      <MyApp />
+    </LanguageProvider>
+  );
+};
+```
+
+Dynamic translations override static ones, so customers can customize specific strings while inheriting defaults.
+
+---
+
+## Widgets
+
+Widgets receive language context via props rather than React context (since they may run outside the provider).
+
+### Widget Props
+
+```typescript
+interface SmartLinksWidgetProps {
+  // ... other props
+  lang?: string;
+  translations?: Record<string, string>;
+}
+```
+
+### Using in Widgets
+
+```typescript
+import { createTranslator } from '@/i18n';
+
+export const MyWidget: React.FC<SmartLinksWidgetProps> = ({
+  lang = 'en',
+  translations = {},
+  ...props
+}) => {
+  const t = createTranslator(lang, translations);
+  
+  return <div>{t('widget.title')}</div>;
+};
+```
+
+The `createTranslator` function creates a standalone translation function that doesn't require React context.
+
+---
+
+## URL Examples
+
+```
+# English (default)
+/#/?collectionId=abc&appId=pamphlet
+
+# German
+/#/?collectionId=abc&appId=pamphlet&lang=de
+
+# French
+/#/?collectionId=abc&appId=pamphlet&lang=fr
+```
+
+---
+
+## Best Practices
+
+1. **Use dot notation** for key namespacing: `category.subcategory.key`
+2. **Keep translations flat** - avoid nested objects in locale files
+3. **Add keys to types.ts first** - ensures type safety
+4. **Provide fallbacks** - English is always the fallback language
+5. **Test all languages** - Use `?lang=xx` to switch during development
+
+---
+
+## API Reference
+
+### `useLanguage()`
+
+Hook to access language context.
+
+```typescript
+const { 
+  lang,               // Current language code
+  setLang,            // Function to change language
+  t,                  // Translation function
+  supportedLanguages  // Array of supported language codes
+} = useLanguage();
+```
+
+### `createTranslator(lang, overrides)`
+
+Creates a standalone translation function for widgets.
+
+```typescript
+const t = createTranslator('de', { 'custom.key': 'Custom value' });
+t('common.loading'); // "Laden..."
+t('custom.key');     // "Custom value"
+```
+
+### `LanguageProvider`
+
+React provider component.
+
+```typescript
+<LanguageProvider dynamicTranslations={optionalOverrides}>
+  <App />
+</LanguageProvider>
+```