@friggframework/core 2.0.0--canary.696.5d9f1be.0 → 2.0.0--canary.698.b1a2d30.0

package/integrations/data-defined/capabilities/salesforce.capabilities.json

@@ -321,30 +321,44 @@
     "scope": "installation",
     "topic": "{{body.payload.ChangeEventHeader.entityName}}.{{body.payload.ChangeEventHeader.changeType}}",
     "eventId": "{{body.id}}",
-    "verify": "verifyWebhookSignature"
+    "verify": "verifyWebhookSignature",
+    "status": "unimplemented",
+    "note": "The salesforce Api has no verifyWebhookSignature method; webhook signatures cannot be checked until the module adds one."
   },
   "capabilities": {
     "lead.get": {
       "kind": "read",
-      "method": "getLead",
+      "method": "get",
       "input": {
         "id": {
           "type": "string",
           "required": true
         }
       },
-      "output": "lead"
+      "output": "lead",
+      "args": [
+        {
+          "value": "Lead"
+        },
+        "id"
+      ]
     },
     "lead.create": {
       "kind": "write",
-      "method": "createLead",
+      "method": "create",
       "input": {
         "fields": {
           "type": "object",
           "required": true
         }
       },
-      "output": "lead"
+      "output": "lead",
+      "args": [
+        {
+          "value": "Lead"
+        },
+        "fields"
+      ]
     },
     "lead.update": {
       "kind": "write",
@@ -359,7 +373,9 @@
           "required": true
         }
       },
-      "output": "void"
+      "output": "void",
+      "status": "unimplemented",
+      "note": "Api.update(object, data) needs the record id inside data (data.Id); the capability passes the id separately, so there is no way to call it."
     },
     "person.searchByEmail": {
       "kind": "search",
@@ -371,18 +387,26 @@
           "required": true
         }
       },
-      "output": "{ leads: lead[], contacts: contact[] }"
+      "output": "{ leads: lead[], contacts: contact[] }",
+      "status": "unimplemented",
+      "note": "Api.find(object, filter) searches one sObject at a time; searching Lead and Contact together would need two calls."
     },
     "event.create": {
       "kind": "write",
-      "method": "createEvent",
+      "method": "create",
       "input": {
         "fields": {
           "type": "object",
           "required": true
         }
       },
-      "output": "event"
+      "output": "event",
+      "args": [
+        {
+          "value": "Event"
+        },
+        "fields"
+      ]
     },
     "event.update": {
       "kind": "write",
@@ -397,18 +421,26 @@
           "required": true
         }
       },
-      "output": "void"
+      "output": "void",
+      "status": "unimplemented",
+      "note": "Api.update(object, data) needs the record id inside data (data.Id); the capability passes the id separately, so there is no way to call it."
     },
     "opportunity.get": {
       "kind": "read",
-      "method": "getOpportunity",
+      "method": "get",
       "input": {
         "id": {
           "type": "string",
           "required": true
         }
       },
-      "output": "opportunity"
+      "output": "opportunity",
+      "args": [
+        {
+          "value": "Opportunity"
+        },
+        "id"
+      ]
     },
     "opportunity.update": {
       "kind": "write",
@@ -423,18 +455,26 @@
           "required": true
         }
       },
-      "output": "void"
+      "output": "void",
+      "status": "unimplemented",
+      "note": "Api.update(object, data) needs the record id inside data (data.Id); the capability passes the id separately, so there is no way to call it."
     },
     "task.create": {
       "kind": "write",
-      "method": "createTask",
+      "method": "create",
       "input": {
         "fields": {
           "type": "object",
           "required": true
         }
       },
-      "output": "task"
+      "output": "task",
+      "args": [
+        {
+          "value": "Task"
+        },
+        "fields"
+      ]
     },
     "file.attach": {
       "kind": "write",
@@ -457,7 +497,9 @@
           "required": true
         }
       },
-      "output": "contentVersion"
+      "output": "contentVersion",
+      "status": "unimplemented",
+      "note": "Api has the generic create(object, data) only; ContentVersion field names differ from this capability's inputs."
     },
     "note.create": {
       "kind": "write",
@@ -476,7 +518,9 @@
           "required": true
         }
       },
