gufi-cli 0.1.50 → 0.1.52

package/docs/dev-guide/2-07-stripe.md

@@ -0,0 +1,173 @@
+---
+id: stripe
+title: "Stripe Integration"
+description: "Payment processing with Stripe"
+icon: Zap
+category: dev
+part: 2
+group: integrations
+---
+
+# Stripe Integration
+
+Payment processing with Stripe
+
+## Overview
+
+Stripe is a payment processing platform. Gufi's integration lets you create Checkout Sessions that redirect customers to Stripe's hosted payment page.
+
+## Setup
+
+1. Create account at [stripe.com](https://stripe.com)
+2. Go to Dashboard → Developers → API keys
+3. Copy your **Secret Key** (starts with `sk_test_` or `sk_live_`)
+4. In Gufi: Settings → Environment Variables → Add `STRIPE_SECRET_KEY`
+
+:::warning
+Use test keys (`sk_test_`) during development. Never commit secret keys to code.
+:::
+
+## Available Methods
+
+| Method | Description |
+|--------|-------------|
+| `createCheckoutSession` | Create a Stripe Checkout Session for payment |
+
+## Method: createCheckoutSession
+
+Creates a Stripe Checkout Session URL that customers can use to pay.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| secretKey | string | Yes | Your Stripe secret key from `env` |
+| lineItems | array | Yes | Products: `[{ name, amount, quantity }]` |
+| customerEmail | string | No | Pre-fill customer email |
+| successUrl | string | No | Redirect after successful payment |
+| cancelUrl | string | No | Redirect if customer cancels |
+| metadata | object | No | Custom key-value data to attach |
+| shippingCountries | array | No | Allowed shipping countries (ISO codes) |
+| locale | string | No | Checkout language (default: es) |
+
+## Returns
+
+```javascript
+{
+  url: "https://checkout.stripe.com/...",  // Redirect customer here
+  sessionId: "cs_test_..."                  // Stripe session ID
+}
+```
+
+## Basic Example
+
+```javascript
+async function create_payment(gufi) {
+  const { row, env } = gufi.context;
+
+  const { url, sessionId } = await gufi.integrations.stripe.createCheckoutSession({
+    secretKey: env.STRIPE_SECRET_KEY,
+    lineItems: [
+      { name: 'Product Name', amount: 1999, quantity: 1 }  // €19.99
+    ],
+    successUrl: 'https://mysite.com/success',
+    cancelUrl: 'https://mysite.com/cart'
+  });
+
+  return { checkout_url: url };
+}
+```
+
+## E-commerce Order Example
+
+Trigger: `on_create` for orders entity
+
+```javascript
+async function process_new_order(gufi) {
+  const { row, env } = gufi.context;
+
+  // Build line items from order
+  const lineItems = [
+    {
+      name: row.product_name,
+      amount: Math.round(row.subtotal * 100),  // Convert to cents
+      quantity: row.quantity
+    }
+  ];
+
+  // Add shipping if present
+  if (row.shipping_cost > 0) {
+    lineItems.push({
+      name: 'Shipping',
+      amount: Math.round(row.shipping_cost * 100),
+      quantity: 1
+    });
+  }
+
+  const { url, sessionId } = await gufi.integrations.stripe.createCheckoutSession({
+    secretKey: env.STRIPE_SECRET_KEY,
+    lineItems,
+    customerEmail: row.customer_email,
+    successUrl: `https://mystore.com/order/${row.id}/success`,
+    cancelUrl: `https://mystore.com/order/${row.id}`,
+    metadata: {
+      order_id: String(row.id),
+      customer_id: String(row.customer_id)
+    }
+  });
+
+  // Save checkout URL to order
+  await gufi.query(
+    `UPDATE orders SET checkout_url = $1, stripe_session = $2, status = 'pending_payment' WHERE id = $3`,
+    [url, sessionId, row.id]
+  );
+
+  gufi.logger.info('Checkout created', { orderId: row.id, sessionId });
+
+  return { checkout_url: url };
+}
+```
+
+## On-Click Payment Button
+
+Trigger: `on_click` - User clicks "Generate Payment Link"
+
+```javascript
+async function generate_payment_link(gufi) {
+  const { row, env, input } = gufi.context;
+
+  const { url } = await gufi.integrations.stripe.createCheckoutSession({
+    secretKey: env.STRIPE_SECRET_KEY,
+    lineItems: [{
+      name: input.description || `Invoice #${row.id}`,
+      amount: Math.round(row.amount * 100),
+      quantity: 1
+    }],
+    customerEmail: row.email,
+    successUrl: 'https://mysite.com/payment-success',
+    metadata: { invoice_id: String(row.id) }
+  });
+
+  // Could also save to record or send by email
+  return {
+    message: 'Payment link generated',
+    payment_url: url
+  };
+}
+```
+
+## Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Invalid API Key | Wrong key format | Check `STRIPE_SECRET_KEY` starts with `sk_test_` or `sk_live_` |
+| Amount must be at least 50 | Amount too small | Amounts are in cents. €19.99 = 1999 |
+| No such customer | Invalid email | `customerEmail` is optional - remove it or use valid email |
+| Invalid currency | Missing currency | Default is EUR. For other currencies, check Stripe docs |
+
+## Tips
+
+- **Test mode**: Use `sk_test_` keys during development
+- **Amounts in cents**: Always multiply by 100 (€19.99 → 1999)
+- **Metadata**: Store your internal IDs for webhook reconciliation
+- **Success URL**: Include `{CHECKOUT_SESSION_ID}` to get session ID back

package/docs/dev-guide/2-08-nayax.md

@@ -0,0 +1,297 @@
+---
+id: nayax
+title: "Nayax Integration"
+description: "Vending machine telemetry"
+icon: Zap
+category: dev
+part: 2
+group: integrations
+---
+
+# Nayax Integration
+
+Vending machine telemetry and sales sync
+
+## Overview
+
+Nayax provides telemetry for vending machines. This integration syncs:
+
+- Machines and their status
+- Products and pricing
+- Sales transactions
+- Alerts and notifications
+- Machine inventory (planograms)
+- Pick lists (low stock items)
+
+## Setup
+
+1. Get your API token from Nayax Management Suite
+2. In Gufi: Settings → Environment Variables → Add `NAYAX_TOKEN`
+3. Create required tables in your module:
+   - `machines` - Machine inventory
+   - `products` - Product catalog
+   - `sales` - Sales transactions
+   - `alerts` - Machine alerts
+   - `machine_products` - Planograms (what's in each machine)
+
+## Available Methods
+
+| Method | Description | Direction |
+|--------|-------------|-----------|
+| `sync_machines` | Sync all machines from Nayax | GET ← Nayax |
+| `sync_products` | Sync product catalog | GET ← Nayax |
+| `sync_machine_products` | Sync planograms (products in machines) | GET ← Nayax |
+| `sync_last_sales` | Sync recent sales transactions | GET ← Nayax |
+| `sync_alerts` | Sync machine alerts | GET ← Nayax |
+| `sync_single_machine_capacity` | Update capacity for one machine | GET ← Nayax |
+| `update_pick_list` | Send pick list to Nayax (quantities to restock) | PUT → Nayax |
+
+## Sync Order
+
+:::warning
+Always sync in this order to maintain foreign key relationships:
+1. `sync_machines` (first - no dependencies)
+2. `sync_products` (second - no dependencies)
+3. `sync_machine_products` (needs machines + products)
+4. `sync_last_sales` (needs machines + products)
+5. `sync_alerts` (needs machines + products)
+:::
+
+## Method: sync_machines
+
+Syncs all machines from your Nayax account.
+
+```javascript
+const result = await gufi.integrations.nayax.sync_machines({
+  token: env.NAYAX_TOKEN,
+  tableName: 'nayax.machines'
+});
+// Returns: { synced: 45, created: 3, updated: 42 }
+```
+
+## Method: sync_products
+
+Syncs your product catalog.
+
+```javascript
+const result = await gufi.integrations.nayax.sync_products({
+  token: env.NAYAX_TOKEN,
+  tableName: 'nayax.products',
+  operatorActorId: 12345  // Optional: your Nayax operator ID
+});
+```
+
+## Method: sync_machine_products
+
+Syncs planograms - which products are in which machines.
+
+```javascript
+const result = await gufi.integrations.nayax.sync_machine_products({
+  token: env.NAYAX_TOKEN,
+  tableName: 'nayax.machine_products',
+  machinesTable: 'nayax.machines',
+  productsTable: 'nayax.products'
+});
+```
+
+## Method: sync_last_sales
+
+Syncs recent sales transactions.
+
+```javascript
+const result = await gufi.integrations.nayax.sync_last_sales({
+  token: env.NAYAX_TOKEN,
+  tableName: 'nayax.sales',
+  machinesTable: 'nayax.machines',
+  productsTable: 'nayax.products'
+});
+// Returns: { synced: 150, created: 150 }
+```
+
+## Method: sync_alerts
+
+Syncs machine alerts and notifications.
+
+```javascript
+const result = await gufi.integrations.nayax.sync_alerts({
+  token: env.NAYAX_TOKEN,
+  tableName: 'nayax.alerts',
+  machinesTable: 'nayax.machines',
+  productsTable: 'nayax.products'
+});
+```
+
+## Method: sync_single_machine_capacity
+
+Updates inventory for a specific machine. Use after replenishment.
+
+```javascript
+const result = await gufi.integrations.nayax.sync_single_machine_capacity({
+  machineId: 123,  // Gufi machine ID
+  token: env.NAYAX_TOKEN,
+  machineProductsTable: 'nayax.machine_products',
+  machinesTable: 'nayax.machines',
+  productsTable: 'nayax.products'
+});
+// Returns: { capacity: 85, synced: true }
+```
+
+## Method: update_pick_list
+
+Sends pick list to Nayax - uploads quantities to restock for a machine.
+
+**Flow:**
+1. `sync_machine_products` - Get inventory from Nayax (current stock + capacity)
+2. Gufi calculates - `pick_qty = par - on_hand_stock`
+3. `update_pick_list` - Send calculated quantities to Nayax
+
+```javascript
+const result = await gufi.integrations.nayax.update_pick_list({
+  token: env.NAYAX_TOKEN,
+  machineId: 123,  // Gufi machine ID (resolved to nayax_machine_id internally)
+  machinesTable: 'nayax.machines',
+  machineProductsTable: 'nayax.machine_products',
+  products: [
+    { product_id: 45, pick_qty: 10 },
+    { product_id: 67, pick_qty: 5 },
+  ],
+});
+// Returns: { success: true, machineId: 123, nayaxMachineId: 98765, productsUpdated: 2 }
+```
+
+### Generate Pick List Automation Example
+
+```javascript
+async function generate_pick_list(gufi) {
+  const { row, env } = gufi.context;
+
+  // Get products with low stock for this machine
+  const products = await gufi.query(`
+    SELECT product_id, par, on_hand_stock, (par - on_hand_stock) as pick_qty
+    FROM nayax.machine_products
+    WHERE machine_id = $1 AND on_hand_stock < par
+  `, [row.machine_id]);
+
+  if (products.length === 0) {
+    gufi.logger.info('No products need restocking');
+    return { skipped: true };
+  }
+
+  // Send to Nayax
+  const result = await gufi.integrations.nayax.update_pick_list({
+    token: env.NAYAX_TOKEN,
+    machineId: row.machine_id,
+    machinesTable: 'nayax.machines',
+    machineProductsTable: 'nayax.machine_products',
+    products: products.map(p => ({
+      product_id: p.product_id,
+      pick_qty: p.pick_qty
+    })),
+  });
+
+  gufi.logger.info('Pick list sent to Nayax', result);
+  return result;
+}
+```
+
+## Complete Daily Sync Example
+
+Trigger: `scheduled` with cron `0 6 * * *` (6 AM daily)
+
+```javascript
+async function nayax_daily_sync(gufi) {
+  const { env } = gufi.context;
+
+  gufi.logger.info('Starting Nayax daily sync');
+
+  // 1. Sync machines first
+  const machines = await gufi.integrations.nayax.sync_machines({
+    token: env.NAYAX_TOKEN,
+    tableName: 'nayax.machines'
+  });
+  gufi.logger.info('Machines synced', machines);
+
+  // 2. Sync products
+  const products = await gufi.integrations.nayax.sync_products({
+    token: env.NAYAX_TOKEN,
+    tableName: 'nayax.products'
+  });
+  gufi.logger.info('Products synced', products);
+
+  // 3. Sync planograms
+  const planograms = await gufi.integrations.nayax.sync_machine_products({
+    token: env.NAYAX_TOKEN,
+    tableName: 'nayax.machine_products',
+    machinesTable: 'nayax.machines',
+    productsTable: 'nayax.products'
+  });
+  gufi.logger.info('Planograms synced', planograms);
+
+  // 4. Sync sales
+  const sales = await gufi.integrations.nayax.sync_last_sales({
+    token: env.NAYAX_TOKEN,
+    tableName: 'nayax.sales',
+    machinesTable: 'nayax.machines',
+    productsTable: 'nayax.products'
+  });
+  gufi.logger.info('Sales synced', sales);
+
+  // 5. Sync alerts
+  const alerts = await gufi.integrations.nayax.sync_alerts({
+    token: env.NAYAX_TOKEN,
+    tableName: 'nayax.alerts',
+    machinesTable: 'nayax.machines',
+    productsTable: 'nayax.products'
+  });
+  gufi.logger.info('Alerts synced', alerts);
+
+  return {
+    machines: machines.synced,
+    products: products.synced,
+    sales: sales.synced,
+    alerts: alerts.synced
+  };
+}
+```
+
+## Sync After Replenishment
+
+Trigger: `on_update` for replenishments entity (when status = 'completed')
+
+```javascript
+async function update_capacity_after_replenishment(gufi) {
+  const { row, env, changes } = gufi.context;
+
+  // Only run when status changes to completed
+  if (changes.status !== 'completed') {
+    return { skipped: true };
+  }
+
+  const result = await gufi.integrations.nayax.sync_single_machine_capacity({
+    machineId: row.machine_id,
+    token: env.NAYAX_TOKEN,
+    machineProductsTable: 'nayax.machine_products',
+    machinesTable: 'nayax.machines',
+    productsTable: 'nayax.products'
+  });
+
+  gufi.logger.info('Machine capacity updated', {
+    machineId: row.machine_id,
+    capacity: result.capacity
+  });
+
+  return { capacity: result.capacity };
+}
+```
+
+## Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| 401 Unauthorized | Token expired | Get new token from Nayax Management Suite |
+| Machine not found | Missing FK | Run `sync_machines` first |
+| Product not found | Missing FK | Run `sync_products` first |
+| FK constraint violation | Wrong sync order | Follow sync order: machines → products → rest |
+| Timeout | Large sync | Consider syncing in smaller batches |
+| MachineProductId not found | Product not in machine | Check `machine_products` has the product for that machine |
+| update_pick_list: No products to update | Empty products array | Ensure products array is not empty |

package/docs/dev-guide/2-09-ourvend.md

@@ -0,0 +1,226 @@
+---
+id: ourvend
+title: "OurVend Integration"
+description: "RedPanda vending system"
+icon: Zap
+category: dev
+part: 2
+group: integrations
+---
+
+# OurVend Integration
+
+RedPanda vending machine system
+
+## Overview
+
+OurVend (RedPanda) is a vending machine management platform. This integration syncs:
+
+- Machine groups (locations/categories)
+- Machines
+- Products
+- Sales transactions
+
+## Setup
+
+1. Get API credentials from RedPanda
+2. In Gufi: Settings → Environment Variables, add:
+   - `OURVEND_USER` - Your API username
+   - `OURVEND_PASSWORD` - Your API password
+3. Create tables: `groups`, `machines`, `products`, `sales`
+
+## Available Methods
+
+| Method | Description |
+|--------|-------------|
+| `sync_groups` | Sync machine groups/locations |
+| `sync_machines` | Sync machines |
+| `sync_products` | Sync product catalog |
+| `sync_sales` | Sync sales with date range |
+
+## Sync Order
+
+:::warning
+Always sync in this order:
+1. `sync_groups` (first - no dependencies)
+2. `sync_machines` (needs groups)
+3. `sync_products` (no dependencies)
+4. `sync_sales` (needs machines, products, groups)
+:::
+
+## Method: sync_groups
+
+Syncs machine groups (locations, categories).
+
+```javascript
+const result = await gufi.integrations.ourvend.sync_groups({
+  user: env.OURVEND_USER,
+  password: env.OURVEND_PASSWORD,
+  tableName: 'ourvend.groups'
+});
+// Returns: { synced: 12, created: 2, updated: 10 }
+```
+
+## Method: sync_machines
+
+Syncs all machines. Requires groups to be synced first.
+
+```javascript
+const result = await gufi.integrations.ourvend.sync_machines({
+  user: env.OURVEND_USER,
+  password: env.OURVEND_PASSWORD,
+  tableName: 'ourvend.machines',
+  groupsTable: 'ourvend.groups'
+});
+```
+
+## Method: sync_products
+
+Syncs the product catalog.
+
+```javascript
+const result = await gufi.integrations.ourvend.sync_products({
+  user: env.OURVEND_USER,
+  password: env.OURVEND_PASSWORD,
+  tableName: 'ourvend.products'
+});
+```
+
+## Method: sync_sales
+
+Syncs sales transactions. Supports date range filtering.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| user | Yes | API username |
+| password | Yes | API password |
+| tableName | Yes | Target sales table |
+| machinesTable | Yes | Machines table for FK |
+| productsTable | Yes | Products table for FK |
+| groupsTable | Yes | Groups table for FK |
+| dateFrom | No | Start date (ISO format) |
+| dateTo | No | End date (ISO format) |
+
+```javascript
+const result = 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: '2024-01-01',
+  dateTo: '2024-01-31'
+});
+// Returns: { synced: 1250, created: 1250 }
+```
+
+## Complete Daily Sync Example
+
+Trigger: `scheduled` with cron `0 5 * * *` (5 AM daily)
+
+```javascript
+async function ourvend_daily_sync(gufi) {
+  const { env } = gufi.context;
+
+  // 1. Sync groups first
+  const groups = await gufi.integrations.ourvend.sync_groups({
+    user: env.OURVEND_USER,
+    password: env.OURVEND_PASSWORD,
+    tableName: 'ourvend.groups'
+  });
+  gufi.logger.info('Groups synced', groups);
+
+  // 2. Sync machines (needs groups)
+  const machines = await gufi.integrations.ourvend.sync_machines({
+    user: env.OURVEND_USER,
+    password: env.OURVEND_PASSWORD,
+    tableName: 'ourvend.machines',
+    groupsTable: 'ourvend.groups'
+  });
+  gufi.logger.info('Machines synced', machines);
+
+  // 3. Sync products
+  const products = await gufi.integrations.ourvend.sync_products({
+    user: env.OURVEND_USER,
+    password: env.OURVEND_PASSWORD,
+    tableName: 'ourvend.products'
+  });
+  gufi.logger.info('Products synced', products);
+
+  // 4. Sync yesterday's sales
+  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
+  });
+  gufi.logger.info('Sales synced', sales);
+
+  return {
+    groups: groups.synced,
+    machines: machines.synced,
+    products: products.synced,
+    sales: sales.synced
+  };
+}
+```
+
+## Monthly Sales Sync
+
+Trigger: `on_click` - Manual sync of historical data
+
+```javascript
+async function sync_monthly_sales(gufi) {
+  const { env, input } = gufi.context;
+
+  // Get dates from input or default to previous month
+  const now = new Date();
+  const firstDay = input.dateFrom || new Date(now.getFullYear(), now.getMonth() - 1, 1).toISOString().split('T')[0];
+  const lastDay = input.dateTo || new Date(now.getFullYear(), now.getMonth(), 0).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: firstDay,
+    dateTo: lastDay
+  });
+
+  return {
+    message: `Synced ${sales.synced} sales from ${firstDay} to ${lastDay}`
+  };
+}
+```
+
+## Integration with TNS
+
+OurVend sales contain product codes that can be matched with TNS catalog:
+
+```javascript
+// After OurVend sync, sync TNS products from sales
+await gufi.integrations.tns.sync_products_from_sales({
+  productsTable: 'tns.products',
+  categoriesTable: 'tns.categories',
+  salesTable: 'ourvend.sales'
+});
+```
+
+## Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Authentication failed | Wrong credentials | Verify `OURVEND_USER` and `OURVEND_PASSWORD` |
+| Group not found | Missing FK | Run `sync_groups` before `sync_machines` |
+| Product not found | Missing FK | Run `sync_products` before `sync_sales` |
+| Timeout | Large date range | Sync in smaller date ranges (e.g., weekly) |