@agnocon/piece-bigcommerce 0.1.11

package/src/lib/actions/find-or-create-customers-address.ts

@@ -0,0 +1,101 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bigcommerceAuth } from '../common/auth';
+import { customerDropdown } from '../common/props';
+import { bigCommerceApiService } from '../common/requests';
+
+export const findOrCreateCustomersAddress = createAction({
+  auth: bigcommerceAuth,
+  name: 'findOrCreateCustomersAddress',
+  displayName: 'Find or Create Customer’s Address',
+  description: 'Finds or creates a customer’s address',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'For a given customer_id, looks up that customer’s addresses and returns the one matching the supplied address line 1, city, and postal code if it exists, otherwise creates a new address from the supplied details. Use instead of Create Customer Address when the address may already be on file, to avoid duplicates. Idempotent: repeated calls reuse the matching address rather than appending duplicates.',
+    idempotent: true,
+  },
+  props: {
+    customer_id: customerDropdown({
+      required: true,
+    }),
+    first_name: Property.ShortText({
+      displayName: 'First Name',
+      required: true,
+    }),
+    last_name: Property.ShortText({
+      displayName: 'Last Name',
+      required: true,
+    }),
+    address1: Property.ShortText({
+      displayName: 'Address Line 1',
+      required: true,
+    }),
+    address2: Property.ShortText({
+      displayName: 'Address Line 2',
+      required: false,
+    }),
+    city: Property.ShortText({
+      displayName: 'City',
+      required: true,
+    }),
+    state_or_province: Property.ShortText({
+      displayName: 'State/Province',
+      required: true,
+    }),
+    postal_code: Property.ShortText({
+      displayName: 'Postal Code',
+      required: true,
+    }),
+    country_code: Property.ShortText({
+      displayName: 'Country Code',
+      description: 'ISO 3166-1 alpha-2 country code',
+      required: true,
+    }),
+    phone: Property.ShortText({
+      displayName: 'Phone',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const params = new URLSearchParams();
+    params.append('customer_id:in', context.propsValue.customer_id as string);
+
+    const response = await bigCommerceApiService.fetchCustomerAddresses({
+      auth: context.auth.props,
+      queryString: params.toString(),
+    });
+
+    if (response.data && response.data.length > 0) {
+      const existingAddress = response.data.find(
+        (addr: any) =>
+          addr.address1 === context.propsValue.address1 &&
+          addr.city === context.propsValue.city &&
+          addr.postal_code === context.propsValue.postal_code
+      );
+
+      if (existingAddress) {
+        return { found: true, data: existingAddress };
+      }
+    }
+
+    const newAddress = await bigCommerceApiService.createCustomerAddress({
+      auth: context.auth.props,
+      payload: [
+        {
+          customer_id: context.propsValue.customer_id,
+          first_name: context.propsValue.first_name,
+          last_name: context.propsValue.last_name,
+          address1: context.propsValue.address1,
+          address2: context.propsValue.address2,
+          city: context.propsValue.city,
+          state_or_province: context.propsValue.state_or_province,
+          postal_code: context.propsValue.postal_code,
+          country_code: context.propsValue.country_code,
+          phone: context.propsValue.phone,
+        },
+      ],
+    });
+
+    return { found: false, data: newAddress.data };
+  },
+});

package/src/lib/actions/find-or-create-product.ts

@@ -0,0 +1,81 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bigcommerceAuth } from '../common/auth';
+import { bigCommerceApiService } from '../common/requests';
+
+export const findOrCreateProduct = createAction({
+  auth: bigcommerceAuth,
+  name: 'findOrCreateProduct',
+  displayName: 'Find or Create Product',
+  description: 'Finds or creates a product',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'Looks up a catalog product by exact name and returns the match if found, otherwise creates a new product from the supplied details (type, weight, and price required). Use instead of Create a Product when the item may already exist, to avoid duplicates. Idempotent: repeated calls match the same existing product by name rather than creating duplicates.',
+    idempotent: true,
+  },
+  props: {
+    name: Property.ShortText({
+      displayName: 'Product Name',
+      required: true,
+    }),
+    sku: Property.ShortText({
+      displayName: 'SKU',
+      required: false,
+    }),
+    type: Property.StaticDropdown({
+      displayName: 'Product Type',
+      required: true,
+      options: {
+        options: [
+          { label: 'Physical', value: 'physical' },
+          { label: 'Digital', value: 'digital' },
+        ],
+      },
+    }),
+    weight: Property.Number({
+      displayName: 'Weight',
+      required: true,
+    }),
+    price: Property.Number({
+      displayName: 'Price',
+      required: true,
+    }),
+    description: Property.LongText({
+      displayName: 'Description',
+      required: false,
+    }),
+    brand_id: Property.Number({
+      displayName: 'Brand ID',
+      description: 'Brand ID',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const params = new URLSearchParams();
+    params.append('name', context.propsValue.name);
+
+    const response = await bigCommerceApiService.fetchProducts({
+      auth: context.auth.props,
+      queryString: params.toString(),
+    });
+
+    if (response.data && response.data.length > 0) {
+      return { found: true, data: response.data };
+    }
+
+    const newProduct = await bigCommerceApiService.createProduct({
+      auth: context.auth.props,
+      payload: {
+        name: context.propsValue.name,
+        type: context.propsValue.type,
+        sku: context.propsValue.sku,
+        description: context.propsValue.description,
+        weight: context.propsValue.weight,
+        price: context.propsValue.price,
+        brand_id: context.propsValue.brand_id,
+      },
+    });
+
+    return { found: false, data: newProduct.data };
+  },
+});

package/src/lib/actions/get-order.ts

@@ -0,0 +1,29 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bigcommerceAuth } from '../common/auth';
+import { bigCommerceApiService } from '../common/requests';
+
+export const getOrder = createAction({
+  auth: bigcommerceAuth,
+  name: 'getOrder',
+  displayName: 'Get Order',
+  description: 'Gets details of an order',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'Retrieves the full details of a single BigCommerce order by its orderId. Use when you already have an order id (e.g. from an order trigger or List Orders) and need its data. Idempotent read-only lookup with no side effects.',
+    idempotent: true,
+  },
+  props: {
+    orderId: Property.ShortText({
+      displayName: 'Order ID',
+      description: 'The ID of the order to retrieve',
+      required: true,
+    }),
+  },
+  async run(context) {
+    return await bigCommerceApiService.fetchOrder({
+      auth: context.auth.props,
+      orderId: context.propsValue.orderId,
+    });
+  },
+});

