@agnocon/piece-bigcommerce 0.1.11

package/src/lib/common/requests.ts

@@ -0,0 +1,252 @@
+import { HttpMethod, httpClient } from '@agnocon/pieces-common';
+import { bigCommerceAuth, GET_BASE_URL } from './constants';
+
+async function fireHttpRequest({
+  method,
+  path,
+  body,
+  auth,
+  filter = false,
+}: {
+  method: HttpMethod;
+  path: string;
+  auth: bigCommerceAuth;
+  body?: unknown;
+  filter?: boolean;
+}) {
+  const BASE_URL = GET_BASE_URL(auth.storeHash);
+
+  const cleanBody = filter && body ? (Array.isArray(body) 
+    ? body.map(item => filterNulls(item)) 
+    : filterNulls(body)) : body;
+
+
+  return await httpClient
+    .sendRequest({
+      method,
+      url: `${BASE_URL}${path}`,
+      headers: {
+        'X-Auth-Token': auth.accessToken,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      body: cleanBody,
+    })
+    .then((res) => res.body)
+    .catch((err) => {
+      throw new Error(
+        `Error in request to ${path}: ${err.message || JSON.stringify(err)}`
+      );
+    });
+}
+
+export const bigCommerceApiService = {
+  async createWebhook({
+    auth,
+    payload,
+  }: {
+    auth: bigCommerceAuth;
+    payload: {
+      scope: string;
+      destination: string;
+      is_active: boolean;
+    };
+  }) {
+    return await fireHttpRequest({
+      auth,
+      path: '/v3/hooks',
+      method: HttpMethod.POST,
+      body: payload,
+    });
+  },
+  async createCustomer({
+    auth,
+    payload,
+  }: {
+    auth: bigCommerceAuth;
+    payload: unknown;
+  }) {
+    return await fireHttpRequest({
+      auth,
+      path: '/v3/customers',
+      method: HttpMethod.POST,
+      body: payload,
+    });
+  },
+  async fetchCustomers({
+    auth,
+    queryString,
+  }: {
+    auth: bigCommerceAuth;
+    queryString?: string;
+  }) {
+    return await fireHttpRequest({
+      auth,
+      path: `/v3/customers${queryString ? `?${queryString}` : ''}`,
+      method: HttpMethod.GET,
+    });
+  },
+  async fetchCustomerAddresses({
+    auth,
+    queryString,
+  }: {
+    auth: bigCommerceAuth;
+    queryString?: string;
+  }) {
+    return await fireHttpRequest({
+      auth,
+      path: `/v3/customers/addresses${queryString ? `?${queryString}` : ''}`,
+      method: HttpMethod.GET,
+    });
+  },
+  async fetchProducts({
+    auth,
+    queryString,
+  }: {
+    auth: bigCommerceAuth;
+    queryString?: string;
+  }) {
+    return await fireHttpRequest({
+      auth,
+      path: `/v3/catalog/products${queryString ? `?${queryString}` : ''}`,
+      method: HttpMethod.GET,
+    });
+  },
+  async createProduct({
+    auth,
+    payload,
+  }: {
+    auth: bigCommerceAuth;
+    payload: unknown;
+  }) {
+    return await fireHttpRequest({
+      auth,
+      path: '/v3/catalog/products',
+      method: HttpMethod.POST,
+      body: payload,
+      filter: true,
+    });
+  },
+  async updateProduct({
+    auth,
+    productId,
+    payload,
+  }: {
+    auth: bigCommerceAuth;
+    productId: string | number;
+    payload: unknown;
+  }) {
+    return await fireHttpRequest({
+      auth,
+      path: `/v3/catalog/products/${productId}`,
+      method: HttpMethod.PUT,
+      body: payload,
+      filter: true,
+    });
+  },
+  async deleteProduct({
+    auth,
+    productId,
+  }: {
+    auth: bigCommerceAuth;
+    productId: string | number;
+  }) {
+    return await fireHttpRequest({
+      auth,
+      path: `/v3/catalog/products/${productId}`,
+      method: HttpMethod.DELETE,
+    });
+  },
+  async fetchOrders({
+    auth,
+    queryString,
+  }: {
+    auth: bigCommerceAuth;
+    queryString?: string;
+  }) {
+    return await fireHttpRequest({
+      auth,
+      path: `/v2/orders${queryString ? `?${queryString}` : ''}`,
+      method: HttpMethod.GET,
+    });
+  },
+  async fetchOrder({
+    auth,
+    orderId,
+  }: {
+    auth: bigCommerceAuth;
+    orderId: string | number;
+  }) {
+    return await fireHttpRequest({
+      auth,
+      path: `/v2/orders/${orderId}`,
+      method: HttpMethod.GET,
+    });
+  },
+  async fetchCategories({
+    auth,
+    queryString,
+  }: {
+    auth: bigCommerceAuth;
+    queryString?: string;
+  }) {
+    return await fireHttpRequest({
+      auth,
+      path: `/v3/catalog/categories${queryString ? `?${queryString}` : ''}`,
+      method: HttpMethod.GET,
+    });
+  },
+  async createBlogPost({
+    auth,
+    payload,
+  }: {
+    auth: bigCommerceAuth;
+    payload: unknown;
+  }) {
+    return await fireHttpRequest({
+      auth,
+      path: '/v2/blog/posts',
+      method: HttpMethod.POST,
+      body: payload,
+    });
+  },
+  async createCustomerAddress({
+    auth,
+    payload,
+  }: {
+    auth: bigCommerceAuth;
+    payload: unknown;
+  }) {
+    return await fireHttpRequest({
+      auth,
+      path: '/v3/customers/addresses',
+      method: HttpMethod.POST,
+      body: payload,
+    });
+  },
+  async deleteWebhook({
+    auth,
+    webhookId,
+  }: {
+    auth: bigCommerceAuth;
+    webhookId: string;
+  }) {
+    return await fireHttpRequest({
+      auth,
+      path: `/v3/hooks/${webhookId}`,
+      method: HttpMethod.DELETE,
+    });
+  },
+};
+
+function filterNulls(obj: unknown): unknown {
+  if (obj === null || obj === undefined) return undefined;
+  if (typeof obj !== 'object') return obj;
+  if (Array.isArray(obj)) return obj.map(filterNulls);
+
+  return Object.fromEntries(
+    Object.entries(obj as Record<string, unknown>)
+      .filter(([_, v]) => v !== null && v !== undefined)
+      .map(([k, v]) => [k, filterNulls(v)])
+  );
+}

package/src/lib/triggers/abandoned-cart.ts

@@ -0,0 +1,58 @@
+import { createTrigger, TriggerStrategy } from '@agnocon/pieces-framework';
+import { bigcommerceAuth } from '../common/auth';
+import { bigCommerceApiService } from '../common/requests';
+
+const TRIGGER_NAME = 'abandoned cart';
+const CACHE_KEY = `${TRIGGER_NAME}-trigger-store-key`;
+const TRIGGER_SCOPE = 'store/cart/abandoned';
+
+export const abandonedCart = createTrigger({
+  auth: bigcommerceAuth,
+  name: 'abandonedCart',
+  displayName: 'Abandoned Cart',
+  description: 'Triggers when a cart is abandoned',
+  aiMetadata: {
+    description:
+      'Fires when a shopper abandons a cart in the BigCommerce store (the cart sits inactive without checkout completing). The event identifies the affected cart; use it to drive abandoned-cart recovery flows.',
+  },
+  props: {},
+  sampleData:{
+    producer: 'stores/dxqdddcaklwsso',
+    hash: '3610addd127e330084ddddd7ddd09b78abfd1a85',
+    created_at: 1761809622,
+    store_id: '1003425529',
+    scope: 'store/cart/abandoned',
+    data: {
+      type: 'cart',
+      id: 'ss-598f-4c95-813b-0ess950562770d',
+    },
+  },
+  type: TriggerStrategy.WEBHOOK,
+  async onEnable(context) {
+    const webhook = await bigCommerceApiService.createWebhook({
+      auth: context.auth.props,
+      payload: {
+        scope: TRIGGER_SCOPE,
+        destination: context.webhookUrl,
+        is_active: true,
+      },
+    });
+
+    await context.store.put(CACHE_KEY, webhook.data.id);
+  },
+  async onDisable(context) {
+    const webhookId = await context.store.get(CACHE_KEY) as string;
+
+    if (webhookId) {
+      await bigCommerceApiService.deleteWebhook({
+        auth: context.auth.props,
+        webhookId,  
+      }).then(async () => {
+        await context.store.delete(CACHE_KEY)
+      })
+    }
+  },
+  async run(context) {
+    return [context.payload.body];
+  },
+});

package/src/lib/triggers/cart-created.ts

@@ -0,0 +1,60 @@
+import { createTrigger, TriggerStrategy } from '@agnocon/pieces-framework';
+import { bigcommerceAuth } from '../common/auth';
+import { bigCommerceApiService } from '../common/requests';
+
+const TRIGGER_NAME = 'cart created';
+const CACHE_KEY = `${TRIGGER_NAME}-trigger-store-key`;
+const TRIGGER_SCOPE = 'store/cart/created';
+
+export const cartCreated = createTrigger({
+  auth: bigcommerceAuth,
+  name: 'cartCreated',
+  displayName: 'Cart Created',
+  description: 'Triggers when a new cart is created',
+  aiMetadata: {
+    description:
+      'Fires when a new shopping cart is created in the BigCommerce store (a shopper adds the first item to a fresh cart). The event identifies the new cart.',
+  },
+  props: {},
+  sampleData: {
+    producer: 'stores/dxqdddcaklwsso',
+    hash: '3610addd127e330084ddddd7ddd09b78abfd1a85',
+    created_at: 1761809622,
+    store_id: '1003425529',
+    scope: 'store/cart/created',
+    data: {
+      type: 'cart',
+      id: 'ss-598f-4c95-813b-0ess950562770d',
+    },
+  },
+  type: TriggerStrategy.WEBHOOK,
+  async onEnable(context) {
+    const webhook = await bigCommerceApiService.createWebhook({
+      auth: context.auth.props,
+      payload: {
+        scope: TRIGGER_SCOPE  ,
+        destination: context.webhookUrl,
+        is_active: true,
+      },
+    });
+
+    await context.store.put(CACHE_KEY, webhook.data.id);
+  },
+  async onDisable(context) {
+    const webhookId = (await context.store.get(CACHE_KEY)) as string;
+
+    if (webhookId) {
+      await bigCommerceApiService
+        .deleteWebhook({
+          auth: context.auth.props,
+          webhookId,
+        })
+        .then(async () => {
+          await context.store.delete(CACHE_KEY);
+        });
+    }
+  },
+  async run(context) {
+    return [context.payload.body];
+  },
+});

package/src/lib/triggers/customer-address-created.ts

@@ -0,0 +1,60 @@
+import { createTrigger, TriggerStrategy } from '@agnocon/pieces-framework';
+import { bigcommerceAuth } from '../common/auth';
+import { bigCommerceApiService } from '../common/requests';
+
+const TRIGGER_NAME = 'customer address created';
+const CACHE_KEY = `${TRIGGER_NAME}-trigger-store-key`;
+const TRIGGER_SCOPE = 'store/customer/address/created';
+
+export const customerAddressCreated = createTrigger({
+  auth: bigcommerceAuth,
+  name: 'customerAddressCreated',
+  displayName: 'Customer Address Created',
+  description: 'Triggers when a new customer address is created',
+  aiMetadata: {
+    description:
+      'Fires when a new address is added to a customer in the BigCommerce store. The event identifies the affected customer.',
+  },
+  props: {},
+  sampleData: {
+    producer: 'stores/xqcaklwsso',
+    hash: 'd7b899890f5e0e98a3e074f018b14b07d5d89360',
+    created_at: 1761808595,
+    store_id: '1003425529',
+    scope: 'store/customer/address/created',
+    data: {
+      type: 'customer',
+      id: 2,
+    },
+  },
+  type: TriggerStrategy.WEBHOOK,
+  async onEnable(context) {
+    const webhook = await bigCommerceApiService.createWebhook({
+      auth: context.auth.props,
+      payload: {
+        scope: TRIGGER_SCOPE,
+        destination: context.webhookUrl,
+        is_active: true,
+      },
+    });
+
+    await context.store.put(CACHE_KEY, webhook.data.id);
+  },
+  async onDisable(context) {
+    const webhookId = (await context.store.get(CACHE_KEY)) as string;
+
+    if (webhookId) {
+      await bigCommerceApiService
+        .deleteWebhook({
+          auth: context.auth.props,
+          webhookId,
+        })
+        .then(async () => {
+          await context.store.delete(CACHE_KEY);
+        });
+    }
+  },
+  async run(context) {
+    return [context.payload.body];
+  },
+});

package/src/lib/triggers/customer-address-updated.ts

@@ -0,0 +1,60 @@
+import { createTrigger, TriggerStrategy } from '@agnocon/pieces-framework';
+import { bigcommerceAuth } from '../common/auth';
+import { bigCommerceApiService } from '../common/requests';
+
+const TRIGGER_NAME = 'customer address updated';
+const CACHE_KEY = `${TRIGGER_NAME}-trigger-store-key`;
+const TRIGGER_SCOPE = 'store/customer/address/updated';
+
+export const customerAddressUpdated = createTrigger({
+  auth: bigcommerceAuth,
+  name: 'customerAddressUpdated',
+  displayName: 'Customer Address Updated',
+  description: 'Triggers when a new customer address is updated',
+  aiMetadata: {
+    description:
+      'Fires when an existing customer address is updated in the BigCommerce store. The event identifies the affected customer.',
+  },
+  props: {},
+  sampleData:{
+    producer: 'stores/xqcaklwsso',
+    hash: 'd7b899890f5e0e98a3e074f018b14b07d5d89360',
+    created_at: 1761808595,
+    store_id: '1003425529',
+    scope: 'store/customer/address/updated',
+    data: {
+      type: 'customer',
+      id: 2,
+    },
+  },
+  type: TriggerStrategy.WEBHOOK,
+  async onEnable(context) {
+    const webhook = await bigCommerceApiService.createWebhook({
+      auth: context.auth.props,
+      payload: {
+        scope: TRIGGER_SCOPE,
+        destination: context.webhookUrl,
+        is_active: true,
+      },
+    });
+
+    await context.store.put(CACHE_KEY, webhook.data.id);
+  },
+  async onDisable(context) {
+    const webhookId = (await context.store.get(CACHE_KEY)) as string;
+
+    if (webhookId) {
+      await bigCommerceApiService
+        .deleteWebhook({
+          auth: context.auth.props,
+          webhookId,
+        })
+        .then(async () => {
+          await context.store.delete(CACHE_KEY);
+        });
+    }
+  },
+  async run(context) {
+    return [context.payload.body];
+  },
+});

package/src/lib/triggers/customer-created.ts

@@ -0,0 +1,62 @@
+import { createTrigger, TriggerStrategy } from '@agnocon/pieces-framework';
+import { bigcommerceAuth } from '../common/auth';
+import { bigCommerceApiService } from '../common/requests';
+
+const TRIGGER_NAME = 'customer created';
+const CACHE_KEY = `${TRIGGER_NAME}-trigger-store-key`;
+const TRIGGER_SCOPE = 'store/customer/created';
+
+export const customerCreated = createTrigger({
+  auth: bigcommerceAuth,
+  name: 'customerCreated',
+  displayName: 'Customer Created',
+  description: 'Triggers when a new customer is created',
+  aiMetadata: {
+    description:
+      'Fires when a new customer is created in the BigCommerce store. The event identifies the new customer.',
+  },
+  props: {},
+  sampleData: {
+    producer: 'stores/xqcaklwsso',
+    hash: 'd7b899890f5e0e98a3e074f018b14b07d5d89360',
+    created_at: 1761808595,
+    store_id: '1003425529',
+    scope: 'store/customer/created',
+    data: {
+      type: 'customer',
+      id: 2,
+      origin_channel_id: 1,
+      channel_ids: [1],
+    },
+  },
+  type: TriggerStrategy.WEBHOOK,
+  async onEnable(context) {
+    const webhook = await bigCommerceApiService.createWebhook({
+      auth: context.auth.props,
+      payload: {
+        scope: TRIGGER_SCOPE,
+        destination: context.webhookUrl,
+        is_active: true,
+      },
+    });
+
+    await context.store.put(CACHE_KEY, webhook.data.id);
+  },
+  async onDisable(context) {
+    const webhookId = (await context.store.get(CACHE_KEY)) as string;
+
+    if (webhookId) {
+      await bigCommerceApiService
+        .deleteWebhook({
+          auth: context.auth.props,
+          webhookId,
+        })
+        .then(async () => {
+          await context.store.delete(CACHE_KEY);
+        });
+    }
+  },
+  async run(context) {
+    return [context.payload.body];
+  },
+});

package/src/lib/triggers/customer-updated.ts

@@ -0,0 +1,60 @@
+import { createTrigger, TriggerStrategy } from '@agnocon/pieces-framework';
+import { bigcommerceAuth } from '../common/auth';
+import { bigCommerceApiService } from '../common/requests';
+
+const TRIGGER_NAME = 'customer updated';
+const CACHE_KEY = `${TRIGGER_NAME}-trigger-store-key`;
+const TRIGGER_SCOPE = 'store/customer/updated';
+
+export const customerUpdated = createTrigger({
+  auth: bigcommerceAuth,
+  name: 'customerUpdated',
+  displayName: 'Customer Updated',
+  description: 'Triggers when a customer is updated',
+  aiMetadata: {
+    description:
+      'Fires when an existing customer record is updated in the BigCommerce store. The event identifies the affected customer.',
+  },
+  props: {},
+  sampleData: {
+    producer: 'stores/xqcaklwsso',
+    hash: 'd7b899890f5e0e98a3e074f018b14b07d5d89360',
+    created_at: 1761808595,
+    store_id: '1003425529',
+    scope: 'store/customer/updated',
+    data: {
+      type: 'customer',
+      id: 2,
+    },
+  },    
+  type: TriggerStrategy.WEBHOOK,
+  async onEnable(context) {
+    const webhook = await bigCommerceApiService.createWebhook({
+      auth: context.auth.props,
+      payload: {
+        scope: TRIGGER_SCOPE,
+        destination: context.webhookUrl,
+        is_active: true,
+      },
+    });
+
+    await context.store.put(CACHE_KEY, webhook.data.id);
+  },
+  async onDisable(context) {
+    const webhookId = (await context.store.get(CACHE_KEY)) as string;
+
+    if (webhookId) {
+      await bigCommerceApiService
+        .deleteWebhook({
+          auth: context.auth.props,
+          webhookId,
+        })
+        .then(async () => {
+          await context.store.delete(CACHE_KEY);
+        });
+    }
+  },
+  async run(context) {
+    return [context.payload.body];
+  },
+});

package/src/lib/triggers/order-created.ts

@@ -0,0 +1,60 @@
+import { createTrigger, TriggerStrategy } from '@agnocon/pieces-framework';
+import { bigcommerceAuth } from '../common/auth';
+import { bigCommerceApiService } from '../common/requests';
+
+const TRIGGER_NAME = 'order created';
+const CACHE_KEY = `${TRIGGER_NAME}-trigger-store-key`;
+const TRIGGER_SCOPE = 'store/order/created';
+
+export const orderCreated = createTrigger({
+  auth: bigcommerceAuth,
+  name: 'orderCreated',
+  displayName: 'Order Created',
+  description: 'Triggers when a new order is created',
+  aiMetadata: {
+    description:
+      'Fires when a new order is created in the BigCommerce store. The event identifies the new order; pair with Get Order to fetch its full details.',
+  },
+  props: {},
+  sampleData: {
+    producer: 'stores/xqcaklwsso',
+    hash: 'd7b899890f5e0e98a3e074f018b14b07d5d89360',
+    created_at: 1761808595,
+    store_id: '1003425529',
+    scope: 'store/order/created',
+    data: {
+      type: 'order',
+      id: 2,
+    },
+  },
+  type: TriggerStrategy.WEBHOOK,
+  async onEnable(context) {
+    const webhook = await bigCommerceApiService.createWebhook({
+      auth: context.auth.props,
+      payload: {
+        scope: TRIGGER_SCOPE,
+        destination: context.webhookUrl,
+        is_active: true,
+      },
+    });
+
+    await context.store.put(CACHE_KEY, webhook.data.id);
+  },
+  async onDisable(context) {
+    const webhookId = (await context.store.get(CACHE_KEY)) as string;
+
+    if (webhookId) {
+      await bigCommerceApiService
+        .deleteWebhook({
+          auth: context.auth.props,
+          webhookId,
+        })
+        .then(async () => {
+          await context.store.delete(CACHE_KEY);
+        });
+    }
+  },
+  async run(context) {
+    return [context.payload.body];
+  },
+});