@pipedream/sperse 0.0.1 → 0.2.0

package/actions/add-or-update-contact/add-or-update-contact.mjs

@@ -0,0 +1,164 @@
+import app from "../../sperse.app.mjs";
+import { parseArray } from "../../common/utils.mjs";
+
+export default {
+  key: "sperse-add-or-update-contact",
+  name: "Add or Update Contact",
+  description: "Creates or updates a contact. [See the documentation](https://app.sperse.com/app/api/swagger)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    app,
+    // eslint-disable-next-line pipedream/props-label, pipedream/props-description
+    info: {
+      type: "alert",
+      alertType: "info",
+      content: "At least one of the following fields is required: **First Name** or **Last Name**, **Company**, **Email** or **Phone**",
+    },
+    contactId: {
+      description: "The ID of the contact to update. Leave empty to create a new contact.",
+      optional: true,
+      propDefinition: [
+        app,
+        "contactId",
+      ],
+    },
+    contactGroupId: {
+      propDefinition: [
+        app,
+        "contactGroupId",
+      ],
+    },
+    firstName: {
+      type: "string",
+      label: "First Name",
+      description: "The first name of the contact",
+      optional: true,
+    },
+    lastName: {
+      type: "string",
+      label: "Last Name",
+      description: "The last name of the contact",
+      optional: true,
+    },
+    companyName: {
+      type: "string",
+      label: "Company Name",
+      description: "The company name of the contact",
+      optional: true,
+    },
+    emailAddresses: {
+      type: "string[]",
+      label: "Email Addresses",
+      description: `An array of email objects.
+
+**Example:**
+\`\`\`json
+[
+  {
+    "emailAddress": "jane.doe@gmail.com",
+    "isActive": true,
+    "isConfirmed": true,
+    "comment": "Primary work email",
+    "usageTypeId": "H"
+  }
+]
+\`\`\``,
+      optional: true,
+    },
+    phoneNumbers: {
+      type: "string[]",
+      label: "Phone Numbers",
+      description: `An array of phone objects.
+
+**Example:**
+\`\`\`json
+[
+  {
+    "phoneNumber": "+14155552671",
+    "phoneExtension": "101",
+    "isActive": true,
+    "isConfirmed": false,
+    "comment": "Direct work line",
+    "usageTypeId": "C"
+  }
+]
+\`\`\``,
+      optional: true,
+    },
+    addresses: {
+      type: "string[]",
+      label: "Addresses",
+      description: `Array of address objects.
+
+**Example:**
+\`\`\`json
+[
+  {
+    "contactId": 12345,
+    "startDate": "2026-02-13",
+    "endDate": "2026-02-13",
+    "isActive": true,
+    "isConfirmed": true,
+    "usageTypeId": "H",
+    "ownershipTypeId": "O",
+    "streetAddress": "123 Main St",
+    "neighborhood": "Main St",
+    "city": "New York",
+    "stateId": "NY",
+    "stateName": "New York",
+    "zip": "10001",
+    "countryId": "US",
+    "countryName": "United States",
+    "comment": "Home address"
+  }
+]
+\`\`\``,
+      optional: true,
+    },
+    note: {
+      type: "string",
+      label: "Note",
+      description: "Additional notes about the contact",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const {
+      app,
+      contactId,
+      contactGroupId,
+      firstName,
+      lastName,
+      companyName,
+      emailAddresses,
+      phoneNumbers,
+      addresses,
+      note,
+    } = this;
+
+    const response = await app.createOrUpdateContact({
+      $,
+      data: {
+        contactId,
+        contactGroupId,
+        firstName,
+        lastName,
+        companyName,
+        emailAddresses: parseArray(emailAddresses),
+        phoneNumbers: parseArray(phoneNumbers),
+        addresses: parseArray(addresses),
+        note,
+      },
+    });
+
+    $.export("$summary", `Successfully created/updated contact with ID \`${response.result?.contactId ?? "unknown"}\``);
+
+    return response;
+  },
+};

package/actions/create-invoice/create-invoice.mjs

