@pipedream/form_io 0.0.3 → 0.1.0

package/actions/list-forms/list-forms.mjs

@@ -0,0 +1,79 @@
+import formIo from "../../form_io.app.mjs";
+import { pluckFields } from "../../common/utils.mjs";
+
+export default {
+  key: "form_io-list-forms",
+  name: "List Forms",
+  description: "List forms and resources in the Form.io project. Optionally filter by `type` to return only forms or only resources. Form.io returns up to `limit` records (default 10); if you receive a full page there may be more — raise `limit` (up to 1000) or page with `skip` to retrieve them all. Forms are large; pass `fields` to return only the fields you need (e.g. `_id`, `title`, `name`, `path`). [See the documentation](https://apidocs.form.io/#40baaaa1-c309-4f81-a546-6821cec14701).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    formIo,
+    type: {
+      propDefinition: [
+        formIo,
+        "type",
+      ],
+      description: "Filter by form type. One of `form` or `resource`. Omit to return both.",
+    },
+    limit: {
+      propDefinition: [
+        formIo,
+        "limit",
+      ],
+    },
+    skip: {
+      propDefinition: [
+        formIo,
+        "skip",
+      ],
+    },
+    sort: {
+      propDefinition: [
+        formIo,
+        "sort",
+      ],
+    },
+    fields: {
+      propDefinition: [
+        formIo,
+        "fields",
+      ],
+      description: "Optional. Return only these top-level fields from each form (e.g. `_id`, `title`, `name`, `path`, `type`). Omit to return the full form objects, which include the large `components` and `access` arrays.",
+    },
+  },
+  async run({ $ }) {
+    const {
+      type,
+      limit,
+      skip,
+      sort,
+      fields,
+    } = this;
+
+    const response = await this.formIo.listForms({
+      $,
+      params: {
+        type,
+        limit,
+        skip,
+        sort,
+      },
+    });
+
+    const forms = Array.isArray(response)
+      ? response
+      : response?.data ?? [];
+
+    $.export("$summary", `Retrieved ${forms.length} form(s)`);
+    return fields?.length
+      ? pluckFields(forms, fields)
+      : response;
+  },
+};

package/actions/list-roles/list-roles.mjs

@@ -0,0 +1,59 @@
+import formIo from "../../form_io.app.mjs";
+
+export default {
+  key: "form_io-list-roles",
+  name: "List Roles",
+  description: "List all roles in the Form.io project, including the built-in Administrator, Authenticated, and Anonymous roles. Form.io returns up to `limit` records (default 10); if you receive a full page there may be more — raise `limit` (up to 1000) or page with `skip` to retrieve them all. [See the documentation](https://apidocs.form.io/#8ecd0673-9088-4157-ae0d-161f93d090fb).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    formIo,
+    limit: {
+      propDefinition: [
+        formIo,
+        "limit",
+      ],
+    },
+    skip: {
+      propDefinition: [
+        formIo,
+        "skip",
+      ],
+    },
+    sort: {
+      propDefinition: [
+        formIo,
+        "sort",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const {
+      limit,
+      skip,
+      sort,
+    } = this;
+
+    const response = await this.formIo.listRoles({
+      $,
+      params: {
+        limit,
+        skip,
+        sort,
+      },
+    });
+
+    const roles = Array.isArray(response)
+      ? response
+      : response?.data ?? [];
+
+    $.export("$summary", `Retrieved ${roles.length} role(s)`);
+    return response;
+  },
+};

package/actions/list-submissions/list-submissions.mjs

@@ -0,0 +1,87 @@
+import formIo from "../../form_io.app.mjs";
+import { pluckFields } from "../../common/utils.mjs";
+
+export default {
+  key: "form_io-list-submissions",
+  name: "List Submissions",
+  description: "List submissions for a Form.io form. Optionally filter by state. Use **List Forms** to find the form ID. Form.io returns up to `limit` records (default 10); if you receive a full page there may be more — raise `limit` (up to 1000) or page with `skip` to retrieve them all. Pass `fields` to return only the fields you need (e.g. `_id`, `data`, `created`). [See the documentation](https://apidocs.form.io/#1f207caa-9d04-3e81-2973-e4bf82ee5190).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    formIo,
+    formId: {
+      propDefinition: [
+        formIo,
+        "formId",
+      ],
+    },
+    state: {
+      propDefinition: [
+        formIo,
+        "state",
+      ],
+      description: "Filter by submission state. One of `submitted` or `draft`.",
+    },
+    sort: {
+      propDefinition: [
+        formIo,
+        "sort",
+      ],
+    },
+    limit: {
+      propDefinition: [
+        formIo,
+        "limit",
+      ],
+    },
+    skip: {
+      propDefinition: [
+        formIo,
+        "skip",
+      ],
+    },
+    fields: {
+      propDefinition: [
+        formIo,
+        "fields",
+      ],
+      description: "Optional. Return only these top-level fields from each submission (e.g. `_id`, `data`, `created`, `state`). Omit to return the full submission objects, which include access and metadata envelopes.",
+    },
+  },
+  async run({ $ }) {
+    const {
+      formId,
+      state,
+      sort,
+      limit,
+      skip,
+      fields,
+    } = this;
+
+    const response = await this.formIo.listSubmissions({
+      $,
+      formId,
+      params: {
+        state,
+        sort,
+        limit,
+        skip,
+      },
+    });
+
+    const submissions = Array.isArray(response)
+      ? response
+      : response?.data ?? [];
+
+    $.export("$summary", `Retrieved ${submissions.length} submission(s)`);
+    return fields?.length
+      ? pluckFields(submissions, fields)
+      : response;
+  },
+};

