gufi-cli 0.1.49 → 0.1.51

package/docs/dev-guide/2-10-tns.md

@@ -0,0 +1,177 @@
+---
+id: tns
+title: "TNS Integration"
+description: "Colombian product catalog"
+icon: Zap
+category: dev
+part: 2
+group: integrations
+---
+
+# TNS Integration
+
+Colombian accounting and product catalog
+
+## Overview
+
+TNS is a Colombian accounting system that provides product catalog information. This integration syncs products and their categories from the TNS catalog.
+
+## Setup
+
+No API credentials needed - TNS provides a public product catalog.
+
+Create these tables in your module:
+- `products` - Product information
+- `categories` - Product categories
+
+## Available Methods
+
+| Method | Description | Use Case |
+|--------|-------------|----------|
+| `sync_products` | Sync specific products | When you know product codes |
+| `sync_products_from_sales` | Sync products from sales | **Recommended** - efficient |
+| `sync_all_products` | Sync entire catalog | Large, slow - avoid if possible |
+
+:::info
+**Recommended:** Use `sync_products_from_sales` - it only syncs products that appear in your sales data, which is much faster than syncing the entire catalog.
+:::
+
+## Method: sync_products
+
+Syncs products by their codes.
+
+```javascript
+const result = await gufi.integrations.tns.sync_products({
+  productsTable: 'tns.products',
+  categoriesTable: 'tns.categories',
+  env: 'production'  // or 'sandbox'
+});
+```
+
+## Method: sync_products_from_sales
+
+Syncs only products that appear in your sales data. Best for OurVend integration.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| productsTable | Yes | Target products table |
+| categoriesTable | Yes | Target categories table |
+| salesTable | Yes | Source sales table (e.g., `ourvend.sales`) |
+| env | No | TNS environment (default: production) |
+
+```javascript
+const result = await gufi.integrations.tns.sync_products_from_sales({
+  productsTable: 'tns.products',
+  categoriesTable: 'tns.categories',
+  salesTable: 'ourvend.sales'
+});
+// Returns: { synced: 85, created: 12, productCodes: [...] }
+```
+
+## Method: sync_all_products
+
+Syncs the entire TNS product catalog. Can be slow for large catalogs.
+
+```javascript
+const result = await gufi.integrations.tns.sync_all_products({
+  productsTable: 'tns.products',
+  categoriesTable: 'tns.categories',
+  env: 'production'
+});
+// Returns: { synced: 5000, created: 200, updated: 4800 }
+```
+
+:::warning
+`sync_all_products` can be slow and may timeout for large catalogs. Use `sync_products_from_sales` for incremental syncing.
+:::
+
+## Example: Sync from OurVend Sales
+
+After syncing OurVend sales, sync TNS product info:
+
+```javascript
+async function sync_tns_from_sales(gufi) {
+  const result = await gufi.integrations.tns.sync_products_from_sales({
+    productsTable: 'tns.products',
+    categoriesTable: 'tns.categories',
+    salesTable: 'ourvend.sales'
+  });
+
+  gufi.logger.info('TNS products synced', {
+    synced: result.synced,
+    created: result.created
+  });
+
+  return result;
+}
+```
+
+## Complete OurVend + TNS Pipeline
+
+Trigger: `scheduled` with cron `0 6 * * *` (6 AM daily)
+
+```javascript
+async function daily_vending_sync(gufi) {
+  const { env } = gufi.context;
+
+  // 1. Sync OurVend data
+  await gufi.integrations.ourvend.sync_groups({
+    user: env.OURVEND_USER,
+    password: env.OURVEND_PASSWORD,
+    tableName: 'ourvend.groups'
+  });
+
+  await gufi.integrations.ourvend.sync_machines({
+    user: env.OURVEND_USER,
+    password: env.OURVEND_PASSWORD,
+    tableName: 'ourvend.machines',
+    groupsTable: 'ourvend.groups'
+  });
+
+  await gufi.integrations.ourvend.sync_products({
+    user: env.OURVEND_USER,
+    password: env.OURVEND_PASSWORD,
+    tableName: 'ourvend.products'
+  });
+
+  const yesterday = new Date(Date.now() - 86400000).toISOString().split('T')[0];
+  const today = new Date().toISOString().split('T')[0];
+
+  const sales = await gufi.integrations.ourvend.sync_sales({
+    user: env.OURVEND_USER,
+    password: env.OURVEND_PASSWORD,
+    tableName: 'ourvend.sales',
+    machinesTable: 'ourvend.machines',
+    productsTable: 'ourvend.products',
+    groupsTable: 'ourvend.groups',
+    dateFrom: yesterday,
+    dateTo: today
+  });
+
+  // 2. Sync TNS products from new sales
+  const tns = await gufi.integrations.tns.sync_products_from_sales({
+    productsTable: 'tns.products',
+    categoriesTable: 'tns.categories',
+    salesTable: 'ourvend.sales'
+  });
+
+  gufi.logger.info('Daily sync complete', {
+    sales: sales.synced,
+    tnsProducts: tns.synced
+  });
+
+  return {
+    sales: sales.synced,
+    tns_products: tns.synced
+  };
+}
+```
+
+## Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Product not found | Code doesn't exist in TNS | The product code from OurVend may not be in TNS catalog |
+| Category not created | Missing categoriesTable | Ensure `categoriesTable` parameter is correct |
+| Timeout | sync_all_products too slow | Use `sync_products_from_sales` for incremental sync |
+| Duplicate products | Re-syncing | Products are matched by code - duplicates are updated, not created |