@@ -0,0 +1,141 @@
+import app from "../../sperse.app.mjs";
+import { parseArray } from "../../common/utils.mjs";
+import constants from "../../common/constants.mjs";
+
+export default {
+  key: "sperse-create-invoice",
+  name: "Create Invoice",
+  description: "Creates a new invoice in Sperse. [See the documentation](https://app.sperse.com/app/api/swagger)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    app,
+    contactId: {
+      propDefinition: [
+        app,
+        "contactId",
+      ],
+    },
+    status: {
+      type: "string",
+      label: "Status",
+      description: "The status of the invoice",
+      options: constants.INVOICE_STATUS,
+    },
+    date: {
+      type: "string",
+      label: "Invoice Date",
+      description: "The date of the invoice in ISO 8601 format (e.g., `2026-02-16`)",
+    },
+    currencyId: {
+      propDefinition: [
+        app,
+        "currencyId",
+      ],
+    },
+    grandTotal: {
+      type: "string",
+      label: "Grand Total",
+      description: "The grand total amount",
+    },
+    lines: {
+      type: "string[]",
+      label: "Invoice Lines",
+      description: `An array of invoice line items. Either priceOptionId or unitId should be specified, productCode or description should be specified. [See the documentation](https://app.sperse.com/app/api/swagger)
+  
+**Example:**
+\`\`\`json
+[
+  {
+    "productCode": "123",
+    "unitId": "Day",
+    "quantity": 1,
+    "rate": 100,
+    "total": 100,
+    "sortOrder": 1
+  }
+]
+\`\`\``,
+    },
+    dueDate: {
+      type: "string",
+      label: "Due Date",
+      description: "The due date of the invoice in ISO 8601 format (e.g., `2026-10-15`)",
+      optional: true,
+    },
+    description: {
+      type: "string",
+      label: "Description",
+      description: "The description of the invoice",
+      optional: true,
+    },
+    note: {
+      type: "string",
+      label: "Note",
+      description: "Additional notes for the invoice",
+      optional: true,
+    },
+    taxTotal: {
+      type: "string",
+      label: "Tax Total",
+      description: "The total tax amount",
+      optional: true,
+    },
+    discountTotal: {
+      type: "string",
+      label: "Discount Total",
+      description: "The total discount amount",
+      optional: true,
+    },
+    shippingTotal: {
+      type: "string",
+      label: "Shipping Total",
+      description: "The total shipping cost",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const {
+      app,
+      contactId,
+      currencyId,
+      grandTotal,
+      lines,
+      date,
+      dueDate,
+      description,
+      note,
+      status,
+      taxTotal,
+      discountTotal,
+      shippingTotal,
+    } = this;
+
+    const response = await app.createInvoice({
+      $,
+      data: {
+        contactId,
+        currencyId,
+        grandTotal,
+        lines: parseArray(lines),
+        date,
+        dueDate,
+        description,
+        note,
+        status,
+        taxTotal,
+        discountTotal,
+        shippingTotal,
+      },
+    });
+
+    $.export("$summary", "Successfully created invoice.");
+
+    return response;
+  },
+};

package/actions/create-product/create-product.mjs

@@ -0,0 +1,141 @@
+import app from "../../sperse.app.mjs";
+import { parseArray } from "../../common/utils.mjs";
+import constants from "../../common/constants.mjs";
+
+export default {
+  key: "sperse-create-product",
+  name: "Create Product",
+  description: "Creates a new product. [See the documentation](https://app.sperse.com/app/api/swagger)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    app,
+    // eslint-disable-next-line pipedream/props-label, pipedream/props-description
+    info: {
+      type: "alert",
+      alertType: "info",
+      content: "At least one **Price Option** should be specified for the product",
+    },
+    name: {
+      type: "string",
+      label: "Name",
+      description: "The name of the product",
+    },
+    code: {
+      type: "string",
+      label: "Product Code",
+      description: "The product code",
+    },
+    productType: {
+      type: "string",
+      label: "Product Type",
+      description: "The type of the product",
+      options: constants.PRODUCT_TYPES,
+    },
+    currencyId: {
+      propDefinition: [
+        app,
+        "currencyId",
+      ],
+    },
+    priceOptions: {
+      type: "string[]",
+      label: "Price Options",
+      description: `An array of price option objects. [See the documentation](https://app.sperse.com/app/api/swagger)
+
+**Example:**
+\`\`\`json
+[
+  {
+    "type": "Subscription",
+    "frequency": "OneTime",
+    "fee": 0,
+    "customerChoosesPrice": false,
+    "credits": 100,
+    "trialDayCount": 0,
+    "customPeriodCount": 14,
+    "customPeriodType": "Days"
+  }
+]
+\`\`\``,
+    },
+    description: {
+      type: "string",
+      label: "Description",
+      description: "The description of the product",
+      optional: true,
+    },
+    descriptionHtml: {
+      type: "string",
+      label: "Description HTML",
+      description: "The HTML description of the product",
+      optional: true,
+    },
+    barCode: {
+      type: "string",
+      label: "Bar Code",
+      description: "The product barcode",
+      optional: true,
+    },
+    isPublished: {
+      type: "boolean",
+      label: "Is Published",
+      description: "Whether the product is published",
+      optional: true,
+    },
+    publishDate: {
+      type: "string",
+      label: "Publish Date",
+      description: "The publish date is required if the product is published. Example: `2026-02-16`",
+      optional: true,
+    },
+    groupName: {
+      type: "string",
+      label: "Group Name",
+      description: "The product group name",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const {
+      app,
+      name,
+      code,
+      productType,
+      currencyId,
+      description,
+      descriptionHtml,
+      priceOptions,
+      groupName,
+      barCode,
+      isPublished,
+      publishDate,
+    } = this;
+
+    const response = await app.createProduct({
+      $,
+      data: {
+        name,
+        code,
+        type: productType,
+        currencyId,
+        description,
+        descriptionHtml,
+        barCode,
+        isPublished,
+        priceOptions: parseArray(priceOptions),
+        groupName,
+        publishDate,
+      },
+    });
+
+    $.export("$summary", `Successfully created product with ID \`${response.result.productId}\`.`);
+
+    return response;
+  },
+};