package/actions/update-form/update-form.mjs

@@ -0,0 +1,113 @@
+import formIo from "../../form_io.app.mjs";
+import { parseJson } from "../../common/utils.mjs";
+
+export default {
+  key: "form_io-update-form",
+  name: "Update Form",
+  description: "Update a form or resource in Form.io. Only the fields you provide are changed; omitted fields keep their current values. Use **List Forms** to find the form ID. The `components` prop is a JSON-string array of Form.io component schema objects. [See the documentation](https://apidocs.form.io/#9faa123a-3183-4513-9ae5-c64553359749).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    formIo,
+    formId: {
+      propDefinition: [
+        formIo,
+        "formId",
+      ],
+    },
+    title: {
+      propDefinition: [
+        formIo,
+        "title",
+      ],
+      description: "Updated title of the form.",
+      optional: true,
+    },
+    name: {
+      propDefinition: [
+        formIo,
+        "name",
+      ],
+      description: "Updated machine name of the form.",
+      optional: true,
+    },
+    path: {
+      propDefinition: [
+        formIo,
+        "path",
+      ],
+      description: "Updated URL path for the form.",
+      optional: true,
+    },
+    type: {
+      propDefinition: [
+        formIo,
+        "type",
+      ],
+    },
+    components: {
+      propDefinition: [
+        formIo,
+        "components",
+      ],
+      description: "JSON-string array of Form.io component schema objects. Example: `[{\"type\":\"textfield\",\"key\":\"name\",\"label\":\"Full Name\",\"input\":true}]`. Parsed from a JSON string before sending.",
+      optional: true,
+    },
+    display: {
+      propDefinition: [
+        formIo,
+        "display",
+      ],
+    },
+    tags: {
+      propDefinition: [
+        formIo,
+        "tags",
+      ],
+    },
+    settings: {
+      propDefinition: [
+        formIo,
+        "settings",
+      ],
+      description: "JSON-string object of form settings. Example: `{\"theme\":\"default\"}`.",
+    },
+  },
+  async run({ $ }) {
+    const {
+      formId,
+      title,
+      name,
+      path,
+      type,
+      components,
+      display,
+      tags,
+      settings,
+    } = this;
+
+    const response = await this.formIo.updateForm({
+      $,
+      formId,
+      data: {
+        title,
+        name,
+        path,
+        type,
+        components: parseJson(components, "components", "array"),
+        display,
+        tags,
+        settings: parseJson(settings, "settings", "object"),
+      },
+    });
+
+    $.export("$summary", `Updated form "${response.title}" (${response._id})`);
+    return response;
+  },
+};

package/actions/update-form-action/update-form-action.mjs