-      "output": "contentNote"
+      "output": "contentNote",
+      "status": "unimplemented",
+      "note": "Api has the generic create(object, data) only; ContentNote field names differ from this capability's inputs."
     },
     "user.list": {
       "kind": "read",
@@ -486,7 +530,9 @@
           "type": "boolean"
         }
       },
-      "output": "user[]"
+      "output": "user[]",
+      "status": "unimplemented",
+      "note": "Api has find(object, filter) but no user listing with an activeOnly filter."
     }
   },
   "options": {

package/integrations/data-defined/capabilities/slack.capabilities.json

@@ -206,7 +206,9 @@
       "body": {
         "challenge": "$.body.challenge"
       }
-    }
+    },
+    "status": "unimplemented",
+    "note": "The slack Api has no verifyWebhookSignature method; webhook signatures cannot be checked until the module adds one."
   },
   "capabilities": {
     "message.post": {
@@ -285,7 +287,7 @@
     },
     "message.permalink": {
       "kind": "read",
-      "method": "getPermalink",
+      "method": "getMessagePermalink",
       "label": "chat.getPermalink",
       "input": {
         "channel": {
@@ -301,7 +303,7 @@
     },
     "channel.list": {
       "kind": "read",
-      "method": "listConversations",
+      "method": "listChannels",
       "label": "conversations.list",
       "input": {
         "types": {
@@ -325,7 +327,9 @@
           "type": "number"
         }
       },
-      "output": "user[]"
+      "output": "user[]",
+      "status": "unimplemented",
+      "note": "Api has lookupUserByEmail, getUserById and getUserProfileById, but no user listing."
     },
     "user.lookupByEmail": {
       "kind": "read",
@@ -337,7 +341,10 @@
           "required": true
         }
       },
-      "output": "user"
+      "output": "user",
+      "args": [
+        "email"
+      ]
     }
   },
   "options": {

package/integrations/data-defined/capabilities/stripe.capabilities.json

@@ -471,7 +471,9 @@
     "topic": "{{body.type}}",
     "eventId": "{{body.id}}",
     "account": "{{body.account}}",
-    "verify": "verifyWebhookSignature"
+    "verify": "verifyWebhookSignature",
+    "status": "unimplemented",
+    "note": "The stripe Api has no verifyWebhookSignature method; webhook signatures cannot be checked until the module adds one."
   },
   "capabilities": {
     "customer.get": {
@@ -483,7 +485,9 @@
           "required": true
         }
       },
-      "output": "customer"
+      "output": "customer",
+      "status": "unimplemented",
+      "note": "Api wraps balance transactions, charges, accounts and webhook endpoints only; customers, payment intents, refunds and payouts are not exposed."
     },
     "customer.list": {
       "kind": "read",
@@ -499,7 +503,9 @@
           "type": "string"
         }
       },
-      "output": "page<customer>"
+      "output": "page<customer>",
+      "status": "unimplemented",
+      "note": "Api wraps balance transactions, charges, accounts and webhook endpoints only; customers, payment intents, refunds and payouts are not exposed."
     },
     "customer.search": {
       "kind": "search",
@@ -510,7 +516,9 @@
           "required": true
         }
       },
-      "output": "customer[]"
+      "output": "customer[]",
+      "status": "unimplemented",
+      "note": "Api wraps balance transactions, charges, accounts and webhook endpoints only; customers, payment intents, refunds and payouts are not exposed."
     },
     "customer.create": {
       "kind": "write",
@@ -521,7 +529,9 @@
           "required": true
         }
       },
-      "output": "customer"
+      "output": "customer",
+      "status": "unimplemented",
+      "note": "Api wraps balance transactions, charges, accounts and webhook endpoints only; customers, payment intents, refunds and payouts are not exposed."
     },
     "customer.update": {
       "kind": "write",
@@ -536,7 +546,9 @@
           "required": true
         }
       },
