@friggframework/core 2.0.0--canary.703.12b980b.0 → 2.0.0--canary.707.df80bfd.0

package/integrations/definitions/config-form.js

@@ -1,137 +0,0 @@
-/**
- * The configure form for an installation, generated from its definition: what GET_CONFIG_OPTIONS and
- * REFRESH_CONFIG_OPTIONS return on Frigg's existing, authenticated /api/integrations/:id/config/options routes.
- *
- * The form's data has exactly the shape of Integration.config, so what the management UI PATCHes back is the config:
- *   { settings: { … }, syncs: { <id>: { enabled } }, workflows: { <id>: { enabled, settings: { … } } }, ui: { <id>: { enabled } } }
- *
- * Option settings become enums filled by `options(path, values)` (resolveOptions underneath). A list whose inputs are
- * not chosen yet comes back empty with a help line saying what to choose first; REFRESH_CONFIG_OPTIONS, called with
- * the form's current values, fills it.
- */
-const SETTING_SCHEMA = {
-    string: () => ({ type: 'string' }),
-    text: () => ({ type: 'string' }),
-    number: () => ({ type: 'number' }),
-    boolean: () => ({ type: 'boolean' }),
-    duration: () => ({ type: 'string', pattern: '^\\d+(m|h|d)$' }),
-    enum: (s) => ({ type: 'string', enum: s.enum }),
-};
-
-const dependsOn = (s) => (s && typeof s.options === 'object' ? Object.values(s.options.with || {}).map((v) => String(v).replace(/^\$\.(settings|install)\./, '')) : []);
-
-async function settingsSchema(settings, pathPrefix, values, options, integrationSettings) {
-    const properties = {}, ui = {}, required = [];
-    for (const [key, s] of Object.entries(settings || {})) {
-        let schema;
-        if (s.type === 'option') {
-            const choices = await options(`${pathPrefix}.${key}`, values, integrationSettings);
-            schema = choices.length
-                ? { type: 'string', oneOf: choices.map((c) => ({ const: String(c.value), title: c.label })) }
-                : { type: 'string', enum: [] };
-            if (!choices.length && dependsOn(s).length) ui[key] = { 'ui:help': `Choose ${dependsOn(s).join(' and ')} first.` };
-        } else schema = (SETTING_SCHEMA[s.type] || SETTING_SCHEMA.string)(s);
-        properties[key] = { ...schema, title: s.label, ...(s.default !== undefined ? { default: s.default } : {}) };
-        if (s.help) ui[key] = { ...(ui[key] || {}), 'ui:help': s.help };
-        if (s.required && s.default === undefined) required.push(key);
-    }
-    return { schema: { type: 'object', properties, ...(required.length ? { required } : {}) }, ui };
-}
-
-/**
- * The timing field of a schedule the definition marks configurable: an interval when its default is an interval,
- * a cron (with time zone) when its default is a cron. The floor is said in the help text and enforced on save.
- */
-function scheduleField(recurrence, configurable) {
-    if (!configurable || !recurrence) return null;
-    const min = configurable.min ? ` No more often than every ${configurable.min}.` : '';
-    if (recurrence.every !== undefined) {
-        return { schema: { type: 'object', title: 'Schedule', properties: { every: { type: 'string', title: 'Runs every', pattern: '^\\d+\\s*(m|h|d)$', default: recurrence.every } } }, ui: { every: { 'ui:help': `Minutes, hours or days: 15m, 2h, 1d.${min}` } } };
-    }
-    return { schema: { type: 'object', title: 'Schedule', properties: { cron: { type: 'string', title: 'Cron', default: recurrence.cron }, timezone: { type: 'string', title: 'Time zone', default: recurrence.timezone || 'UTC' } } }, ui: { cron: { 'ui:help': `minute hour day-of-month month day-of-week.${min}` } } };
-}
-const configurableOf = (c) => (c ? (c === true ? {} : c) : false);
-
-const toggle = (title, description, enabledByDefault) => ({ type: 'boolean', title, ...(description ? { description } : {}), default: enabledByDefault });
-const isOn = (item, chosen) => (typeof chosen?.enabled === 'boolean' ? chosen.enabled : (item.default || 'on') === 'on');
-
-/**
- * @param {object} def
- * @param {object} config        the installation's current config (or the form's current values on refresh)
- * @param {(path: string, values: object, integrationSettings: object) => Promise<Array<{label,value}>>} options
- * @returns {Promise<{ jsonSchema: object, uiSchema: object, data: object }>}
- */
-async function buildConfigForm(def, config = {}, options = async () => []) {
-    const jsonSchema = { type: 'object', title: def.display?.label, properties: {} };
-    const uiSchema = {};
-    const data = { settings: { ...(config.settings || {}) }, syncs: {}, workflows: {}, ui: {} };
-
-    if (Object.keys(def.settings || {}).length) {
-        const s = await settingsSchema(def.settings, 'settings', config.settings || {}, options, config.settings || {});
-        jsonSchema.properties.settings = { title: 'Settings', ...s.schema };
-        uiSchema.settings = s.ui;
-    }
-
-    if ((def.syncs || []).length) {
-        jsonSchema.properties.syncs = { type: 'object', title: 'Syncs', properties: {} };
-        for (const s of def.syncs) {
-            jsonSchema.properties.syncs.properties[s.id] = { type: 'object', title: s.label, properties: { enabled: toggle('On', s.description, (s.default || 'on') === 'on') } };
-            data.syncs[s.id] = { enabled: isOn(s, config.syncs?.[s.id]) };
-            const field = s.ongoing?.mode === 'poll' && scheduleField({ every: s.ongoing.every || '15m' }, configurableOf(s.ongoing.configurable));
-            if (field) {
-                jsonSchema.properties.syncs.properties[s.id].properties.schedule = field.schema;
-                ((uiSchema.syncs ||= {})[s.id] ||= {}).schedule = field.ui;
-                if (config.syncs?.[s.id]?.schedule) data.syncs[s.id].schedule = { ...config.syncs[s.id].schedule };
-            }
-        }
-    }
-
-    if ((def.workflows || []).length) {
-        jsonSchema.properties.workflows = { type: 'object', title: 'Workflows', properties: {} };
-        uiSchema.workflows = {};
-        for (const w of def.workflows) {
-            const chosen = config.workflows?.[w.id] || {};
-            const node = { type: 'object', title: w.label, properties: { enabled: toggle('On', w.description, (w.default || 'on') === 'on') } };
-            data.workflows[w.id] = { enabled: isOn(w, chosen), settings: { ...(chosen.settings || {}) } };
-            if (Object.keys(w.settings || {}).length) {
-                // A workflow setting's option inputs may read integration settings, which it sees as $.install.
-                const s = await settingsSchema(w.settings, `workflows.${w.id}.settings`, chosen.settings || {}, options, config.settings || {});
-                node.properties.settings = { title: 'Settings', ...s.schema };
-                uiSchema.workflows[w.id] = { settings: s.ui };
-                // Settings only matter while the workflow is on: required only then.
-                node.dependencies = { enabled: { oneOf: [{ properties: { enabled: { const: false } } }, { properties: { enabled: { const: true } }, required: ['settings'] }] } };
-            }
-            const t = w.trigger || {};
-            const field = t.type === 'schedule' && scheduleField(t.every !== undefined ? { every: t.every } : { cron: t.cron, timezone: t.timezone }, configurableOf(t.configurable));
-            if (field) {
-                node.properties.schedule = field.schema;
-                (uiSchema.workflows[w.id] ||= {}).schedule = field.ui;
-                if (chosen.schedule) data.workflows[w.id].schedule = { ...chosen.schedule };
-            }
-            jsonSchema.properties.workflows.properties[w.id] = node;
-        }
-    }
-
-    if ((def.ui || []).length) {
-        jsonSchema.properties.ui = { type: 'object', title: 'Cards and panels', properties: {} };
-        for (const u of def.ui) {
-            jsonSchema.properties.ui.properties[u.id] = { type: 'object', title: u.label || u.id, properties: { enabled: toggle('Show', `${u.host} · ${u.placement}`, (u.default || 'on') === 'on') } };
-            data.ui[u.id] = { enabled: isOn(u, config.ui?.[u.id]) };
-        }
-    }
-
-    return { jsonSchema, uiSchema, data };
-}
-
-/** Is anything required still missing? (NEEDS_CONFIG) */
-function missingRequired(def, config = {}) {
-    const missing = [];
-    for (const [k, s] of Object.entries(def.settings || {})) if (s.required && s.default === undefined && (config.settings?.[k] == null || config.settings[k] === '')) missing.push(`settings.${k}`);
-    for (const w of def.workflows || []) {
-        if (!isOn(w, config.workflows?.[w.id])) continue;
-        for (const [k, s] of Object.entries(w.settings || {})) if (s.required && s.default === undefined && (config.workflows?.[w.id]?.settings?.[k] == null || config.workflows[w.id].settings[k] === '')) missing.push(`workflows.${w.id}.settings.${k}`);
-    }
-    return missing;
-}
-
-module.exports = { buildConfigForm, missingRequired };

