@teleporthq/teleport-plugin-next-workflows 0.43.62 → 0.43.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teleporthq/teleport-plugin-next-workflows",
-  "version": "0.43.62",
+  "version": "0.43.63",
   "description": "A plugin for workflow code generation in Next.js projects.",
   "author": "teleportHQ",
   "license": "MIT",
@@ -66,8 +66,8 @@
   },
   "dependencies": {
     "@babel/types": "^7.5.5",
-    "@teleporthq/teleport-shared": "^0.43.62",
-    "@teleporthq/teleport-types": "^0.43.62"
+    "@teleporthq/teleport-shared": "^0.43.63",
+    "@teleporthq/teleport-types": "^0.43.63"
   },
-  "gitHead": "7f737c4c1bbabda1d95a0bee8a7d7c488ba17990"
+  "gitHead": "2c7a1001dd77ae05f54ff41f44acfa9f89a156b4"
 }

package/src/nodes/analytics/commerce-tracking.ts

@@ -0,0 +1,93 @@
+/**
+ * The one way a generated workflow handler reports a commerce funnel step.
+ *
+ * ## Why a global and not an import
+ *
+ * A node handler ships as a SERIALIZED function body (`fn.toString()`) that is
+ * evaluated at runtime with no module scope — it cannot import anything. The
+ * analytics tracker publishes `window.tpTrackCommerce` when it boots, and that
+ * global is the only channel a handler can reach.
+ *
+ * ## Why every call is guarded twice
+ *
+ * The global is absent on any project that did not enable analytics, and absent
+ * on every server-side render. These handlers run inside add-to-cart and
+ * checkout, where an exception costs a sale — so a missing tracker has to be a
+ * silent no-op, never a `ReferenceError`. The `try` covers the second failure
+ * mode: a tracker that is present but throws (storage disabled, a browser
+ * extension replacing the global) must not take the cart down with it.
+ *
+ * ## ⛔ Why a calling node must NOT import `trackCommerceStep`
+ *
+ * TypeScript's CommonJS emit rewrites a cross-module call into
+ * `(0, commerce_tracking_1.trackCommerceStep)(...)`. That survives `.toString()`
+ * verbatim, and `commerce_tracking_1` does not exist in the generated workflow
+ * segment — so the handler throws `ReferenceError` the first time a shopper adds
+ * to the cart, in production only, because nothing about it is visible in the
+ * TypeScript source.
+ *
+ * A caller therefore declares the name AMBIENTLY (`declare function
+ * trackCommerceStep`), which emits nothing and leaves a bare identifier in the
+ * serialized body, and appends `COMMERCE_TRACKING_HELPER_SOURCE` so the runtime
+ * definition travels with it. `assertHandlerHasNoModuleRefs` fails the build if
+ * a module reference ever creeps back in.
+ */
+
+/**
+ * ⛔ EXACTLY ONE PARAMETER. Not a style choice.
+ *
+ * When this package is minified by a consumer, the handler's own entry function
+ * loses its conventional name, and `resolveHandlerEntryName` then identifies the
+ * entry by ARITY: it prefers a 2-param declaration, because every real handler
+ * entry is `(config, context)`. A 2-param helper concatenated after a 1-param
+ * entry therefore WINS, and the generated workflow calls the tracking helper
+ * where it meant to call add-to-cart.
+ *
+ * One object parameter keeps the helper out of that contest, and the resolver's
+ * positional fallback then correctly picks the entry, which is emitted first.
+ * `resolve-handler-entry-name.test.ts` checks every registered node type against
+ * exactly this, and is what caught it.
+ *
+ * Not exported either: exporting invites the cross-module call this file exists
+ * to prevent. It is here to be read by `.toString()` below, nothing else.
+ */
+function trackCommerceStep(step: { name: string; detail?: Record<string, unknown> }): void {
+  try {
+    const tracker = (globalThis as Record<string, unknown>).tpTrackCommerce
+    if (typeof tracker === 'function') {
+      ;(tracker as (n: string, d?: Record<string, unknown>) => void)(step.name, step.detail)
+    }
+  } catch (e) {
+    /* analytics must never break a cart or a checkout */
+  }
+}
+
+/** ES5 source of the helper, for concatenating after a serialized handler. */
+export const COMMERCE_TRACKING_HELPER_SOURCE = trackCommerceStep.toString()
+
+/**
+ * Matches the two shapes TypeScript's CJS emit produces for a cross-module
+ * call — `(0, ns_1.fn)(…)` and a bare `ns_1.fn(…)`.
+ */
+const MODULE_REFERENCE = /\b[A-Za-z_$][\w$]*_\d+\s*\./
+
+/**
+ * Fails the BUILD when a serialized handler still references a module namespace.
+ *
+ * Cheap insurance against a failure that is otherwise invisible: the TypeScript
+ * compiles, the tests that only read the source pass, and the handler throws in
+ * a shopper's browser. Called by every `generateHandler` that concatenates a
+ * helper.
+ */
+export function assertHandlerHasNoModuleRefs(source: string, nodeType: string): string {
+  const match = source.match(MODULE_REFERENCE)
+  if (match) {
+    throw new Error(
+      `The "${nodeType}" handler references the module namespace "${match[0]}". ` +
+        'A serialized handler has no module scope, so this throws ReferenceError at ' +
+        'runtime. Declare the helper ambiently (declare function ...) and append its ' +
+        'source instead of importing it.'
+    )
+  }
+  return source
+}