-      "output": "customer"
+      "output": "customer",
+      "status": "unimplemented",
+      "note": "Api wraps balance transactions, charges, accounts and webhook endpoints only; customers, payment intents, refunds and payouts are not exposed."
     },
     "paymentIntent.get": {
       "kind": "read",
@@ -550,7 +562,9 @@
           "type": "array"
         }
       },
-      "output": "paymentIntent"
+      "output": "paymentIntent",
+      "status": "unimplemented",
+      "note": "Api wraps balance transactions, charges, accounts and webhook endpoints only; customers, payment intents, refunds and payouts are not exposed."
     },
     "refund.get": {
       "kind": "read",
@@ -561,7 +575,9 @@
           "required": true
         }
       },
-      "output": "refund"
+      "output": "refund",
+      "status": "unimplemented",
+      "note": "Api wraps balance transactions, charges, accounts and webhook endpoints only; customers, payment intents, refunds and payouts are not exposed."
     },
     "payout.list": {
       "kind": "read",
@@ -580,11 +596,13 @@
           "type": "number"
         }
       },
-      "output": "payout[]"
+      "output": "payout[]",
+      "status": "unimplemented",
+      "note": "Api wraps balance transactions, charges, accounts and webhook endpoints only; customers, payment intents, refunds and payouts are not exposed."
     },
     "balanceTransaction.list": {
       "kind": "read",
-      "method": "listBalanceTransactions",
+      "method": "getBalanceTransactions",
       "input": {
         "payout": {
           "type": "string",

package/integrations/data-defined/data-defined-integration.js

@@ -18,7 +18,7 @@
  */
 const crypto = require('crypto');
 const { compile, routeWebhook, eventName } = require('./compile');
-const { makePorts, runWorkflow, resumeWorkflow, runQuery, renderSurface, runLifecycle, resolveOptions, installContext } = require('./runtime');
+const { argumentsFor, makePorts, runWorkflow, resumeWorkflow, runQuery, renderSurface, runLifecycle, resolveOptions, installContext } = require('./runtime');
 const { createSyncEngine } = require('./sync-engine');
 const { eventsIn, handshakeFor, modulesFor } = require('./webhooks');
 const { buildConfigForm, missingRequired } = require('./config-form');
@@ -252,7 +252,7 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
                     return runCode(ref, args);
                 },
                 // The shared class registers modules by module name; a definition may name them by its own keys.
-                callApi: (moduleKey, method, args) => this.moduleFor(moduleKey).api[method](args),
+                callApi: (moduleKey, method, args, order) => this.moduleFor(moduleKey).api[method](...argumentsFor(args, order)),
                 store: this.mappingStore(),
             });
         }

package/integrations/data-defined/examples/asana-slack.definition.json

@@ -35,7 +35,7 @@
       "options": {
         "source": "asana.project",
         "with": {
-          "workspaceGid": "$.settings.workspace"
+          "workspace": "$.settings.workspace"
         }
       },
       "label": "Project to announce completed tasks from",