@@ -0,0 +1,93 @@
+import formIo from "../../form_io.app.mjs";
+import { parseJson } from "../../common/utils.mjs";
+
+export default {
+  key: "form_io-update-form-action",
+  name: "Update Form Action",
+  description: "Update an action attached to a Form.io form. Only the fields you provide are changed; omitted fields keep their current values. Use **List Form Actions** to find the action ID. The `settings` prop is a JSON-string object specific to the action type. [See the documentation](https://apidocs.form.io/#2b553c0c-f857-4bfc-8023-1ddd0fc216e9).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    formIo,
+    formId: {
+      propDefinition: [
+        formIo,
+        "formId",
+      ],
+    },
+    actionId: {
+      propDefinition: [
+        formIo,
+        "actionId",
+      ],
+    },
+    title: {
+      propDefinition: [
+        formIo,
+        "title",
+      ],
+      description: "Updated title of the action.",
+      optional: true,
+    },
+    handler: {
+      propDefinition: [
+        formIo,
+        "handler",
+      ],
+      optional: true,
+    },
+    method: {
+      propDefinition: [
+        formIo,
+        "method",
+      ],
+      optional: true,
+    },
+    priority: {
+      propDefinition: [
+        formIo,
+        "priority",
+      ],
+    },
+    settings: {
+      propDefinition: [
+        formIo,
+        "settings",
+      ],
+      description: "JSON-string object of action-specific settings; the shape depends on the action type. Example (webhook action): `{\"method\":\"post\",\"url\":\"https://example.com/webhook\"}`. Parsed with JSON.parse() before sending.",
+    },
+  },
+  async run({ $ }) {
+    const {
+      formId,
+      actionId,
+      title,
+      handler,
+      method,
+      priority,
+      settings,
+    } = this;
+
+    const response = await this.formIo.updateFormAction({
+      $,
+      formId,
+      actionId,
+      data: {
+        title,
+        handler,
+        method,
+        priority,
+        settings: parseJson(settings, "settings", "object"),
+      },
+    });
+
+    $.export("$summary", `Updated form action "${response.title}" (${response._id})`);
+    return response;
+  },
+};

package/actions/update-role/update-role.mjs

@@ -0,0 +1,76 @@
+import { ConfigurationError } from "@pipedream/platform";
+import formIo from "../../form_io.app.mjs";
+
+export default {
+  key: "form_io-update-role",
+  name: "Update Role",
+  description: "Update a role in the Form.io project. Only the fields you provide are changed; omitted fields keep their current values. Obtain the role ID from **List Roles** (it is the role's 24-character hex `_id`, e.g. `64f8a1b2c3d4e5f60718293a`). Example: for `roleId` `64f8a1b2c3d4e5f60718293a`, set description to `Read-only reviewer` → returns the updated role. [See the documentation](https://apidocs.form.io/#6ad0536d-1927-41c5-b406-956ac736f9e5).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    formIo,
+    roleId: {
+      propDefinition: [
+        formIo,
+        "roleId",
+      ],
+    },
+    title: {
+      propDefinition: [
+        formIo,
+        "title",
+      ],
+      description: "Updated title of the role.",
+      optional: true,
+    },
+    description: {
+      propDefinition: [
+        formIo,
+        "description",
+      ],
+      description: "Updated description of the role.",
+    },
+  },
+  async run({ $ }) {
+    const {
+      roleId,
+      title,
+      description,
+    } = this;
+
+    // Send only the fields the user actually provided. Form.io's role PUT merges
+    // the request body onto the existing document server-side (omitted fields keep
+    // their current values), so we deliberately do NOT read-modify-write a full
+    // snapshot: reading the whole role and PUTting it back would overwrite any
+    // field a concurrent update changed in between (a lost update). By writing only
+    // the changed fields, two concurrent updates to different fields both survive.
+    const data = {};
+    if (title !== undefined) {
+      data.title = title;
+    }
+    if (description !== undefined) {
+      data.description = description;
+    }
+
+    if (!Object.keys(data).length) {
+      throw new ConfigurationError(
+        "Provide at least one field to update (Title and/or Description).",
+      );
+    }
+
+    const response = await this.formIo.updateRole({
+      $,
+      roleId,
+      data,
+    });
+
+    $.export("$summary", `Updated role "${response.title}" (${response._id})`);
+    return response;
+  },
+};

package/actions/update-submission/update-submission.mjs