package/src/lib/actions/list-categories.ts

@@ -0,0 +1,31 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bigcommerceAuth } from '../common/auth';
+import { bigCommerceApiService } from '../common/requests';
+
+export const listCategories = createAction({
+  auth: bigcommerceAuth,
+  name: 'listCategories',
+  displayName: 'List Categories',
+  description: 'Lists all categories',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'Lists product categories from a BigCommerce store. With no name filter it returns all categories; provide a name to filter to matching categories. Use to discover category names or ids before assigning products. Idempotent read-only query with no side effects.',
+    idempotent: true,
+  },
+  props: {
+    name: Property.ShortText({
+      displayName: 'Category Name',
+      description: 'Filter by category name',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const qParams = new URLSearchParams();
+    if (context.propsValue.name) qParams.append('name', context.propsValue.name);
+    return await bigCommerceApiService.fetchCategories({
+      auth: context.auth.props,
+      queryString: qParams.toString(),
+    });
+  },
+});

package/src/lib/actions/list-orders.ts

@@ -0,0 +1,38 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bigcommerceAuth } from '../common/auth';
+import { bigCommerceApiService } from '../common/requests';
+
+export const listOrders = createAction({
+  auth: bigcommerceAuth,
+  name: 'listOrders',
+  displayName: 'List Orders',
+  description: 'Lists all orders',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'Lists orders from a BigCommerce store. With no filters it returns all orders; optionally narrow by customer_id and/or status_id to a subset. Use to browse or find orders when you do not have a specific order id. Idempotent read-only query with no side effects.',
+    idempotent: true,
+  },
+  props: {
+    customer_id: Property.Number({
+      displayName: 'Customer ID',
+      description: 'Filter by customer ID',
+      required: false,
+    }),
+    status_id: Property.Number({
+      displayName: 'Status ID',
+      description: 'Filter by status ID',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const qParams = new URLSearchParams();
+    if (context.propsValue.customer_id !== undefined && context.propsValue.customer_id !== null) qParams.append('customer_id', context.propsValue.customer_id.toString());
+    if (context.propsValue.status_id !== undefined && context.propsValue.status_id !== null) qParams.append('status_id', context.propsValue.status_id.toString());
+    
+    return await bigCommerceApiService.fetchOrders({
+      auth: context.auth.props,
+      queryString: qParams.toString(),
+    });
+  },
+});

package/src/lib/actions/search-customer-address.ts

@@ -0,0 +1,42 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bigCommerceApiService } from '../common/requests';
+import { bigcommerceAuth } from '../common/auth';
+import { multiCustomerDropdown } from '../common/props';
+
+export const searchCustomerAddress = createAction({
+  auth: bigcommerceAuth,
+  name: 'searchCustomerAddress',
+  displayName: 'Search Customer Address',
+  description: 'Searches for a customer’s address',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'Searches customer addresses in a BigCommerce store, optionally filtered by one or more customer ids and/or a name. With no filters it returns all addresses; supplying filters narrows to matches. Use to look up addresses belonging to specific customers. Idempotent read-only query with no side effects.',
+    idempotent: true,
+  },
+  props: {
+    customer_ids: multiCustomerDropdown({
+      required: false,
+    }),
+    name: Property.ShortText({
+      displayName: 'Name',
+      description: 'Customer name to search for',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const params = new URLSearchParams();
+    if (context.propsValue.customer_ids)
+      params.append(
+        'customer_ids:in',
+        (context.propsValue.customer_ids as string[]).join(',')
+      );
+    if (context.propsValue.name)
+      params.append('name:in', `${context.propsValue.name}`);
+
+    return await bigCommerceApiService.fetchCustomerAddresses({
+      auth: context.auth.props,
+      queryString: params.toString(),
+    });
+  },
+});

package/src/lib/actions/search-customer.ts

@@ -0,0 +1,47 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bigcommerceAuth } from '../common/auth';
+import { bigCommerceApiService } from '../common/requests';
+
+export const searchCustomer = createAction({
+  auth: bigcommerceAuth,
+  name: 'searchCustomer',
+  displayName: 'Search Customer',
+  description: 'Searches for a registered customer',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'Searches registered customers in a BigCommerce store by email, phone, and/or name. With no filters it returns all customers; supplying any filter narrows to matches. Use to look up a customer or check whether one exists before creating it. Idempotent read-only query with no side effects.',
+    idempotent: true,
+  },
+  props: {
+    email: Property.ShortText({
+      displayName: 'Email',
+      description: 'Customer email to search for',
+      required: false,
+    }),
+    phone: Property.ShortText({
+      displayName: 'Phone Number',
+      description: 'Phone Number to search for',
+      required: false,
+    }),
+    name: Property.ShortText({
+      displayName: 'Name',
+      description: 'Customer name to search for',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const params = new URLSearchParams();
+    if (context.propsValue.email)
+      params.append('email:in', context.propsValue.email);
+    if (context.propsValue.name)
+      params.append('name:in', `${context.propsValue.name}`);
+    if (context.propsValue.phone)
+      params.append('phone:in', context.propsValue.phone);
+
+    return await bigCommerceApiService.fetchCustomers({
+      auth: context.auth.props,
+      queryString: params.toString(),
+    });
+  },
+});

package/src/lib/actions/search-product.ts

@@ -0,0 +1,69 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bigcommerceAuth } from '../common/auth';
+import { bigCommerceApiService } from '../common/requests';
+
+export const searchProduct = createAction({
+  auth: bigcommerceAuth,
+  name: 'searchProduct',
+  displayName: 'Search Product',
+  description: 'Searches for a product in the catalog',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'Searches the BigCommerce product catalog by name, SKU, type, brand, weight, and/or price. With no filters it returns all products; supplying any filter narrows to matches. Use to find a product or its id, or to check whether one exists before creating it. Idempotent read-only query with no side effects.',
+    idempotent: true,
+  },
+  props: {
+    name: Property.ShortText({
+      displayName: 'Product Name',
+      description: 'Product name to search for',
+      required: false,
+    }),
+    sku: Property.ShortText({
+      displayName: 'SKU',
+      description: 'Product SKU to search for',
+      required: false,
+    }),
+    type: Property.StaticDropdown({
+      displayName: 'Product Type',
+      required: false,
+      options: {
+        options: [
+          { label: 'Physical', value: 'physical' },
+          { label: 'Digital', value: 'digital' },
+        ],
+      },
+    }),
+    brand_id: Property.ShortText({
+      displayName: 'Brand ID',
+      description: 'Brand ID to search for',
+      required: false,
+    }),
+    weight: Property.Number({
+      displayName: 'Weight',
+      required: false,
+    }),
+    price: Property.Number({
+      displayName: 'Price',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const params = new URLSearchParams();
+    if (context.propsValue.name) params.append('name', context.propsValue.name);
+    if (context.propsValue.sku) params.append('sku', context.propsValue.sku);
+    if (context.propsValue.brand_id)
+      params.append('brand_id', context.propsValue.brand_id);
+    if (context.propsValue.type)
+      params.append('type', context.propsValue.type);
+    if (context.propsValue.price)
+      params.append('price', String(context.propsValue.price));
+    if (context.propsValue.weight)
+      params.append('weight', String(context.propsValue.weight));
+
+    return await bigCommerceApiService.fetchProducts({
+      auth: context.auth.props,
+      queryString: params.toString(),
+    });
+  },
+});

package/src/lib/actions/update-a-product.ts

@@ -0,0 +1,78 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { bigcommerceAuth } from '../common/auth';
+import { bigCommerceApiService } from '../common/requests';
+
+export const updateAProduct = createAction({
+  auth: bigcommerceAuth,
+  name: 'updateAProduct',
+  displayName: 'Update a Product',
+  description: 'Updates an existing Product',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'Updates an existing catalog product in a BigCommerce store, identified by its productId. Only the fields you supply are sent (null/undefined values are dropped so existing data is preserved), so use it for partial edits to name, type, SKU, description, weight, price, or brand. Idempotent: re-applying the same field values leaves the product in the same state.',
+    idempotent: true,
+  },
+  props: {
+    productId: Property.ShortText({
+      displayName: 'Product ID',
+      description: 'The ID of the product to update',
+      required: true,
+    }),
+    name: Property.ShortText({
+      displayName: 'Product Name',
+      description: 'Name of the product',
+      required: false,
+    }),
+    type: Property.StaticDropdown({
+      displayName: 'Product Type',
+      description: 'Type of product',
+      required: false,
+      options: {
+        options: [
+          { label: 'Physical', value: 'physical' },
+          { label: 'Digital', value: 'digital' },
+        ],
+      },
+    }),
+    sku: Property.ShortText({
+      displayName: 'SKU',
+      description: 'Product SKU',
+      required: false,
+    }),
+    description: Property.LongText({
+      displayName: 'Description',
+      description: 'Product description',
+      required: false,
+    }),
+    weight: Property.Number({
+      displayName: 'Weight',
+      description: 'Product weight',
+      required: false,
+    }),
+    price: Property.Number({
+      displayName: 'Price',
+      description: 'Product price',
+      required: false,
+    }),
+    brand_id: Property.Number({
+      displayName: 'Brand ID',
+      description: 'Brand ID',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const { productId, ...payload } = context.propsValue;
+
+    // Filter out null/undefined values to prevent overwriting existing data with nulls
+    const filteredPayload = Object.fromEntries(
+      Object.entries(payload).filter(([_, v]) => v !== null && v !== undefined)
+    );
+
+    return await bigCommerceApiService.updateProduct({
+      auth: context.auth.props,
+      productId,
+      payload: filteredPayload,
+    });
+  },
+});

package/src/lib/common/auth.ts

@@ -0,0 +1,44 @@
+import { PieceAuth, Property } from '@agnocon/pieces-framework';
+import { bigCommerceApiService } from './requests';
+
+export const bigcommerceAuth = PieceAuth.CustomAuth({
+  description:
+    'Enter your BigCommerce API credentials. ',
+
+  props: {
+    instruction: Property.MarkDown({
+      value: `1. Login to https://www.bigcommerce.com/essentials/
+2. Go to Settings
+3. Scroll down to API
+4. Click on "Store Level API Accounts"
+5. Click "Create API Account" button
+6. Enter a name and add required scopes
+7. Save - you will get a downloaded file containing your access token and store hash`,
+    }),
+    storeHash: Property.ShortText({
+      displayName: 'Store Hash',
+      description: 'Your BigCommerce store hash (e.g., abcd1234)',
+      required: true,
+    }),
+    accessToken: Property.ShortText({
+      displayName: 'Access Token',
+      description: 'Your BigCommerce API access token',
+      required: true,
+    }),
+  },
+  required: true,
+  async validate(context) {
+    try {
+      await bigCommerceApiService.fetchProducts({
+        auth: context.auth,
+      });
+      return { valid: true };
+    } catch {
+      return {
+        valid: false,
+        error:
+          'Could not validate credentials. please check your credentials are correct.',
+      };
+    }
+  },
+});

package/src/lib/common/constants.ts

@@ -0,0 +1,15 @@
+export type bigCommerceAuth = {
+    storeHash: string;
+    accessToken: string;
+}
+
+export const GET_BASE_URL = (storeHash: string) =>
+  `https://api.bigcommerce.com/stores/${storeHash}`;
+
+export function handleDropdownError(msg: string) {
+  return {
+    disabled: true,
+    options: [],
+    placeholder: msg,
+  };
+}

package/src/lib/common/props.ts

@@ -0,0 +1,90 @@
+import { Property } from '@agnocon/pieces-framework';
+import { handleDropdownError } from './constants';
+import { bigCommerceApiService } from './requests';
+import { bigcommerceAuth } from './auth';
+
+export const customerDropdown = ({ required }: { required: boolean }) =>
+  Property.Dropdown({
+    auth: bigcommerceAuth,
+    displayName: 'Customer',
+    description: 'Select the customer',
+    required,
+    refreshers: ['auth'],
+    options: async ({ auth }) => {
+      if (!auth)
+        return handleDropdownError('Please connect your account first');
+
+      try {
+        const response = await bigCommerceApiService.fetchCustomers({ auth: auth.props });
+
+        const data = Array.isArray(response?.data) ? response.data : [];
+        if (data.length === 0) {
+          return handleDropdownError('No customers found');
+        }
+
+        const options = data.map((user: any) => {
+          const fullName =
+            [user.first_name, user.last_name]
+              .filter((p: any) => typeof p === 'string' && p.trim() !== '')
+              .join(' ') ||
+            user.email ||
+            user.id;
+
+          return {
+            label: fullName,
+            value: user.id,
+          };
+        });
+
+        return {
+          disabled: false,
+          options,
+        };
+      } catch (error) {
+        return handleDropdownError('Failed to load customers');
+      }
+    },
+  });
+
+export const multiCustomerDropdown = ({ required }: { required: boolean }) =>
+  Property.MultiSelectDropdown({
+    auth: bigcommerceAuth,
+    displayName: 'Customers',
+    description: 'Select the customers',
+    required,
+    refreshers: ['auth'],
+    options: async ({ auth }) => {
+      if (!auth)
+        return handleDropdownError('Please connect your account first');
+
+      try {
+        const response = await bigCommerceApiService.fetchCustomers({ auth: auth.props });
+
+        const data = Array.isArray(response?.data) ? response.data : [];
+        if (data.length === 0) {
+          return handleDropdownError('No customers found');
+        }
+
+        const options = data.map((user: any) => {
+          const fullName =
+            [user.first_name, user.last_name]
+              .filter((p: any) => typeof p === 'string' && p.trim() !== '')
+              .join(' ') ||
+            user.email ||
+            user.id;
+
+          return {
+            label: fullName,
+            value: user.id,
+          };
+        });
+
+        return {
+          disabled: false,
+          options,
+        };
+      } catch (error) {
+        return handleDropdownError('Failed to load customers');
+      }
+    },
+  });