@@ -163,8 +163,7 @@
           "id": "task",
           "use": "asana.task.get",
           "with": {
-            "taskGid": "$.record.gid",
-            "opt_fields": "name,completed,completed_by.name,assignee.name,permalink_url"
+            "taskGid": "$.record.gid"
           }
         },
         {
@@ -178,14 +177,14 @@
           "use": "slack.message.post",
           "with": {
             "channel": "$.settings.channel",
-            "text": ":white_check_mark: {{steps.task.completed_by.name | default: 'Someone'}} completed <{{steps.task.permalink_url}}|{{steps.task.name}}>"
+            "text": ":white_check_mark: {{steps.task.completed_by.name | default: 'Someone' | mrkdwn}} completed <{{steps.task.permalink_url}}|{{steps.task.name | mrkdwn}}>"
           }
         }
       ]
     }
   ],
   "templates": {
-    "assignee-digest": ":spiral_calendar_pad: Hi {{item.firstName | default: item.name}}, you have {{item.count}} Asana task(s) due tomorrow:\n{{item.lines}}",
+    "assignee-digest": ":spiral_calendar_pad: Hi {{item.firstName | default: item.name | mrkdwn}}, you have {{item.count}} Asana task(s) due tomorrow:\n{{item.lines}}",
     "unassigned-digest": ":warning: {{steps.groups.unassignedCount}} task(s) due tomorrow have no assignee:\n{{steps.groups.unassignedLines}}"
   },
   "lifecycle": {

package/integrations/data-defined/examples/hubspot-slack.definition.json

@@ -258,7 +258,7 @@
               "when": "$.steps.slackUser.id exists",
               "with": {
                 "channel": "$.steps.slackUser.id",
-                "text": "Due today: {{item.properties.hs_task_subject}}",
+                "text": "Due today: {{item.properties.hs_task_subject | mrkdwn}}",
                 "metadata": {
                   "event_type": "hubspot_task",
                   "event_payload": {
@@ -401,9 +401,9 @@
     }
   ],
   "templates": {
-    "deal-won": ":tada: *{{steps.deal.properties.dealname}}* closed won for ${{steps.deal.properties.amount | default: '?'}}. Nice work {{steps.owner.firstName | default: 'team'}}! <https://app.hubspot.com/contacts/{{install.portalId}}/record/0-3/{{steps.deal.id}}|Open deal>",
-    "high-value": ":moneybag: New deal over ${{settings.threshold}}: *{{steps.deal.properties.dealname}}* (${{steps.deal.properties.amount}}), closing {{steps.deal.properties.closedate | date}}. <https://app.hubspot.com/contacts/{{install.portalId}}/record/0-3/{{steps.deal.id}}|Open deal>",
-    "digest-line": "\u2022 <https://app.hubspot.com/contacts/{{install.portalId}}/record/0-3/{{item.id}}|{{item.properties.dealname}}>: ${{item.properties.amount | default: 0}}, closes {{item.properties.closedate | date}}",
+    "deal-won": ":tada: *{{steps.deal.properties.dealname | mrkdwn}}* closed won for ${{steps.deal.properties.amount | default: '?'}}. Nice work {{steps.owner.firstName | default: 'team' | mrkdwn}}! <https://app.hubspot.com/contacts/{{install.portalId}}/record/0-3/{{steps.deal.id}}|Open deal>",
+    "high-value": ":moneybag: New deal over ${{settings.threshold}}: *{{steps.deal.properties.dealname | mrkdwn}}* (${{steps.deal.properties.amount}}), closing {{steps.deal.properties.closedate | date}}. <https://app.hubspot.com/contacts/{{install.portalId}}/record/0-3/{{steps.deal.id}}|Open deal>",
+    "digest-line": "\u2022 <https://app.hubspot.com/contacts/{{install.portalId}}/record/0-3/{{item.id}}|{{item.properties.dealname | mrkdwn}}>: ${{item.properties.amount | default: 0}}, closes {{item.properties.closedate | date}}",
     "digest": ":calendar: *Closing in the next 7 days* ({{steps.deals | size}} deals)\n{{steps.build | join: '\\n'}}"
   }
 }

package/integrations/data-defined/examples/klaviyo-hubspot.definition.json

@@ -239,10 +239,7 @@
           "id": "contact",
           "use": "hubspot.contact.get",
           "with": {
-            "id": "$.record.objectId",
-            "properties": [
-              "email"
-            ]
+            "id": "$.record.objectId"
           }
         },
         {

package/integrations/data-defined/examples/phone-hubspot.definition.json

@@ -243,11 +243,7 @@
           "id": "full",
           "use": "hubspot.contact.get",
           "with": {
-            "id": "$.steps.contact.hubspot",
-            "properties": [
-              "hubspot_owner_id",
-              "firstname"
-            ]
+            "id": "$.steps.contact.hubspot"
           }
         },
         {

package/integrations/data-defined/expressions.js

@@ -46,6 +46,8 @@ const FILTERS = {
     seconds: (v) => (v == null ? '' : String(Math.round(Number(v) / 1000))),
     date: (v) => (v ? new Date(v).toISOString().slice(0, 10) : ''),
     json: (v) => JSON.stringify(v),
+    // Record data inside a Slack message: escaped so a name like "*x* <!channel>" neither formats nor pings.
+    mrkdwn: (v) => require('./renderers/slack').escapeMrkdwn(v),
     default: (v, arg) => (v == null || v === '' ? arg : v),
     truncate: (v, arg) => { const s = String(v ?? ''); const n = Number(arg) || 80; return s.length > n ? s.slice(0, n - 1) + '…' : s; },
     // lists

package/integrations/data-defined/index.js

@@ -15,6 +15,11 @@ const { TRANSFORMS, applyMapping } = require('./transforms');
 const { FILTERS } = require('./expressions');
 const { validateManifest } = require('./manifests');
 const { checkDefinition, checkManifest, checkInstallation } = require('./schema-check');
+const { viewToSlack, escapeMrkdwn } = require('./renderers/slack');
+const { viewToHubSpot } = require('./renderers/hubspot');
+const { viewToHtml, slackMessageToHtml } = require('./renderers/html');
+const { previewSurface, previewWorkflow, recordingPorts } = require('./renderers/preview');
+const { decodeAction } = require('./renderers/common');
 const useCases = require('./use-cases/definition-use-cases');
 
 /** Load every capabilities/*.capabilities.json (bundled mocks; real modules ship their own). */
@@ -35,5 +40,6 @@ module.exports = {
     defineIntegrationClass, defineSharedIntegrationClass, extendIntegrationClass, memoryDefinitions,
     BUILTINS, TRANSFORMS, FILTERS, applyMapping, resolveOptions,
     loadManifests, loadExamples,
+    viewToSlack, escapeMrkdwn, viewToHubSpot, viewToHtml, slackMessageToHtml, previewSurface, previewWorkflow, recordingPorts, decodeAction,
     ...useCases,
 };

package/integrations/data-defined/manifests.js

@@ -40,6 +40,23 @@ function validateManifest(m) {
         if (!KINDS.has(c?.kind)) err(`${p}.kind`, [...KINDS].join(', '));
         if (!/^[A-Za-z_$][\w$]*$/.test(c?.method || '')) err(`${p}.method`, 'Name of a method on the module\'s Api class');
         for (const [arg, spec] of Object.entries(c?.input || {})) if (!spec?.type) err(`${p}.input.${arg}`, 'Input needs a type');
+        if (c?.status !== undefined && c.status !== 'unimplemented') err(`${p}.status`, 'Only "unimplemented" (the module\'s Api has no such method)');
+        if (c?.args !== undefined) {
+            if (!Array.isArray(c.args)) err(`${p}.args`, 'An ordered list: input names, "$rest", or { value }');
+            else {
+                const named = new Set();
+                c.args.forEach((a, i) => {
+                    if (typeof a === 'string' && a !== '$rest') {
+                        if (!(a in (c.input || {}))) err(`${p}.args[${i}]`, `"${a}" is not an input of this capability`);
+                        else if (named.has(a)) err(`${p}.args[${i}]`, `"${a}" is passed twice`);
+                        named.add(a);
+                    } else if (a === '$rest') { if (c.args.indexOf('$rest') !== i) err(`${p}.args[${i}]`, '"$rest" appears once'); }
+                    else if (!(a && typeof a === 'object' && 'value' in a)) err(`${p}.args[${i}]`, 'An input name, "$rest" or { value }');
+                });
+                // An input that is never passed would be accepted and silently dropped.
+                if (!c.args.includes('$rest')) for (const k of Object.keys(c.input || {})) if (!named.has(k)) err(`${p}.args`, `Input "${k}" is declared but never passed to ${c.method}; list it in args or use "$rest"`);
+            }
+        }
     }
 
     // How a sync reads and writes an object (sync-engine.js). Each operation names a capability of the right kind on
@@ -140,6 +157,7 @@ function validateManifest(m) {
         if (w.account) tpl(w.account, 'webhook.account');
         const batch = w.batch == null ? [] : Array.isArray(w.batch) ? w.batch : [w.batch];
         if (batch.length > 2 || batch.some((b) => typeof b !== 'string')) err('webhook.batch', 'A path to the array of events, or [outer, inner] for two levels');
+        if (w.status !== undefined && w.status !== 'unimplemented') err('webhook.status', 'Only "unimplemented" (the module\'s Api has no verify method)');
         if (w.verify != null && !/^[A-Za-z_$][\w$]*$/.test(w.verify)) err('webhook.verify', 'Name of an Api method that checks the signature');
         if (w.handshake) {
             try { parseCondition(w.handshake.when); } catch (e) { err('webhook.handshake.when', e.message); }

package/integrations/data-defined/renderers/common.js

@@ -0,0 +1,67 @@
+/**
+ * What every renderer shares: coercion of view props (they come from record data, so any type can arrive), the one
+ * URL rule, truncation that never leaves half an entity behind, and the button <-> Slack round trip.
+ */
+
+/** A view prop as text. Objects are JSON, null/undefined are empty: a renderer never prints "[object Object]" or "undefined". */
+function str(v) {
+    if (v == null) return '';
+    if (typeof v === 'string') return v;
+    if (typeof v === 'object') { try { return JSON.stringify(v); } catch (_) { return ''; } }
+    return String(v);
+}
+
+/**
+ * Only http(s) links leave a preview or a card. Record data decides these URLs ("{{data.proposal.recording}}"), and a
+ * `javascript:` or `data:` URL in a vendor field must not become a clickable thing in someone's HubSpot or Slack.
+ * @returns {string|null}
+ */
+function safeUrl(u) {
+    const s = str(u).trim();
+    if (!/^https?:\/\/[^\s<>"']+$/i.test(s)) return null;
+    try { new URL(s); } catch (_) { return null; }
+    return s;
+}
+
+/**
+ * Cut to at most `max` characters, ending in the marker. Never leaves a dangling half of a Slack entity ("&am"), which
+ * would render as literal junk instead of the character it stood for.
+ */
+function truncate(s, max, marker = '…') {
+    s = String(s);
+    if (s.length <= max) return s;
+    let cut = s.slice(0, Math.max(0, max - marker.length));
+    cut = cut.replace(/&(?:[a-z]{1,4}|#\d{0,6}|#x[0-9a-f]{0,5})?$/i, '');
+    return cut + marker;
+}
+
+/** Badge tone (`neutral`, or a Jira statusCategory key like `done`) -> one of four. Unknown is neutral, never an error. */
+function toneOf(tone) {
+    const t = str(tone).toLowerCase();
+    if (['positive', 'success', 'good', 'done', 'green', 'complete', 'completed'].includes(t)) return 'positive';
+    if (['warning', 'caution', 'indeterminate', 'yellow', 'in_progress', 'pending'].includes(t)) return 'warning';
+    if (['critical', 'danger', 'error', 'bad', 'red', 'failed'].includes(t)) return 'critical';
+    return 'neutral';
+}
+
+const ACTION_VALUE_MAX = 2000; // Slack's cap on a button's value
+
+/**
+ * A userAction button's identity as a Slack button value: which installation, which workflow, which surface it was on.
+ * `needsInput` marks a button whose workflow asks for values first (a Slack button cannot, so the handler opens a form).
+ */
+function encodeAction({ integrationId, workflow, surface, needsInput }) {
+    const value = JSON.stringify({ ...(integrationId ? { integrationId: String(integrationId) } : {}), workflow, surface, ...(needsInput ? { needsInput: true } : {}) });
+    return value.length <= ACTION_VALUE_MAX ? value : null;
+}
+
+/** The inverse, for the handler that receives a click. null for anything that is not one of ours. */
+function decodeAction(value) {
+    let v;
+    try { v = JSON.parse(value); } catch (_) { return null; }
+    if (!v || typeof v !== 'object' || typeof v.workflow !== 'string' || !v.workflow || typeof v.surface !== 'string') return null;
+    if (v.integrationId !== undefined && typeof v.integrationId !== 'string') return null;
+    return { ...(v.integrationId ? { integrationId: v.integrationId } : {}), workflow: v.workflow, surface: v.surface, ...(v.needsInput ? { needsInput: true } : {}) };
+}
+
+module.exports = { str, safeUrl, truncate, toneOf, encodeAction, decodeAction, ACTION_VALUE_MAX };