package/actions/get-contact-details/get-contact-details.mjs

@@ -0,0 +1,40 @@
+import app from "../../sperse.app.mjs";
+
+export default {
+  key: "sperse-get-contact-details",
+  name: "Get Contact Details",
+  description: "Retrieves detailed information about a contact. [See the documentation](https://app.sperse.com/app/api/swagger)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    app,
+    contactId: {
+      propDefinition: [
+        app,
+        "contactId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const {
+      app,
+      contactId,
+    } = this;
+
+    const response = await app.getContactDetails({
+      $,
+      params: {
+        contactId,
+      },
+    });
+
+    $.export("$summary", "Successfully retrieved contact details");
+
+    return response;
+  },
+};

package/actions/list-contact-group-id-options/list-contact-group-id-options.mjs

@@ -0,0 +1,24 @@
+import sperse from "../../sperse.app.mjs";
+
+export default {
+  key: "sperse-list-contact-group-id-options",
+  name: "List Contact Group ID Options",
+  description: "Retrieves available options for the Contact Group ID field.",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    sperse,
+  },
+  async run({ $ }) {
+    const options = await sperse.propDefinitions.contactGroupId.options.call(this.sperse);
+    $.export("$summary", `Successfully retrieved ${options.length} option${options.length === 1
+      ? ""
+      : "s"}`);
+    return options;
+  },
+};

package/actions/list-currency-id-options/list-currency-id-options.mjs

@@ -0,0 +1,24 @@
+import sperse from "../../sperse.app.mjs";
+
+export default {
+  key: "sperse-list-currency-id-options",
+  name: "List Currency ID Options",
+  description: "Retrieves available options for the Currency ID field.",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    sperse,
+  },
+  async run({ $ }) {
+    const options = await sperse.propDefinitions.currencyId.options.call(this.sperse);
+    $.export("$summary", `Successfully retrieved ${options.length} option${options.length === 1
+      ? ""
+      : "s"}`);
+    return options;
+  },
+};

package/common/constants.mjs

@@ -0,0 +1,28 @@
+const DEFAULT_MAX = 600;
+const DEFAULT_LIMIT = 100;
+
+const INVOICE_STATUS = [
+  "Draft",
+  "Final",
+  "Sent",
+  "Paid",
+  "Canceled",
+  "PartiallyPaid",
+  "Refunded",
+  "PartiallyRefunded",
+];
+
+const PRODUCT_TYPES = [
+  "General",
+  "Subscription",
+  "Digital",
+  "Event",
+  "Donation",
+];
+
+export default {
+  DEFAULT_MAX,
+  DEFAULT_LIMIT,
+  INVOICE_STATUS,
+  PRODUCT_TYPES,
+};

package/common/utils.mjs

@@ -0,0 +1,37 @@
+export const parseObject = (obj) => {
+  if (!obj) return undefined;
+  if (typeof obj === "string") {
+    return JSON.parse(obj);
+  }
+  return obj;
+};
+
+export const parseArray = (arr) => {
+  if (!arr) return undefined;
+
+  // If it's a string, parse it as JSON
+  if (typeof arr === "string") {
+    return JSON.parse(arr);
+  }
+
+  // If it's already an array
+  if (Array.isArray(arr)) {
+    // Check if first element is a string (needs parsing) or already an object
+    if (arr.length === 0) return arr;
+
+    // If first element is an object, assume the whole array is already parsed
+    if (typeof arr[0] === "object" && arr[0] !== null) {
+      return arr;
+    }
+
+    // If elements are strings, parse each one
+    return arr.map((item) => {
+      if (typeof item === "string") {
+        return JSON.parse(item);
+      }
+      return item;
+    });
+  }
+
+  return arr;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipedream/sperse",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Pipedream Sperse Components",
   "main": "sperse.app.mjs",
   "keywords": [
@@ -11,5 +11,8 @@
   "author": "Pipedream <support@pipedream.com> (https://pipedream.com/)",
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@pipedream/platform": "^3.2.5"
   }
 }