package/src/nodes/cache/page-revalidate.ts

@@ -0,0 +1,140 @@
+import { NodeHandlerGenerator, handlerToString } from '../types'
+
+/**
+ * Rebuilds statically generated pages on the published site.
+ *
+ * This is the OTHER cache a published project serves from. `cache-invalidate`
+ * clears the data-API cache; a page built by `getStaticProps` keeps serving the
+ * HTML it was built with regardless, until its ISR window expires. So an admin
+ * who creates, edits or deletes a row watches the public URL stay wrong for the
+ * length of that window. Calling `res.revalidate(path)` re-runs `getStaticProps`
+ * for that path immediately.
+ *
+ * SERVER-classified deliberately, for the same two reasons as
+ * `cache-invalidate`: `res.revalidate` only exists inside a server route, and
+ * being server-side lands it in the SAME segment as the write it follows, so
+ * adding it to a CRUD workflow costs no extra round trip.
+ *
+ * It reaches the rebuild through the app's own `POST /api/tq-revalidate` rather
+ * than by importing anything: node handlers ship as runtime source and are
+ * re-bundled by webpack, which rewrites `require(` — so an internal HTTP call is
+ * the sanctioned way for a handler to reach server-side machinery, and it is
+ * also the only way to get at a `res` object with `revalidate` on it.
+ *
+ * ⛔ Never mark this node fire-and-forget. Its workflows navigate or refresh a
+ * page immediately afterwards, and that reload routinely wins the race against
+ * an unawaited rebuild — leaving the visitor looking at the stale page this was
+ * meant to replace.
+ *
+ * ⛔ It also must NEVER return `{ success: false }` or a string `error`. The
+ * runtime treats both as FATAL and halts the workflow (`isFatalNodeResult`), so
+ * a page that could not be rebuilt would abort an admin's save AFTER the row was
+ * already written — no success toast, no navigation, and an error for an action
+ * that worked. Outcomes are reported as `revalidated` plus a `warning`, and the
+ * page's own ISR window remains the safety net.
+ */
+async function page_revalidate(config: any, context: Record<string, unknown>) {
+  const configured = Array.isArray(config.paths)
+    ? config.paths
+    : config.paths === undefined || config.paths === null
+    ? []
+    : [config.paths]
+
+  // One level of flattening: a step that revalidates several rows at once (a
+  // bulk delete, say) resolves ONE reference to an array of slugs rather than
+  // configuring a path per row.
+  const flattened: unknown[] = []
+  for (let i = 0; i < configured.length; i++) {
+    const entry = configured[i]
+    if (Array.isArray(entry)) {
+      for (let j = 0; j < entry.length; j++) {
+        flattened.push(entry[j])
+      }
+      continue
+    }
+    flattened.push(entry)
+  }
+
+  const paths: string[] = []
+  for (let i = 0; i < flattened.length; i++) {
+    const raw = flattened[i]
+    if (raw === undefined || raw === null || typeof raw === 'object') {
+      continue
+    }
+    const trimmed = String(raw).trim()
+    if (!trimmed) {
+      continue
+    }
+    // `res.revalidate` only accepts a site-root-relative path, and a step whose
+    // path came from a database column often holds the bare slug.
+    const normalized = trimmed.charAt(0) === '/' ? trimmed : '/' + trimmed
+    if (paths.indexOf(normalized) === -1) {
+      paths.push(normalized)
+    }
+  }
+
+  if (!paths.length) {
+    return {
+      revalidated: [],
+      warning: 'No page paths were configured on this step.',
+    }
+  }
+
+  const baseUrl = (context.__baseUrl as string) || ''
+  const __internalHeaders = (context.__internalHeaders as Record<string, string>) || {}
+  const __env = (globalThis as any).process && (globalThis as any).process.env
+  const secret = __env ? __env.TQ_CACHE_SECRET : ''
+
+  if (!secret) {
+    // Reported rather than thrown: the write this follows already succeeded, and
+    // the page still refreshes on its own revalidate window.
+    return {
+      revalidated: [],
+      warning:
+        'TQ_CACHE_SECRET is not configured, so published pages will refresh on their own schedule.',
+    }
+  }
+
+  try {
+    const response = await fetch(baseUrl + '/api/tq-revalidate', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-tq-cache-secret': secret,
+        ...__internalHeaders,
+      },
+      body: JSON.stringify({ paths }),
+    })
+
+    const data = await response.json()
+
+    if (!response.ok || !data.ok) {
+      const warning: string =
+        data.error || 'The published pages could not be refreshed; they will refresh on their own.'
+      return { revalidated: [], warning }
+    }
+
+    const revalidated = Array.isArray(data.revalidated) ? data.revalidated : []
+    const failed = Array.isArray(data.failed) ? data.failed : []
+
+    if (failed.length) {
+      return {
+        revalidated,
+        warning:
+          'Some pages could not be refreshed and will refresh on their own: ' + failed.join(', '),
+      }
+    }
+
+    return { revalidated }
+  } catch (err: unknown) {
+    return { revalidated: [], warning: (err as Error).message }
+  }
+}
+
+export const pageRevalidate: NodeHandlerGenerator = {
+  nodeType: 'page-revalidate',
+  executionEnv: 'server',
+  generateHandler(): string {
+    return handlerToString(page_revalidate)
+  },
+}