package/docs/dev-guide/2-11-custom-http.md

@@ -0,0 +1,268 @@
+---
+id: custom-http
+title: "Custom HTTP Requests"
+description: "Connect to any REST API"
+icon: Zap
+category: dev
+part: 2
+group: integrations
+---
+
+# Custom HTTP Requests
+
+Connect to any REST API with gufi.http()
+
+## Overview
+
+For services without built-in integrations, use `gufi.http()` to make HTTP requests to any REST API.
+
+## Basic Syntax
+
+```javascript
+const response = await gufi.http({
+  url: 'https://api.example.com/endpoint',
+  method: 'POST',
+  headers: {
+    'Authorization': 'Bearer ' + env.API_KEY,
+    'Content-Type': 'application/json'
+  },
+  body: {
+    key: 'value'
+  }
+});
+```
+
+## Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| url | string | Yes | - | Full URL to call |
+| method | string | No | GET | HTTP method: GET, POST, PUT, DELETE, PATCH |
+| headers | object | No | {} | HTTP headers |
+| body | object | No | - | Request body (auto JSON stringified) |
+| timeout | number | No | 30000 | Timeout in milliseconds |
+
+## GET Request
+
+```javascript
+async function fetch_data(gufi) {
+  const { env } = gufi.context;
+
+  const response = await gufi.http({
+    url: 'https://api.example.com/users',
+    headers: {
+      'Authorization': 'Bearer ' + env.API_KEY
+    }
+  });
+
+  return { users: response.data };
+}
+```
+
+## POST Request
+
+```javascript
+async function create_record(gufi) {
+  const { env, row } = gufi.context;
+
+  const response = await gufi.http({
+    url: 'https://api.example.com/orders',
+    method: 'POST',
+    headers: {
+      'Authorization': 'Bearer ' + env.API_KEY,
+      'Content-Type': 'application/json'
+    },
+    body: {
+      customer_id: row.customer_id,
+      items: row.items,
+      total: row.total
+    }
+  });
+
+  return { external_id: response.id };
+}
+```
+
+## Webhook Notification
+
+Trigger: `on_create` - Notify external system when record created
+
+```javascript
+async function notify_webhook(gufi) {
+  const { row, env, table } = gufi.context;
+
+  await gufi.http({
+    url: env.WEBHOOK_URL,
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Webhook-Secret': env.WEBHOOK_SECRET
+    },
+    body: {
+      event: 'record.created',
+      table: table,
+      data: row,
+      timestamp: new Date().toISOString()
+    }
+  });
+
+  gufi.logger.info('Webhook sent', { table, id: row.id });
+}
+```
+
+## Slack Notification
+
+```javascript
+async function send_slack_alert(gufi) {
+  const { row, env } = gufi.context;
+
+  await gufi.http({
+    url: env.SLACK_WEBHOOK_URL,
+    method: 'POST',
+    body: {
+      text: `New order #${row.id} received!`,
+      blocks: [
+        {
+          type: 'section',
+          text: {
+            type: 'mrkdwn',
+            text: `*New Order*\nOrder: #${row.id}\nCustomer: ${row.customer_name}\nTotal: €${row.total}`
+          }
+        }
+      ]
+    }
+  });
+}
+```
+
+## Error Handling
+
+Always wrap HTTP calls in try/catch:
+
+```javascript
+async function safe_api_call(gufi) {
+  const { env, row } = gufi.context;
+
+  try {
+    const response = await gufi.http({
+      url: 'https://api.example.com/process',
+      method: 'POST',
+      headers: { 'Authorization': 'Bearer ' + env.API_KEY },
+      body: { id: row.id }
+    });
+
+    return { success: true, data: response };
+
+  } catch (error) {
+    gufi.logger.error('API call failed', {
+      error: error.message,
+      rowId: row.id
+    });
+
+    return { success: false, error: error.message };
+  }
+}
+```
+
+## Retry Logic
+
+For unreliable APIs, implement retry:
+
+```javascript
+async function api_with_retry(gufi) {
+  const { env } = gufi.context;
+  const maxRetries = 3;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await gufi.http({
+        url: 'https://api.example.com/data',
+        headers: { 'Authorization': 'Bearer ' + env.API_KEY }
+      });
+      return response;
+
+    } catch (error) {
+      gufi.logger.warn(`Attempt ${attempt} failed`, { error: error.message });
+
+      if (attempt === maxRetries) {
+        throw error;  // Final attempt failed
+      }
+
+      // Wait before retry (exponential backoff)
+      await new Promise(r => setTimeout(r, 1000 * attempt));
+    }
+  }
+}
+```
+
+## Pagination
+
+For APIs with paginated results:
+
+```javascript
+async function fetch_all_pages(gufi) {
+  const { env } = gufi.context;
+  const allData = [];
+  let page = 1;
+  let hasMore = true;
+
+  while (hasMore) {
+    const response = await gufi.http({
+      url: `https://api.example.com/items?page=${page}&limit=100`,
+      headers: { 'Authorization': 'Bearer ' + env.API_KEY }
+    });
+
+    allData.push(...response.items);
+    hasMore = response.has_more;
+    page++;
+
+    // Safety limit
+    if (page > 100) break;
+  }
+
+  return { total: allData.length, data: allData };
+}
+```
+
+## OAuth Token Refresh
+
+```javascript
+async function call_with_oauth(gufi) {
+  const { env } = gufi.context;
+
+  // First, refresh the token
+  const tokenResponse = await gufi.http({
+    url: 'https://oauth.example.com/token',
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: {
+      grant_type: 'refresh_token',
+      refresh_token: env.OAUTH_REFRESH_TOKEN,
+      client_id: env.OAUTH_CLIENT_ID,
+      client_secret: env.OAUTH_CLIENT_SECRET
+    }
+  });
+
+  // Then use the new token
+  const response = await gufi.http({
+    url: 'https://api.example.com/data',
+    headers: {
+      'Authorization': 'Bearer ' + tokenResponse.access_token
+    }
+  });
+
+  return response;
+}
+```
+
+## Best Practices
+
+1. **Store credentials in env** - Never hardcode API keys
+2. **Handle errors** - Always use try/catch
+3. **Log important events** - Use logger for debugging
+4. **Set timeouts** - Don't wait forever for slow APIs
+5. **Validate responses** - Check response structure before using
+
+:::warning
+Never log sensitive data like API keys or passwords. Only log non-sensitive identifiers.
+:::