package/sources/common/polling.mjs

@@ -0,0 +1,67 @@
+import app from "../../sperse.app.mjs";
+import {
+  DEFAULT_POLLING_SOURCE_TIMER_INTERVAL,
+  ConfigurationError,
+} from "@pipedream/platform";
+
+export default {
+  props: {
+    app,
+    db: "$.service.db",
+    timer: {
+      type: "$.interface.timer",
+      default: {
+        intervalSeconds: DEFAULT_POLLING_SOURCE_TIMER_INTERVAL,
+      },
+    },
+  },
+  methods: {
+    _getLastId() {
+      return this.db.get("lastId") || 0;
+    },
+    _setLastId(lastId) {
+      this.db.set("lastId", lastId);
+    },
+    generateMeta() {
+      throw new ConfigurationError("generateMeta is not implemented");
+    },
+    getResourceFn() {
+      throw new ConfigurationError("getResourceFn is not implemented");
+    },
+    getResourceFnArgs() {
+      return;
+    },
+  },
+  async run() {
+    const {
+      _getLastId,
+      _setLastId,
+      generateMeta,
+      getResourceFn,
+      getResourceFnArgs,
+    } = this;
+
+    let lastId = _getLastId();
+    let maxId = lastId;
+
+    const resourcesFn = getResourceFn();
+    const { result } = await resourcesFn(getResourceFnArgs());
+
+    const resources = result || [];
+
+    for (const resource of resources.reverse()) {
+      if (resource.id <= lastId) {
+        continue;
+      }
+
+      this.$emit(resource, generateMeta(resource));
+      if (resource.id > maxId) {
+        maxId = resource.id;
+      }
+    }
+
+    if (maxId > lastId) {
+      _setLastId(maxId);
+    }
+  },
+};

package/sources/new-lead/new-lead.mjs

@@ -0,0 +1,32 @@
+import common from "../common/polling.mjs";
+import constants from "../../common/constants.mjs";
+
+export default {
+  ...common,
+  key: "sperse-new-lead",
+  name: "New Lead",
+  description: "Emit new event when a new lead is created. [See the documentation](https://app.sperse.com/app/api/swagger)",
+  version: "0.0.1",
+  type: "source",
+  dedupe: "unique",
+  methods: {
+    ...common.methods,
+    getResourceFn() {
+      return this.app.getLeads;
+    },
+    getResourceFnArgs() {
+      return {
+        params: {
+          TopCount: constants.DEFAULT_MAX,
+        },
+      };
+    },
+    generateMeta(lead) {
+      return {
+        id: lead.id,
+        summary: `New Lead: ${lead.name}`,
+        ts: Date.now(),
+      };
+    },
+  },
+};

package/sources/new-subscription/new-subscription.mjs

@@ -0,0 +1,41 @@
+import app from "../../sperse.app.mjs";
+import common from "../common/polling.mjs";
+
+export default {
+  ...common,
+  key: "sperse-new-subscription",
+  name: "New Subscription",
+  description: "Emit new event when a new subscription is created. [See the documentation](https://app.sperse.com/app/api/swagger)",
+  version: "0.0.1",
+  type: "source",
+  dedupe: "unique",
+  props: {
+    ...common.props,
+    contactId: {
+      propDefinition: [
+        app,
+        "contactId",
+      ],
+    },
+  },
+  methods: {
+    ...common.methods,
+    getResourceFn() {
+      return this.app.getSubscriptionHistory;
+    },
+    getResourceFnArgs() {
+      return {
+        params: {
+          contactId: this.contactId,
+        },
+      };
+    },
+    generateMeta(subscription) {
+      return {
+        id: subscription.id,
+        summary: `New Subscription: ${subscription.productName || subscription.productCode}`,
+        ts: Date.now(),
+      };
+    },
+  },
+};

package/sperse.app.mjs