package/integrations/definitions/examples/acme-erp-quickbooks.definition.json

@@ -1,467 +0,0 @@
-{
-  "$schema": "https://friggframework.org/schemas/integration-definition/v0.1.json",
-  "schemaVersion": "0.1",
-  "id": "acme-erp-quickbooks",
-  "version": "1.3.0",
-  "display": {
-    "label": "Acme ERP \u2194 QuickBooks Online",
-    "description": "Finished jobs become QuickBooks invoices with every line item, customers stay matched both ways, and payments recorded in QuickBooks mark the job paid in Acme ERP.",
-    "category": "Accounting",
-    "tags": [
-      "field-service",
-      "invoicing",
-      "accounting"
-    ]
-  },
-  "modules": {
-    "acmeerp": {
-      "module": "acmeerp",
-      "version": "^0.9"
-    },
-    "quickbooks": {
-      "module": "quickbooks",
-      "version": "^2.0"
-    }
-  },
-  "settings": {
-    "fallbackItem": {
-      "type": "option",
-      "options": "quickbooks.item",
-      "label": "Product/service for line items with no matching QuickBooks item",
-      "required": true
-    },
-    "terms": {
-      "type": "enum",
-      "label": "Invoice terms",
-      "enum": [
-        "Due on receipt",
-        "Net 15",
-        "Net 30"
-      ],
-      "default": "Due on receipt"
-    }
-  },
-  "syncs": [
-    {
-      "id": "customers",
-      "label": "Customers",
-      "description": "One customer in both systems. Contact details follow whichever side changed last; QuickBooks owns the billing name.",
-      "source": "acmeerp.customer",
-      "target": "quickbooks.customer",
-      "direction": "two_way",
-      "identity": {
-        "match": [
-          {
-            "source": "email",
-            "target": "PrimaryEmailAddr.Address",
-            "transform": "lowercase",
-            "key": "email"
-          },
-          {
-            "source": "mobile_number",
-            "target": "Mobile.FreeFormNumber",
-            "transform": "to_e164_phone",
-            "key": "phone"
-          }
-        ],
-        "onAmbiguous": "skip"
-      },
-      "mapping": [
-        {
-          "source": "display_name",
-          "target": "DisplayName",
-          "master": "target"
-        },
-        {
-          "source": "first_name",
-          "target": "GivenName",
-          "master": "newest"
-        },
-        {
-          "source": "last_name",
-          "target": "FamilyName",
-          "master": "newest"
-        },
-        {
-          "source": "company_name",
-          "target": "CompanyName",
-          "master": "newest"
-        },
-        {
-          "source": "email",
-          "target": "PrimaryEmailAddr.Address",
-          "transform": "lowercase",
-          "master": "newest"
-        },
-        {
-          "source": "mobile_number",
-          "target": "Mobile.FreeFormNumber",
-          "transform": "to_e164_phone",
-          "master": "newest"
-        },
-        {
-          "source": "address.street",
-          "target": "BillAddr.Line1",
-          "master": "source"
-        },
-        {
-          "source": "address.city",
-          "target": "BillAddr.City",
-          "master": "source"
-        },
-        {
-          "source": "address.state",
-          "target": "BillAddr.CountrySubDivisionCode",
-          "master": "source"
-        },
-        {
-          "source": "address.zip",
-          "target": "BillAddr.PostalCode",
-          "master": "source"
-        }
-      ],
-      "backfill": {
-        "trigger": "userAction",
-        "pageSize": 100
-      },
-      "ongoing": {
-        "mode": "webhook"
-      },
-      "default": "on"
-    }
-  ],
-  "workflows": [
-    {
-      "id": "job-invoice",
-      "label": "Invoice finished jobs",
-      "purpose": "write",
-      "default": "on",
-      "settings": {
-        "emailInvoice": {
-          "type": "boolean",
-          "label": "Email the invoice from QuickBooks",
-          "default": false
-        }
-      },
-      "trigger": {
-        "type": "webhook",
-        "module": "acmeerp",
-        "topic": "job.finished",
-        "filter": "$.record.total_amount > 0 && $.record.external_invoice_id == null"
-      },
-      "steps": [
-        {
-          "id": "customer",
-          "use": "links.find",
-          "with": {
-            "sync": "customers",
-            "from": "acmeerp",
-            "id": "$.record.customer_id"
-          }
-        },
-        {
-          "use": "stop",
-          "when": "$.steps.customer == null",
-          "with": {
-            "reason": "Customer is not in QuickBooks yet; the queue will retry after the customer sync"
-          }
-        },
-        {
-          "id": "lineItems",
-          "use": "acmeerp.job.lineItems",
-          "with": {
-            "jobId": "$.record.id"
-          }
-        },
-        {
-          "id": "lines",
-          "use": "code",
-          "with": {
-            "ref": "@acme/frigg-steps#quickbooksInvoiceLines@1.0.0",
-            "with": {
-              "lineItems": "$.steps.lineItems",
-              "fallbackItemId": "$.install.fallbackItem",
-              "taxAmount": "$.record.tax_amount"
-            }
-          }
-        },
-        {
-          "id": "memo",
-          "use": "template",
-          "with": {
-            "id": "invoice-memo"
-          }
-        },
-        {
-          "id": "invoice",
-          "use": "quickbooks.invoice.create",
-          "with": {
-            "invoice": {
-              "CustomerRef": {
-                "value": "$.steps.customer.quickbooks"
-              },
-              "DocNumber": "TW-{{record.job_number}}",
-              "TxnDate": "$.record.finished_at",
-              "SalesTermRef": {
-                "name": "$.install.terms"
-              },
-              "CustomerMemo": {
-                "value": "$.steps.memo"
-              },
-              "PrivateNote": "Acme ERP job {{record.id}}",
-              "Line": "$.steps.lines.lines"
-            }
-          }
-        },
-        {
-          "use": "acmeerp.job.update",
-          "with": {
-            "id": "$.record.id",
-            "job": {
-              "status": "invoiced",
-              "external_invoice_id": "$.steps.invoice.Id"
-            }
-          }
-        },
-        {
-          "use": "quickbooks.invoice.send",
-          "when": "$.settings.emailInvoice == true",
-          "with": {
-            "id": "$.steps.invoice.Id"
-          },
-          "onError": "continue"
-        }
-      ],
-      "retry": {
-        "max": 5,
-        "backoff": "exponential"
-      }
-    },
-    {
-      "id": "invoice-paid",
-      "label": "Mark jobs paid when QuickBooks records a payment",
-      "purpose": "write",
-      "default": "on",
-      "trigger": {
-        "type": "webhook",
-        "module": "quickbooks",
-        "topic": "payment.created"
-      },
-      "steps": [
-        {
-          "id": "payment",
-          "use": "quickbooks.payment.get",
-          "with": {
-            "id": "$.record.id"
-          }
-        },
-        {
-          "id": "apply",
-          "use": "foreach",
-          "with": {
-            "over": "$.steps.payment.Line",
-            "max": 20
-          },
-          "do": [
-            {
-              "id": "jobs",
-              "use": "acmeerp.job.search",
-              "when": "$.item.LinkedTxn[0].TxnType == 'Invoice'",
-              "with": {
-                "external_invoice_id": "$.item.LinkedTxn[0].TxnId"
-              }
-            },
-            {
-              "use": "acmeerp.job.markPaid",
-              "when": "$.steps.jobs[0] exists",
-              "with": {
-                "id": "$.steps.jobs[0].id",
-                "amount": "{{item.Amount | to_cents}}",
-                "paid_at": "$.steps.payment.TxnDate",
-                "method": "quickbooks",
-                "reference": "QBO payment {{steps.payment.Id}}"
-              }
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "id": "invoice-note",
-      "label": "Note the invoice on the job",
-      "purpose": "write",
-      "default": "off",
-      "trigger": {
-        "type": "syncRecord",
-        "sync": "customers",
-        "on": [
-          "linked"
-        ]
-      },
-      "steps": [
-        {
-          "id": "open",
-          "use": "acmeerp.job.search",
-          "with": {
-            "customer_id": "$.record.id"
-          }
-        },
-        {
-          "id": "notes",
-          "use": "foreach",
-          "with": {
-            "over": "$.steps.open",
-            "max": 25
-          },
-          "do": [
-            {
-              "use": "acmeerp.job.addNote",
-              "when": "$.item.status == 'finished'",
-              "with": {
-                "jobId": "$.item.id",
-                "body": "Customer is now linked to QuickBooks; finished jobs will be invoiced automatically."
-              }
-            }
-          ]
-        }
-      ]
-    }
-  ],
-  "queries": [
-    {
-      "id": "job-invoice-status",
-      "description": "The QuickBooks invoice for this job.",
-      "steps": [
-        {
-          "use": "stop",
-          "when": "$.record.external_invoice_id == null",
-          "with": {
-            "reason": "Not invoiced"
-          }
-        },
-        {
-          "id": "invoice",
-          "use": "quickbooks.invoice.get",
-          "with": {
-            "id": "$.record.external_invoice_id"
-          }
-        }
-      ],
-      "returns": {
-        "invoice": "$.steps.invoice",
-        "realmId": "$.install.accounts.quickbooks.realmId"
-      }
-    }
-  ],
-  "ui": [
-    {
-      "id": "invoice-panel",
-      "label": "QuickBooks invoice",
-      "host": "acmeerp",
-      "placement": "job.sidebar",
-      "objects": [
-        "job"
-      ],
-      "data": {
-        "query": "job-invoice-status"
-      },
-      "view": {
-        "component": "Stack",
-        "children": [
-          {
-            "component": "Heading",
-            "props": {
-              "text": "QuickBooks"
-            }
-          },
-          {
-            "component": "Empty",
-            "when": "!($.data.invoice exists)",
-            "props": {
-              "text": "Invoiced automatically when the job is finished."
-            }
-          },
-          {
-            "component": "KeyValue",
-            "when": "$.data.invoice exists",
-            "props": {
-              "items": [
-                {
-                  "label": "Invoice",
-                  "value": "{{data.invoice.DocNumber}}"
-                },
-                {
-                  "label": "Total",
-                  "value": "${{data.invoice.TotalAmt}}"
-                },
-                {
-                  "label": "Balance",
-                  "value": "${{data.invoice.Balance}}"
-                },
-                {
-                  "label": "Due",
-                  "value": "{{data.invoice.DueDate | date}}"
-                }
-              ]
-            }
-          },
-          {
-            "component": "Badge",
-            "when": "$.data.invoice.Balance == 0",
-            "props": {
-              "text": "Paid",
-              "tone": "success"
-            }
-          },
-          {
-            "component": "Badge",
-            "when": "$.data.invoice.Balance > 0",
-            "props": {
-              "text": "Open",
-              "tone": "warning"
-            }
-          },
-          {
-            "component": "Button",
-            "when": "$.data.invoice exists",
-            "props": {
-              "label": "Open in QuickBooks",
-              "action": {
-                "type": "open_url",
-                "url": "https://app.qbo.intuit.com/app/invoice?txnId={{data.invoice.Id}}"
-              }
-            }
-          }
-        ]
-      }
-    }
-  ],
-  "templates": {
-    "invoice-memo": "Thanks for choosing Acme! Job #{{record.job_number}}: {{record.description | truncate: 200}}"
-  },
-  "lifecycle": {
-    "onInstall": [
-      {
-        "id": "hook",
-        "use": "acmeerp.webhook.create",
-        "with": {
-          "url": "$.install.webhookUrls.acmeerp",
-          "events": [
-            "job.finished",
-            "job.scheduled",
-            "customer.created",
-            "customer.updated"
-          ]
-        }
-      }
-    ],
-    "onUninstall": [
-      {
-        "use": "acmeerp.webhook.delete",
-        "with": {
-          "id": "$.install.runtime.installed.hook.id"
-        }
-      }
-    ]
-  }
-}