package/src/nodes/cart/cart-add-item.ts

@@ -1,4 +1,15 @@
 import { NodeHandlerGenerator, handlerToString } from '../types'
+import {
+  COMMERCE_TRACKING_HELPER_SOURCE,
+  assertHandlerHasNoModuleRefs,
+} from '../analytics/commerce-tracking'
+
+// AMBIENT, not imported. A cross-module call compiles to
+// `(0, commerce_tracking_1.trackCommerceStep)(...)`, which survives
+// `.toString()` and throws ReferenceError in the browser — the runtime has no
+// module scope. Declaring the name emits nothing and leaves a bare identifier
+// that the appended helper source defines. See `commerce-tracking.ts`.
+declare function trackCommerceStep(step: { name: string; detail?: Record<string, unknown> }): void
 
 async function cart_add_item(config: any) {
   const productId = config.productId
@@ -79,6 +90,16 @@ async function cart_add_item(config: any) {
       if (typeof window !== 'undefined') {
         window.dispatchEvent(new CustomEvent('teleport:cart-changed'))
       }
+      // Reported AFTER the write succeeds, so the funnel counts carts that were
+      // really changed rather than clicks that were merely attempted.
+      trackCommerceStep({
+        name: 'add_to_cart',
+        detail: {
+          currency,
+          value: price * quantity,
+          items: [{ item_id: productId, item_name: name, price, quantity }],
+        },
+      })
       return {
         id: cart[existingIndex].id,
         productId,
@@ -110,6 +131,14 @@ async function cart_add_item(config: any) {
       if (typeof window !== 'undefined') {
         window.dispatchEvent(new CustomEvent('teleport:cart-changed'))
       }
+      trackCommerceStep({
+        name: 'add_to_cart',
+        detail: {
+          currency,
+          value: price * initialQty,
+          items: [{ item_id: productId, item_name: name, price, quantity: initialQty }],
+        },
+      })
       return { id: newItem.id, productId, quantity: initialQty }
     }
   } catch (err: unknown) {
@@ -120,6 +149,11 @@ export const cartAddItem: NodeHandlerGenerator = {
   nodeType: 'cart-add-item',
   executionEnv: 'client',
   generateHandler(): string {
-    return handlerToString(cart_add_item)
+    // The helper is concatenated rather than imported: the handler ships as a
+    // serialized function body with no module scope. See `commerce-tracking.ts`.
+    return assertHandlerHasNoModuleRefs(
+      handlerToString(cart_add_item) + '\n' + COMMERCE_TRACKING_HELPER_SOURCE,
+      'cart-add-item'
+    )
   },
 }

package/src/nodes/cart/cart-remove-item.ts

@@ -1,4 +1,15 @@
 import { NodeHandlerGenerator, handlerToString } from '../types'
+import {
+  COMMERCE_TRACKING_HELPER_SOURCE,
+  assertHandlerHasNoModuleRefs,
+} from '../analytics/commerce-tracking'
+
+// AMBIENT, not imported. A cross-module call compiles to
+// `(0, commerce_tracking_1.trackCommerceStep)(...)`, which survives
+// `.toString()` and throws ReferenceError in the browser — the runtime has no
+// module scope. Declaring the name emits nothing and leaves a bare identifier
+// that the appended helper source defines. See `commerce-tracking.ts`.
+declare function trackCommerceStep(step: { name: string; detail?: Record<string, unknown> }): void
 
 async function cart_remove_item(config: any) {
   const itemId = config.itemId
@@ -6,12 +17,33 @@ async function cart_remove_item(config: any) {
   try {
     const raw = localStorage.getItem('workflow_cart')
     const cart: any[] = raw ? JSON.parse(raw) : []
+    const removed = cart.find((item: any) => item.id === itemId)
     const newCart = cart.filter((item: any) => item.id !== itemId)
 
     localStorage.setItem('workflow_cart', JSON.stringify(newCart))
     if (typeof window !== 'undefined') {
       window.dispatchEvent(new CustomEvent('teleport:cart-changed'))
     }
+    // Only when a line was actually removed: a remove call for an id that is no
+    // longer in the cart (a double click, a stale button) changed nothing, and
+    // counting it would overstate the abandonment the merchant reads here.
+    if (removed) {
+      trackCommerceStep({
+        name: 'remove_from_cart',
+        detail: {
+          currency: removed.currency,
+          value: (Number(removed.price) || 0) * (Number(removed.quantity) || 0),
+          items: [
+            {
+              item_id: removed.productId,
+              item_name: removed.name,
+              price: removed.price,
+              quantity: removed.quantity,
+            },
+          ],
+        },
+      })
+    }
     return { success: true, cart: newCart }
   } catch (err: unknown) {
     return { success: false, error: (err as Error).message }
@@ -21,6 +53,9 @@ export const cartRemoveItem: NodeHandlerGenerator = {
   nodeType: 'cart-remove-item',
   executionEnv: 'client',
   generateHandler(): string {
-    return handlerToString(cart_remove_item)
+    return assertHandlerHasNoModuleRefs(
+      handlerToString(cart_remove_item) + '\n' + COMMERCE_TRACKING_HELPER_SOURCE,
+      'cart-remove-item'
+    )
   },
 }

package/src/nodes/data/data-create-item.ts

@@ -30,6 +30,49 @@ async function data_create_item(config: any, context: any) {
     }
   }
 
+  // A value the client→server hand-off could not carry (see pruneContext: any
+  // context entry over its budget crosses as { __truncated: true }) must never
+  // be INSERTed — the placeholder object would be stored as the column's
+  // content. Dropping the mapping leaves the column at its default, which is
+  // recoverable; a row whose body reads {"__truncated":true} is not.
+  const __isUnwritableValue = function (__v: any) {
+    return (
+      !!__v &&
+      typeof __v === 'object' &&
+      (__v.__truncated === true || __v.__serializationError === true)
+    )
+  }
+  const __warnDroppedMapping = function (__col: any) {
+    if (typeof console !== 'undefined' && console.warn) {
+      console.warn(
+        '[workflow] data-create-item left "' +
+          (__col || 'unknown') +
+          '" unset: the value was too large to reach the server'
+      )
+    }
+  }
+  let effectiveColumnMappings: any = columnMappings
+  if (Array.isArray(columnMappings)) {
+    effectiveColumnMappings = columnMappings.filter(function (__m: any) {
+      if (!(__m && typeof __m === 'object') || !__isUnwritableValue(__m.value)) {
+        return true
+      }
+      __warnDroppedMapping(__m.column || __m.name || __m.field)
+      return false
+    })
+  } else if (columnMappings && typeof columnMappings === 'object') {
+    effectiveColumnMappings = {}
+    const __ck = Object.keys(columnMappings)
+    for (let __ci = 0; __ci < __ck.length; __ci++) {
+      const __value = (columnMappings as any)[__ck[__ci]]
+      if (__isUnwritableValue(__value)) {
+        __warnDroppedMapping(__ck[__ci])
+      } else {
+        ;(effectiveColumnMappings as any)[__ck[__ci]] = __value
+      }
+    }
+  }
+
   // Surface the workflow's anonymous-user UUID to the data-api so a
   // guest-checkout INSERT can recover its `user_id` from the
   // resolve-user output instead of being NULL'd by the UUID
@@ -59,7 +102,7 @@ async function data_create_item(config: any, context: any) {
   }
 
   try {
-    const reqBody: any = { tableName, columnMappings }
+    const reqBody: any = { tableName, columnMappings: effectiveColumnMappings }
     if (__anonymousUserId) {
       reqBody.__anonymousUserId = __anonymousUserId
     }

package/src/nodes/data/data-update-item.ts

@@ -67,17 +67,53 @@ async function data_update_item(config: any, context: any) {
   // guests.full_name from an un-prefilled guest_name input. OMIT such mappings so
   // the column keeps its stored value. (An intentional null — e.g. a route-param
   // sentinel degraded above — is preserved: only `undefined` is dropped.)
+  //
+  // A value the client→server hand-off could not carry (see pruneContext: any
+  // context entry over its budget crosses as { __truncated: true }) is dropped
+  // for the same reason and with the same result — the column KEEPS what it
+  // holds. Writing the placeholder instead destroys the stored value, which is
+  // how a rich-text field with an inlined image emptied a whole page of blocks.
+  const __isUnwritableValue = function (__v: any) {
+    if (__v === undefined) {
+      return true
+    }
+    if (!__v || typeof __v !== 'object') {
+      return false
+    }
+    return __v.__truncated === true || __v.__serializationError === true
+  }
+  const __warnDroppedMapping = function (__col: any) {
+    if (typeof console !== 'undefined' && console.warn) {
+      console.warn(
+        '[workflow] data-update-item kept the stored value of "' +
+          (__col || 'unknown') +
+          '": the new value was too large to reach the server (it stays as it was)'
+      )
+    }
+  }
   let effectiveColumnMappings: any = columnMappings
   if (Array.isArray(columnMappings)) {
     effectiveColumnMappings = columnMappings.filter(function (__m: any) {
-      return !(__m && typeof __m === 'object' && __m.value === undefined)
+      if (!(__m && typeof __m === 'object')) {
+        return true
+      }
+      if (!__isUnwritableValue(__m.value)) {
+        return true
+      }
+      if (__m.value !== undefined) {
+        __warnDroppedMapping(__m.column || __m.name || __m.field)
+      }
+      return false
     })
   } else if (columnMappings && typeof columnMappings === 'object') {
     effectiveColumnMappings = {}
     const __ck = Object.keys(columnMappings)
     for (let __ci = 0; __ci < __ck.length; __ci++) {
-      if ((columnMappings as any)[__ck[__ci]] !== undefined) {
-        ;(effectiveColumnMappings as any)[__ck[__ci]] = (columnMappings as any)[__ck[__ci]]
+      const __value = (columnMappings as any)[__ck[__ci]]
+      if (!__isUnwritableValue(__value)) {
+        ;(effectiveColumnMappings as any)[__ck[__ci]] = __value
+      } else if (__value !== undefined) {
+        __warnDroppedMapping(__ck[__ci])
       }
     }
   }

package/src/nodes/index.ts

@@ -39,6 +39,7 @@ import { browserWriteClipboard } from './browser/browser-write-clipboard'
 import { cacheGet } from './cache/cache-get'
 import { cacheSet } from './cache/cache-set'
 import { cacheInvalidate } from './cache/cache-invalidate'
+import { pageRevalidate } from './cache/page-revalidate'
 import { cartAddItem } from './cart/cart-add-item'
 import { cartClear } from './cart/cart-clear'
 import { cartGetItems } from './cart/cart-get-items'
@@ -97,6 +98,7 @@ import { navigationRefreshPage } from './navigation/navigation-refresh-page'
 import { paymentCancelPlan } from './payment/payment-cancel-plan'
 import { paymentChargeUser } from './payment/payment-charge-user'
 import { paymentCreateCustomer } from './payment/payment-create-customer'
+import { paymentRefund } from './payment/payment-refund'
 import { paymentCreateProduct } from './payment/payment-create-product'
 import { paymentCreateSubscription } from './payment/payment-create-subscription'
 import { paymentGetCustomer } from './payment/payment-get-customer'
@@ -262,6 +264,7 @@ export const nodeRegistry: Record<string, NodeHandlerGenerator> = {
   'navigation-refresh-page': navigationRefreshPage,
   'payment-cancel-plan': paymentCancelPlan,
   'payment-charge-user': paymentChargeUser,
+  'payment-refund': paymentRefund,
   'payment-create-customer': paymentCreateCustomer,
   'payment-create-product': paymentCreateProduct,
   'payment-create-subscription': paymentCreateSubscription,
@@ -297,6 +300,7 @@ export const nodeRegistry: Record<string, NodeHandlerGenerator> = {
   'cache-get': cacheGet,
   'cache-set': cacheSet,
   'cache-invalidate': cacheInvalidate,
+  'page-revalidate': pageRevalidate,
   'toast-show': toastShow,
   'transform-array': transformArray,
   'transform-calculate': transformCalculate,