@@ -1,11 +1,173 @@
+import { axios } from "@pipedream/platform";
+import constants from "./common/constants.mjs";
+
 export default {
   type: "app",
   app: "sperse",
-  propDefinitions: {},
+  propDefinitions: {
+    contactId: {
+      type: "string",
+      label: "Contact ID",
+      description: "The ID of the contact",
+      async options() {
+        const { result } = await this.getContacts({
+          params: {
+            TopCount: constants.DEFAULT_LIMIT,
+          },
+        });
+        return result?.map(({
+          id: value, name, email,
+        }) => ({
+          label: `${name} ${email
+            ? `(${email})`
+            : ""}`.trim(),
+          value,
+        })) || [];
+      },
+    },
+    contactGroupId: {
+      type: "string",
+      label: "Contact Group ID",
+      description: "The ID of the contact group",
+      async options() {
+        const { result } = await this.getContactGroups();
+        return result?.map(({
+          id: value, name: label,
+        }) => ({
+          label,
+          value,
+        })) || [];
+      },
+    },
+    currencyId: {
+      type: "string",
+      label: "Currency ID",
+      description: "The ID of the currency",
+      async options() {
+        const { result } = await this.getCurrencies();
+        return result?.map(({
+          id: value, name: label,
+        }) => ({
+          label,
+          value,
+        })) || [];
+      },
+    },
+    productId: {
+      type: "integer",
+      label: "Product ID",
+      description: "The ID of the product",
+      async options({ page }) {
+        const { result } = await this.getProducts({
+          params: {
+            phrase: "",
+            MaxResultCount: 20,
+            SkipCount: page * 20,
+          },
+        });
+        return result?.items?.map(({
+          id: value, name: label,
+        }) => ({
+          label,
+          value,
+        })) || [];
+      },
+    },
+  },
   methods: {
-    // this.$auth contains connected account data
-    authKeys() {
-      console.log(Object.keys(this.$auth));
+    getUrl(path) {
+      return `https://app.sperse.com${path}`;
+    },
+    getHeaders(headers) {
+      return {
+        "api-key": this.$auth.api_key,
+        "accept": "application/json",
+        ...headers,
+      };
+    },
+    async _makeRequest({
+      $ = this, path, headers, ...opts
+    }) {
+      try {
+        return await axios($, {
+          url: this.getUrl(path),
+          headers: this.getHeaders(headers),
+          ...opts,
+        });
+
+      } catch (error) {
+        throw new Error(JSON.stringify(error.response.data, null, 2));
+      }
+    },
+    async createOrUpdateContact(opts = {}) {
+      return this._makeRequest({
+        method: "POST",
+        path: "/api/services/CRM/Contact/CreateOrUpdateContact",
+        ...opts,
+      });
+    },
+    async getContactDetails(opts = {}) {
+      return this._makeRequest({
+        path: "/api/services/CRM/Contact/GetContactDetails",
+        ...opts,
+      });
+    },
+    async getContacts(opts = {}) {
+      return this._makeRequest({
+        path: "/api/services/CRM/Contact/GetAllByPhrase",
+        ...opts,
+      });
+    },
+    async getContactGroups(opts = {}) {
+      return this._makeRequest({
+        path: "/api/services/CRM/Contact/GetContactGroups",
+        ...opts,
+      });
+    },
+    async createLead(opts = {}) {
+      return this._makeRequest({
+        method: "POST",
+        path: "/api/services/CRM/Lead/Create",
+        ...opts,
+      });
+    },
+    async getLeads(opts = {}) {
+      return this._makeRequest({
+        path: "/api/services/CRM/Lead/GetAllByPhrase",
+        ...opts,
+      });
+    },
+    async createInvoice(opts = {}) {
+      return this._makeRequest({
+        method: "POST",
+        path: "/api/services/CRM/Invoice/Create",
+        ...opts,
+      });
+    },
+    async createProduct(opts = {}) {
+      return this._makeRequest({
+        method: "POST",
+        path: "/api/services/CRM/Product/CreateProduct",
+        ...opts,
+      });
+    },
+    async getProducts(opts = {}) {
+      return this._makeRequest({
+        path: "/api/services/CRM/Product/GetProductsByPhrase",
+        ...opts,
+      });
+    },
+    async getSubscriptionHistory(opts = {}) {
+      return this._makeRequest({
+        path: "/api/services/CRM/OrderSubscription/GetSubscriptionHistory",
+        ...opts,
+      });
+    },
+    async getCurrencies(opts = {}) {
+      return this._makeRequest({
+        path: "/api/services/CRM/Currency/GetCurrencies",
+        ...opts,
+      });
     },
   },
-};
+};