@@ -0,0 +1,64 @@
+import formIo from "../../form_io.app.mjs";
+import { parseJson } from "../../common/utils.mjs";
+
+export default {
+  key: "form_io-update-submission",
+  name: "Update Submission",
+  description: "Update a submission for a Form.io form. Only the fields you provide are changed; omitted fields keep their current values. Use **List Submissions** to find the submission ID. The `data` prop is a JSON-string object of field key-value pairs. [See the documentation](https://apidocs.form.io/#fa874508-bff1-1047-a504-d3831576df00).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    formIo,
+    formId: {
+      propDefinition: [
+        formIo,
+        "formId",
+      ],
+    },
+    submissionId: {
+      propDefinition: [
+        formIo,
+        "submissionId",
+      ],
+    },
+    data: {
+      propDefinition: [
+        formIo,
+        "data",
+      ],
+    },
+    state: {
+      propDefinition: [
+        formIo,
+        "state",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const {
+      formId,
+      submissionId,
+      data,
+      state,
+    } = this;
+
+    const response = await this.formIo.updateSubmission({
+      $,
+      formId,
+      submissionId,
+      data: {
+        data: parseJson(data, "data", "object"),
+        state,
+      },
+    });
+
+    $.export("$summary", `Updated submission ${response._id}`);
+    return response;
+  },
+};

package/common/constants.mjs

@@ -0,0 +1,24 @@
+// Form.io project API Keys authenticate via the `x-token` header.
+// (`x-jwt-token` is only for short-lived login JWTs, which expire in minutes.)
+export const API_KEY_HEADER = "x-token";
+export const FORM_TYPES = [
+  "form",
+  "resource",
+];
+export const SUBMISSION_STATES = [
+  "submitted",
+  "draft",
+];
+export const ACTION_HANDLERS = [
+  "before",
+  "after",
+];
+export const ACTION_METHODS = [
+  "create",
+  "update",
+  "read",
+  "delete",
+  "index",
+];
+export const LIMIT_MIN = 1;
+export const LIMIT_MAX = 1000;

package/common/utils.mjs

@@ -0,0 +1,75 @@
+import { ConfigurationError } from "@pipedream/platform";
+
+/**
+ * Parse a JSON-string prop into a JS value, optionally validating its shape.
+ *
+ * MCP/agent-facing props like `components`, `settings`, and `data` arrive as JSON strings.
+ * This centralizes the parsing so every action reports the same clear, prop-named error on
+ * malformed input (a raw `JSON.parse` throws a bare `SyntaxError` with no prop context).
+ *
+ * - Returns `undefined` for empty input (null / undefined / ""), so optional props can be
+ *   passed straight through without a caller-side ternary.
+ * - Passes an already-parsed object/array through unchanged (defensive).
+ * - When `expect` is `"object"` or `"array"`, the parsed value must match that shape, so a
+ *   valid-JSON-but-wrong-shape value (e.g. an array where the API wants an object) fails here
+ *   with a prop-named message instead of as an opaque 400 from the API.
+ *
+ * @param {string|object|null|undefined} value - the raw prop value
+ * @param {string} propLabel - the prop name, used in the error message
+ * @param {"object"|"array"} [expect] - required shape of the parsed value
+ * @returns {*} the parsed value, or `undefined` when `value` is empty
+ * @throws {ConfigurationError} when `value` is not valid JSON, or does not match `expect`
+ */
+export function parseJson(value, propLabel = "value", expect) {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+  let parsed;
+  if (typeof value === "object") {
+    parsed = value;
+  } else {
+    try {
+      parsed = JSON.parse(value);
+    } catch (err) {
+      throw new ConfigurationError(
+        `The \`${propLabel}\` prop must be a valid JSON string. ${err.message}`,
+      );
+    }
+  }
+  if (expect === "object"
+    && (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))) {
+    throw new ConfigurationError(
+      `The \`${propLabel}\` prop must be a JSON object (e.g. \`{ ... }\`).`,
+    );
+  }
+  if (expect === "array" && !Array.isArray(parsed)) {
+    throw new ConfigurationError(
+      `The \`${propLabel}\` prop must be a JSON array (e.g. \`[ { ... } ]\`).`,
+    );
+  }
+  return parsed;
+}
+
+/**
+ * Reduce each record in an array to only the named top-level fields.
+ *
+ * Optional response-shaping for list actions that return large objects (Form.io forms carry
+ * big `components`/`access` arrays). When `fields` is empty/undefined the records are returned
+ * unchanged, so this is always additive — omitting the `fields` prop reproduces the raw output.
+ *
+ * @param {Array} records - the array of record objects
+ * @param {string[]|undefined} fields - top-level field names to keep
+ * @returns {Array} the records, each narrowed to `fields` (or unchanged when `fields` is empty)
+ */
+export function pluckFields(records, fields) {
+  if (!Array.isArray(records) || !fields?.length) {
+    return records;
+  }
+  return records.map((r) => (
+    r && typeof r === "object" && !Array.isArray(r)
+      ? Object.fromEntries(Object.entries(r).filter(([
+        k,
+      ]) => fields.includes(k)))
+      : r
+  ));
+}