chore: import upstream snapshot with attribution

apps/sim/tools/square/batch_retrieve_inventory_counts.ts

@@ -0,0 +1,112 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type {
+  BatchRetrieveInventoryCountsParams,
+  InventoryCountListResponse,
+} from '@/tools/square/types'
+import {
+  INVENTORY_COUNT_OUTPUT,
+  LIST_METADATA_OUTPUT_PROPERTIES,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareBatchRetrieveInventoryCountsTool: ToolConfig<
+  BatchRetrieveInventoryCountsParams,
+  InventoryCountListResponse
+> = {
+  id: 'square_batch_retrieve_inventory_counts',
+  name: 'Square Batch Retrieve Inventory Counts',
+  description: 'Retrieve current inventory counts for catalog items across locations',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    catalogObjectIds: {
+      type: 'array',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'IDs of the catalog item variations to retrieve counts for',
+    },
+    locationIds: {
+      type: 'array',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'IDs of the locations to retrieve counts for (defaults to all locations)',
+    },
+    states: {
+      type: 'array',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Inventory states to filter by (e.g. IN_STOCK, SOLD, IN_TRANSIT)',
+    },
+    updatedAfter: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Only return counts updated after this RFC 3339 timestamp',
+    },
+    limit: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Maximum number of results to return per page (1-1000)',
+    },
+    cursor: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Pagination cursor from a previous response',
+    },
+  },
+
+  request: {
+    url: () => `${SQUARE_BASE_URL}/v2/inventory/counts/batch-retrieve`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => {
+      const body: Record<string, unknown> = {}
+      if (params.catalogObjectIds) body.catalog_object_ids = params.catalogObjectIds
+      if (params.locationIds) body.location_ids = params.locationIds
+      if (params.states) body.states = params.states
+      if (params.updatedAfter) body.updated_after = params.updatedAfter
+      if (params.limit !== undefined) body.limit = params.limit
+      if (params.cursor) body.cursor = params.cursor
+      return body
+    },
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const counts = data.counts ?? []
+    return {
+      success: true,
+      output: {
+        counts,
+        metadata: {
+          count: counts.length,
+          cursor: data.cursor ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    counts: {
+      type: 'array',
+      description: 'Array of inventory count objects',
+      items: INVENTORY_COUNT_OUTPUT,
+    },
+    metadata: {
+      type: 'json',
+      description: 'List pagination metadata',
+      properties: LIST_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/cancel_invoice.ts

@@ -0,0 +1,71 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CancelInvoiceParams, InvoiceResponse } from '@/tools/square/types'
+import {
+  INVOICE_METADATA_OUTPUT_PROPERTIES,
+  INVOICE_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareCancelInvoiceTool: ToolConfig<CancelInvoiceParams, InvoiceResponse> = {
+  id: 'square_cancel_invoice',
+  name: 'Square Cancel Invoice',
+  description: 'Cancel a published invoice that is unpaid or partially paid',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    invoiceId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the invoice to cancel',
+    },
+    version: {
+      type: 'number',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Current version of the invoice',
+    },
+  },
+
+  request: {
+    url: (params) =>
+      `${SQUARE_BASE_URL}/v2/invoices/${encodeURIComponent(params.invoiceId)}/cancel`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => ({ version: params.version }),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const invoice = data.invoice ?? {}
+    return {
+      success: true,
+      output: {
+        invoice,
+        metadata: {
+          id: invoice.id,
+          status: invoice.status ?? null,
+          version: invoice.version ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    invoice: { ...INVOICE_OUTPUT, description: 'The canceled invoice object' },
+    metadata: {
+      type: 'json',
+      description: 'Invoice summary metadata',
+      properties: INVOICE_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/cancel_payment.ts

@@ -0,0 +1,65 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CancelPaymentParams, PaymentResponse } from '@/tools/square/types'
+import {
+  PAYMENT_METADATA_OUTPUT_PROPERTIES,
+  PAYMENT_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareCancelPaymentTool: ToolConfig<CancelPaymentParams, PaymentResponse> = {
+  id: 'square_cancel_payment',
+  name: 'Square Cancel Payment',
+  description: 'Cancel (void) an authorized payment that has not been captured',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    paymentId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the payment to cancel',
+    },
+  },
+
+  request: {
+    url: (params) =>
+      `${SQUARE_BASE_URL}/v2/payments/${encodeURIComponent(params.paymentId)}/cancel`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: () => ({}),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const payment = data.payment ?? {}
+    return {
+      success: true,
+      output: {
+        payment,
+        metadata: {
+          id: payment.id,
+          status: payment.status ?? null,
+          order_id: payment.order_id ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    payment: { ...PAYMENT_OUTPUT, description: 'The canceled payment object' },
+    metadata: {
+      type: 'json',
+      description: 'Payment summary metadata',
+      properties: PAYMENT_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/complete_payment.ts

@@ -0,0 +1,71 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CompletePaymentParams, PaymentResponse } from '@/tools/square/types'
+import {
+  PAYMENT_METADATA_OUTPUT_PROPERTIES,
+  PAYMENT_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareCompletePaymentTool: ToolConfig<CompletePaymentParams, PaymentResponse> = {
+  id: 'square_complete_payment',
+  name: 'Square Complete Payment',
+  description: 'Capture (complete) a payment that was authorized with delayed capture',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    paymentId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the payment to complete',
+    },
+    versionToken: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Optional version token for optimistic concurrency control',
+    },
+  },
+
+  request: {
+    url: (params) =>
+      `${SQUARE_BASE_URL}/v2/payments/${encodeURIComponent(params.paymentId)}/complete`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => (params.versionToken ? { version_token: params.versionToken } : {}),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const payment = data.payment ?? {}
+    return {
+      success: true,
+      output: {
+        payment,
+        metadata: {
+          id: payment.id,
+          status: payment.status ?? null,
+          order_id: payment.order_id ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    payment: { ...PAYMENT_OUTPUT, description: 'The completed payment object' },
+    metadata: {
+      type: 'json',
+      description: 'Payment summary metadata',
+      properties: PAYMENT_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/create_catalog_image.ts

@@ -0,0 +1,91 @@
+import type { CatalogObjectResponse, CreateCatalogImageParams } from '@/tools/square/types'
+import {
+  CATALOG_OBJECT_METADATA_OUTPUT_PROPERTIES,
+  CATALOG_OBJECT_OUTPUT,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareCreateCatalogImageTool: ToolConfig<
+  CreateCatalogImageParams,
+  CatalogObjectResponse
+> = {
+  id: 'square_create_catalog_image',
+  name: 'Square Create Catalog Image',
+  description: 'Upload an image and attach it to the catalog, optionally to a specific item',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    file: {
+      type: 'file',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'The image file to upload (UserFile object)',
+    },
+    fileName: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Optional filename override for the image',
+    },
+    objectId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'ID of the catalog object (e.g. an item) to attach the image to',
+    },
+    caption: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Caption (alt text) for the image',
+    },
+    idempotencyKey: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Unique key to make the request idempotent (auto-generated if omitted)',
+    },
+  },
+
+  request: {
+    url: '/api/tools/square/catalog-image',
+    method: 'POST',
+    headers: () => ({
+      'Content-Type': 'application/json',
+    }),
+    body: (params) => ({
+      accessToken: params.apiKey,
+      file: params.file,
+      fileName: params.fileName,
+      objectId: params.objectId,
+      caption: params.caption,
+      idempotencyKey: params.idempotencyKey,
+    }),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    if (!data.success) {
+      throw new Error(data.error || 'Failed to upload catalog image')
+    }
+    return {
+      success: true,
+      output: data.output,
+    }
+  },
+
+  outputs: {
+    object: { ...CATALOG_OBJECT_OUTPUT, description: 'The created catalog image object' },
+    metadata: {
+      type: 'json',
+      description: 'Catalog object summary metadata',
+      properties: CATALOG_OBJECT_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/create_customer.ts

@@ -0,0 +1,141 @@
+import { generateId } from '@sim/utils/id'
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CreateCustomerParams, CustomerResponse } from '@/tools/square/types'
+import {
+  CUSTOMER_METADATA_OUTPUT_PROPERTIES,
+  CUSTOMER_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareCreateCustomerTool: ToolConfig<CreateCustomerParams, CustomerResponse> = {
+  id: 'square_create_customer',
+  name: 'Square Create Customer',
+  description: 'Create a new customer profile in the Square customer directory',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    givenName: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'First name of the customer',
+    },
+    familyName: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Last name of the customer',
+    },
+    companyName: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Business name of the customer',
+    },
+    nickname: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Nickname of the customer',
+    },
+    emailAddress: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Email address of the customer',
+    },
+    phoneNumber: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Phone number of the customer',
+    },
+    birthday: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Birthday in YYYY-MM-DD or MM-DD format',
+    },
+    note: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Note about the customer',
+    },
+    referenceId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Optional external reference for the customer',
+    },
+    address: {
+      type: 'json',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Square address object for the customer',
+    },
+    idempotencyKey: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Unique key to make the request idempotent (auto-generated if omitted)',
+    },
+  },
+
+  request: {
+    url: () => `${SQUARE_BASE_URL}/v2/customers`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => {
+      const body: Record<string, unknown> = {
+        idempotency_key: params.idempotencyKey || generateId(),
+      }
+      if (params.givenName) body.given_name = params.givenName
+      if (params.familyName) body.family_name = params.familyName
+      if (params.companyName) body.company_name = params.companyName
+      if (params.nickname) body.nickname = params.nickname
+      if (params.emailAddress) body.email_address = params.emailAddress
+      if (params.phoneNumber) body.phone_number = params.phoneNumber
+      if (params.birthday) body.birthday = params.birthday
+      if (params.note) body.note = params.note
+      if (params.referenceId) body.reference_id = params.referenceId
+      if (params.address) body.address = params.address
+      return body
+    },
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const customer = data.customer ?? {}
+    return {
+      success: true,
+      output: {
+        customer,
+        metadata: {
+          id: customer.id,
+          email_address: customer.email_address ?? null,
+          given_name: customer.given_name ?? null,
+          family_name: customer.family_name ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    customer: { ...CUSTOMER_OUTPUT, description: 'The created customer object' },
+    metadata: {
+      type: 'json',
+      description: 'Customer summary metadata',
+      properties: CUSTOMER_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/create_invoice.ts

@@ -0,0 +1,75 @@
+import { generateId } from '@sim/utils/id'
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CreateInvoiceParams, InvoiceResponse } from '@/tools/square/types'
+import {
+  INVOICE_METADATA_OUTPUT_PROPERTIES,
+  INVOICE_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareCreateInvoiceTool: ToolConfig<CreateInvoiceParams, InvoiceResponse> = {
+  id: 'square_create_invoice',
+  name: 'Square Create Invoice',
+  description: 'Create a draft invoice for an existing order and customer',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    invoice: {
+      type: 'json',
+      required: true,
+      visibility: 'user-or-llm',
+      description:
+        'Square invoice object including location_id, order_id, primary_recipient, and payment_requests (e.g. {"location_id":"L1","order_id":"O1","primary_recipient":{"customer_id":"C1"},"payment_requests":[{"request_type":"BALANCE","due_date":"2026-07-01"}]})',
+    },
+    idempotencyKey: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Unique key to make the request idempotent (auto-generated if omitted)',
+    },
+  },
+
+  request: {
+    url: () => `${SQUARE_BASE_URL}/v2/invoices`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => ({
+      idempotency_key: params.idempotencyKey || generateId(),
+      invoice: params.invoice,
+    }),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const invoice = data.invoice ?? {}
+    return {
+      success: true,
+      output: {
+        invoice,
+        metadata: {
+          id: invoice.id,
+          status: invoice.status ?? null,
+          version: invoice.version ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    invoice: { ...INVOICE_OUTPUT, description: 'The created invoice object' },
+    metadata: {
+      type: 'json',
+      description: 'Invoice summary metadata',
+      properties: INVOICE_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/create_order.ts

@@ -0,0 +1,75 @@
+import { generateId } from '@sim/utils/id'
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CreateOrderParams, OrderResponse } from '@/tools/square/types'
+import {
+  ORDER_METADATA_OUTPUT_PROPERTIES,
+  ORDER_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareCreateOrderTool: ToolConfig<CreateOrderParams, OrderResponse> = {
+  id: 'square_create_order',
+  name: 'Square Create Order',
+  description: 'Create an order with line items, taxes, discounts, and fulfillments',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    order: {
+      type: 'json',
+      required: true,
+      visibility: 'user-or-llm',
+      description:
+        'Square order object including location_id and line_items (e.g. {"location_id":"L1","line_items":[{"name":"Coffee","quantity":"1","base_price_money":{"amount":250,"currency":"USD"}}]})',
+    },
+    idempotencyKey: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Unique key to make the request idempotent (auto-generated if omitted)',
+    },
+  },
+
+  request: {
+    url: () => `${SQUARE_BASE_URL}/v2/orders`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => ({
+      idempotency_key: params.idempotencyKey || generateId(),
+      order: params.order,
+    }),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const order = data.order ?? {}
+    return {
+      success: true,
+      output: {
+        order,
+        metadata: {
+          id: order.id,
+          state: order.state ?? null,
+          location_id: order.location_id ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    order: { ...ORDER_OUTPUT, description: 'The created order object' },
+    metadata: {
+      type: 'json',
+      description: 'Order summary metadata',
+      properties: ORDER_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/create_payment.ts

@@ -0,0 +1,132 @@
+import { generateId } from '@sim/utils/id'
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CreatePaymentParams, PaymentResponse } from '@/tools/square/types'
+import {
+  PAYMENT_METADATA_OUTPUT_PROPERTIES,
+  PAYMENT_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareCreatePaymentTool: ToolConfig<CreatePaymentParams, PaymentResponse> = {
+  id: 'square_create_payment',
+  name: 'Square Create Payment',
+  description: 'Take a payment using a payment source such as a card nonce or a card on file',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    sourceId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the payment source (card nonce, card-on-file ID, or wallet token)',
+    },
+    amount: {
+      type: 'number',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Amount in the smallest currency denomination (e.g. 1000 = $10.00)',
+    },
+    currency: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Three-letter ISO 4217 currency code (e.g. USD)',
+    },
+    idempotencyKey: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Unique key to make the request idempotent (auto-generated if omitted)',
+    },
+    customerId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'ID of the customer associated with the payment',
+    },
+    locationId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'ID of the location where the payment is taken (defaults to the main location)',
+    },
+    orderId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'ID of the order associated with the payment',
+    },
+    referenceId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Optional external reference for the payment',
+    },
+    note: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Optional note attached to the payment',
+    },
+    autocomplete: {
+      type: 'boolean',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Whether to immediately capture the payment (defaults to true)',
+    },
+  },
+
+  request: {
+    url: () => `${SQUARE_BASE_URL}/v2/payments`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => {
+      const body: Record<string, unknown> = {
+        idempotency_key: params.idempotencyKey || generateId(),
+        source_id: params.sourceId,
+        amount_money: { amount: params.amount, currency: params.currency },
+      }
+      if (params.customerId) body.customer_id = params.customerId
+      if (params.locationId) body.location_id = params.locationId
+      if (params.orderId) body.order_id = params.orderId
+      if (params.referenceId) body.reference_id = params.referenceId
+      if (params.note) body.note = params.note
+      if (params.autocomplete !== undefined) body.autocomplete = params.autocomplete
+      return body
+    },
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const payment = data.payment ?? {}
+    return {
+      success: true,
+      output: {
+        payment,
+        metadata: {
+          id: payment.id,
+          status: payment.status ?? null,
+          order_id: payment.order_id ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    payment: { ...PAYMENT_OUTPUT, description: 'The created payment object' },
+    metadata: {
+      type: 'json',
+      description: 'Payment summary metadata',
+      properties: PAYMENT_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/delete_catalog_object.ts

@@ -0,0 +1,62 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CatalogDeleteResponse, DeleteCatalogObjectParams } from '@/tools/square/types'
+import { SQUARE_BASE_URL, squareHeaders } from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareDeleteCatalogObjectTool: ToolConfig<
+  DeleteCatalogObjectParams,
+  CatalogDeleteResponse
+> = {
+  id: 'square_delete_catalog_object',
+  name: 'Square Delete Catalog Object',
+  description: 'Delete a catalog object and its children (e.g. an item and its variations)',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    objectId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the catalog object to delete',
+    },
+  },
+
+  request: {
+    url: (params) => `${SQUARE_BASE_URL}/v2/catalog/object/${encodeURIComponent(params.objectId)}`,
+    method: 'DELETE',
+    headers: (params) => squareHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    return {
+      success: true,
+      output: {
+        deleted: true,
+        deleted_object_ids: data.deleted_object_ids ?? [],
+        deleted_at: data.deleted_at ?? null,
+      },
+    }
+  },
+
+  outputs: {
+    deleted: { type: 'boolean', description: 'Whether the catalog object was deleted' },
+    deleted_object_ids: {
+      type: 'array',
+      description: 'IDs of all catalog objects deleted (including children)',
+      items: { type: 'string' },
+    },
+    deleted_at: {
+      type: 'string',
+      description: 'Timestamp when the deletion occurred (RFC 3339)',
+      optional: true,
+    },
+  },
+}

apps/sim/tools/square/delete_customer.ts

@@ -0,0 +1,49 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CustomerDeleteResponse, DeleteCustomerParams } from '@/tools/square/types'
+import { SQUARE_BASE_URL, squareHeaders } from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareDeleteCustomerTool: ToolConfig<DeleteCustomerParams, CustomerDeleteResponse> = {
+  id: 'square_delete_customer',
+  name: 'Square Delete Customer',
+  description: 'Delete a customer profile from the Square customer directory',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    customerId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the customer to delete',
+    },
+  },
+
+  request: {
+    url: (params) => `${SQUARE_BASE_URL}/v2/customers/${encodeURIComponent(params.customerId)}`,
+    method: 'DELETE',
+    headers: (params) => squareHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response, params) => {
+    await response.json().catch(() => ({}))
+    return {
+      success: true,
+      output: {
+        deleted: true,
+        id: params?.customerId ?? '',
+      },
+    }
+  },
+
+  outputs: {
+    deleted: { type: 'boolean', description: 'Whether the customer was deleted' },
+    id: { type: 'string', description: 'ID of the deleted customer' },
+  },
+}

apps/sim/tools/square/delete_invoice.ts

@@ -0,0 +1,60 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { DeleteInvoiceParams, InvoiceDeleteResponse } from '@/tools/square/types'
+import { SQUARE_BASE_URL, squareHeaders } from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareDeleteInvoiceTool: ToolConfig<DeleteInvoiceParams, InvoiceDeleteResponse> = {
+  id: 'square_delete_invoice',
+  name: 'Square Delete Invoice',
+  description: 'Delete a draft invoice',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    invoiceId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the draft invoice to delete',
+    },
+    version: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Current version of the invoice (required if the invoice has been updated)',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const url = new URL(`${SQUARE_BASE_URL}/v2/invoices/${encodeURIComponent(params.invoiceId)}`)
+      if (params.version !== undefined)
+        url.searchParams.append('version', params.version.toString())
+      return url.toString()
+    },
+    method: 'DELETE',
+    headers: (params) => squareHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response, params) => {
+    await response.json().catch(() => ({}))
+    return {
+      success: true,
+      output: {
+        deleted: true,
+        id: params?.invoiceId ?? '',
+      },
+    }
+  },
+
+  outputs: {
+    deleted: { type: 'boolean', description: 'Whether the invoice was deleted' },
+    id: { type: 'string', description: 'ID of the deleted invoice' },
+  },
+}

apps/sim/tools/square/get_catalog_object.ts

@@ -0,0 +1,78 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CatalogObjectResponse, GetCatalogObjectParams } from '@/tools/square/types'
+import {
+  CATALOG_OBJECT_METADATA_OUTPUT_PROPERTIES,
+  CATALOG_OBJECT_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareGetCatalogObjectTool: ToolConfig<GetCatalogObjectParams, CatalogObjectResponse> =
+  {
+    id: 'square_get_catalog_object',
+    name: 'Square Get Catalog Object',
+    description: 'Retrieve a single catalog object by its ID',
+    version: '1.0.0',
+    errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+    params: {
+      apiKey: {
+        type: 'string',
+        required: true,
+        visibility: 'user-only',
+        description: 'Square access token (personal access token)',
+      },
+      objectId: {
+        type: 'string',
+        required: true,
+        visibility: 'user-or-llm',
+        description: 'ID of the catalog object to retrieve',
+      },
+      includeRelatedObjects: {
+        type: 'boolean',
+        required: false,
+        visibility: 'user-or-llm',
+        description: 'Whether to include related objects such as an item variations',
+      },
+    },
+
+    request: {
+      url: (params) => {
+        const url = new URL(
+          `${SQUARE_BASE_URL}/v2/catalog/object/${encodeURIComponent(params.objectId)}`
+        )
+        if (params.includeRelatedObjects !== undefined) {
+          url.searchParams.append('include_related_objects', String(params.includeRelatedObjects))
+        }
+        return url.toString()
+      },
+      method: 'GET',
+      headers: (params) => squareHeaders(params.apiKey),
+    },
+
+    transformResponse: async (response) => {
+      const data = await response.json()
+      const object = data.object ?? {}
+      return {
+        success: true,
+        output: {
+          object,
+          metadata: {
+            id: object.id,
+            type: object.type ?? null,
+            version: object.version ?? null,
+          },
+        },
+      }
+    },
+
+    outputs: {
+      object: { ...CATALOG_OBJECT_OUTPUT, description: 'The retrieved catalog object' },
+      metadata: {
+        type: 'json',
+        description: 'Catalog object summary metadata',
+        properties: CATALOG_OBJECT_METADATA_OUTPUT_PROPERTIES,
+      },
+    },
+  }

apps/sim/tools/square/get_customer.ts

@@ -0,0 +1,64 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CustomerResponse, GetCustomerParams } from '@/tools/square/types'
+import {
+  CUSTOMER_METADATA_OUTPUT_PROPERTIES,
+  CUSTOMER_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareGetCustomerTool: ToolConfig<GetCustomerParams, CustomerResponse> = {
+  id: 'square_get_customer',
+  name: 'Square Get Customer',
+  description: 'Retrieve a single customer profile by its ID',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    customerId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the customer to retrieve',
+    },
+  },
+
+  request: {
+    url: (params) => `${SQUARE_BASE_URL}/v2/customers/${encodeURIComponent(params.customerId)}`,
+    method: 'GET',
+    headers: (params) => squareHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const customer = data.customer ?? {}
+    return {
+      success: true,
+      output: {
+        customer,
+        metadata: {
+          id: customer.id,
+          email_address: customer.email_address ?? null,
+          given_name: customer.given_name ?? null,
+          family_name: customer.family_name ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    customer: { ...CUSTOMER_OUTPUT, description: 'The retrieved customer object' },
+    metadata: {
+      type: 'json',
+      description: 'Customer summary metadata',
+      properties: CUSTOMER_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/get_invoice.ts

@@ -0,0 +1,63 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { GetInvoiceParams, InvoiceResponse } from '@/tools/square/types'
+import {
+  INVOICE_METADATA_OUTPUT_PROPERTIES,
+  INVOICE_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareGetInvoiceTool: ToolConfig<GetInvoiceParams, InvoiceResponse> = {
+  id: 'square_get_invoice',
+  name: 'Square Get Invoice',
+  description: 'Retrieve a single invoice by its ID',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    invoiceId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the invoice to retrieve',
+    },
+  },
+
+  request: {
+    url: (params) => `${SQUARE_BASE_URL}/v2/invoices/${encodeURIComponent(params.invoiceId)}`,
+    method: 'GET',
+    headers: (params) => squareHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const invoice = data.invoice ?? {}
+    return {
+      success: true,
+      output: {
+        invoice,
+        metadata: {
+          id: invoice.id,
+          status: invoice.status ?? null,
+          version: invoice.version ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    invoice: { ...INVOICE_OUTPUT, description: 'The retrieved invoice object' },
+    metadata: {
+      type: 'json',
+      description: 'Invoice summary metadata',
+      properties: INVOICE_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/get_location.ts

@@ -0,0 +1,60 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { GetLocationParams, LocationResponse } from '@/tools/square/types'
+import { LOCATION_OUTPUT, SQUARE_BASE_URL, squareHeaders } from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareGetLocationTool: ToolConfig<GetLocationParams, LocationResponse> = {
+  id: 'square_get_location',
+  name: 'Square Get Location',
+  description: 'Retrieve a single location by its ID',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    locationId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the location to retrieve (use "main" for the main location)',
+    },
+  },
+
+  request: {
+    url: (params) => `${SQUARE_BASE_URL}/v2/locations/${encodeURIComponent(params.locationId)}`,
+    method: 'GET',
+    headers: (params) => squareHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const location = data.location ?? {}
+    return {
+      success: true,
+      output: {
+        location,
+        metadata: {
+          id: location.id,
+          name: location.name ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    location: { ...LOCATION_OUTPUT, description: 'The retrieved location object' },
+    metadata: {
+      type: 'json',
+      description: 'Location summary metadata',
+      properties: {
+        id: { type: 'string', description: 'Square location ID' },
+        name: { type: 'string', description: 'Location name', optional: true },
+      },
+    },
+  },
+}

apps/sim/tools/square/get_order.ts

@@ -0,0 +1,63 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { GetOrderParams, OrderResponse } from '@/tools/square/types'
+import {
+  ORDER_METADATA_OUTPUT_PROPERTIES,
+  ORDER_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareGetOrderTool: ToolConfig<GetOrderParams, OrderResponse> = {
+  id: 'square_get_order',
+  name: 'Square Get Order',
+  description: 'Retrieve a single order by its ID',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    orderId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the order to retrieve',
+    },
+  },
+
+  request: {
+    url: (params) => `${SQUARE_BASE_URL}/v2/orders/${encodeURIComponent(params.orderId)}`,
+    method: 'GET',
+    headers: (params) => squareHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const order = data.order ?? {}
+    return {
+      success: true,
+      output: {
+        order,
+        metadata: {
+          id: order.id,
+          state: order.state ?? null,
+          location_id: order.location_id ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    order: { ...ORDER_OUTPUT, description: 'The retrieved order object' },
+    metadata: {
+      type: 'json',
+      description: 'Order summary metadata',
+      properties: ORDER_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/get_payment.ts

@@ -0,0 +1,63 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { GetPaymentParams, PaymentResponse } from '@/tools/square/types'
+import {
+  PAYMENT_METADATA_OUTPUT_PROPERTIES,
+  PAYMENT_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareGetPaymentTool: ToolConfig<GetPaymentParams, PaymentResponse> = {
+  id: 'square_get_payment',
+  name: 'Square Get Payment',
+  description: 'Retrieve details for a single payment by its ID',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    paymentId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the payment to retrieve',
+    },
+  },
+
+  request: {
+    url: (params) => `${SQUARE_BASE_URL}/v2/payments/${encodeURIComponent(params.paymentId)}`,
+    method: 'GET',
+    headers: (params) => squareHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const payment = data.payment ?? {}
+    return {
+      success: true,
+      output: {
+        payment,
+        metadata: {
+          id: payment.id,
+          status: payment.status ?? null,
+          order_id: payment.order_id ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    payment: { ...PAYMENT_OUTPUT, description: 'The retrieved payment object' },
+    metadata: {
+      type: 'json',
+      description: 'Payment summary metadata',
+      properties: PAYMENT_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/get_refund.ts

@@ -0,0 +1,63 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { GetRefundParams, RefundResponse } from '@/tools/square/types'
+import {
+  REFUND_METADATA_OUTPUT_PROPERTIES,
+  REFUND_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareGetRefundTool: ToolConfig<GetRefundParams, RefundResponse> = {
+  id: 'square_get_refund',
+  name: 'Square Get Refund',
+  description: 'Retrieve a single payment refund by its ID',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    refundId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the refund to retrieve',
+    },
+  },
+
+  request: {
+    url: (params) => `${SQUARE_BASE_URL}/v2/refunds/${encodeURIComponent(params.refundId)}`,
+    method: 'GET',
+    headers: (params) => squareHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const refund = data.refund ?? {}
+    return {
+      success: true,
+      output: {
+        refund,
+        metadata: {
+          id: refund.id,
+          status: refund.status ?? null,
+          payment_id: refund.payment_id ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    refund: { ...REFUND_OUTPUT, description: 'The retrieved refund object' },
+    metadata: {
+      type: 'json',
+      description: 'Refund summary metadata',
+      properties: REFUND_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/index.ts

@@ -0,0 +1,34 @@
+export { squareBatchRetrieveInventoryCountsTool } from '@/tools/square/batch_retrieve_inventory_counts'
+export { squareCancelInvoiceTool } from '@/tools/square/cancel_invoice'
+export { squareCancelPaymentTool } from '@/tools/square/cancel_payment'
+export { squareCompletePaymentTool } from '@/tools/square/complete_payment'
+export { squareCreateCatalogImageTool } from '@/tools/square/create_catalog_image'
+export { squareCreateCustomerTool } from '@/tools/square/create_customer'
+export { squareCreateInvoiceTool } from '@/tools/square/create_invoice'
+export { squareCreateOrderTool } from '@/tools/square/create_order'
+export { squareCreatePaymentTool } from '@/tools/square/create_payment'
+export { squareDeleteCatalogObjectTool } from '@/tools/square/delete_catalog_object'
+export { squareDeleteCustomerTool } from '@/tools/square/delete_customer'
+export { squareDeleteInvoiceTool } from '@/tools/square/delete_invoice'
+export { squareGetCatalogObjectTool } from '@/tools/square/get_catalog_object'
+export { squareGetCustomerTool } from '@/tools/square/get_customer'
+export { squareGetInvoiceTool } from '@/tools/square/get_invoice'
+export { squareGetLocationTool } from '@/tools/square/get_location'
+export { squareGetOrderTool } from '@/tools/square/get_order'
+export { squareGetPaymentTool } from '@/tools/square/get_payment'
+export { squareGetRefundTool } from '@/tools/square/get_refund'
+export { squareListCatalogTool } from '@/tools/square/list_catalog'
+export { squareListCustomersTool } from '@/tools/square/list_customers'
+export { squareListInvoicesTool } from '@/tools/square/list_invoices'
+export { squareListLocationsTool } from '@/tools/square/list_locations'
+export { squareListPaymentsTool } from '@/tools/square/list_payments'
+export { squareListRefundsTool } from '@/tools/square/list_refunds'
+export { squarePayOrderTool } from '@/tools/square/pay_order'
+export { squarePublishInvoiceTool } from '@/tools/square/publish_invoice'
+export { squareRefundPaymentTool } from '@/tools/square/refund_payment'
+export { squareSearchCatalogObjectsTool } from '@/tools/square/search_catalog_objects'
+export { squareSearchCustomersTool } from '@/tools/square/search_customers'
+export { squareSearchInvoicesTool } from '@/tools/square/search_invoices'
+export { squareSearchOrdersTool } from '@/tools/square/search_orders'
+export { squareUpdateCustomerTool } from '@/tools/square/update_customer'
+export { squareUpsertCatalogObjectTool } from '@/tools/square/upsert_catalog_object'

apps/sim/tools/square/list_catalog.ts

@@ -0,0 +1,78 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CatalogListResponse, ListCatalogParams } from '@/tools/square/types'
+import {
+  CATALOG_OBJECT_OUTPUT,
+  LIST_METADATA_OUTPUT_PROPERTIES,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareListCatalogTool: ToolConfig<ListCatalogParams, CatalogListResponse> = {
+  id: 'square_list_catalog',
+  name: 'Square List Catalog',
+  description: 'List catalog objects, optionally filtered by type',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    types: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Comma-separated catalog object types to return (e.g. ITEM,CATEGORY). Defaults to all top-level types',
+    },
+    cursor: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Pagination cursor from a previous response',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const url = new URL(`${SQUARE_BASE_URL}/v2/catalog/list`)
+      if (params.types) url.searchParams.append('types', params.types)
+      if (params.cursor) url.searchParams.append('cursor', params.cursor)
+      return url.toString()
+    },
+    method: 'GET',
+    headers: (params) => squareHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const objects = data.objects ?? []
+    return {
+      success: true,
+      output: {
+        objects,
+        metadata: {
+          count: objects.length,
+          cursor: data.cursor ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    objects: {
+      type: 'array',
+      description: 'Array of catalog objects',
+      items: CATALOG_OBJECT_OUTPUT,
+    },
+    metadata: {
+      type: 'json',
+      description: 'List pagination metadata',
+      properties: LIST_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/list_customers.ts

@@ -0,0 +1,91 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CustomerListResponse, ListCustomersParams } from '@/tools/square/types'
+import {
+  CUSTOMER_OUTPUT,
+  LIST_METADATA_OUTPUT_PROPERTIES,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareListCustomersTool: ToolConfig<ListCustomersParams, CustomerListResponse> = {
+  id: 'square_list_customers',
+  name: 'Square List Customers',
+  description: 'List customer profiles in the Square customer directory',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    limit: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Maximum number of results to return per page (max 100)',
+    },
+    cursor: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Pagination cursor from a previous response',
+    },
+    sortField: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Field to sort by (DEFAULT or CREATED_AT)',
+    },
+    sortOrder: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Sort order (ASC or DESC)',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const url = new URL(`${SQUARE_BASE_URL}/v2/customers`)
+      if (params.limit !== undefined) url.searchParams.append('limit', params.limit.toString())
+      if (params.cursor) url.searchParams.append('cursor', params.cursor)
+      if (params.sortField) url.searchParams.append('sort_field', params.sortField)
+      if (params.sortOrder) url.searchParams.append('sort_order', params.sortOrder)
+      return url.toString()
+    },
+    method: 'GET',
+    headers: (params) => squareHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const customers = data.customers ?? []
+    return {
+      success: true,
+      output: {
+        customers,
+        metadata: {
+          count: customers.length,
+          cursor: data.cursor ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    customers: {
+      type: 'array',
+      description: 'Array of customer objects',
+      items: CUSTOMER_OUTPUT,
+    },
+    metadata: {
+      type: 'json',
+      description: 'List pagination metadata',
+      properties: LIST_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/list_invoices.ts

@@ -0,0 +1,84 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { InvoiceListResponse, ListInvoicesParams } from '@/tools/square/types'
+import {
+  INVOICE_OUTPUT,
+  LIST_METADATA_OUTPUT_PROPERTIES,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareListInvoicesTool: ToolConfig<ListInvoicesParams, InvoiceListResponse> = {
+  id: 'square_list_invoices',
+  name: 'Square List Invoices',
+  description: 'List invoices for a specific location',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    locationId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the location to list invoices for',
+    },
+    limit: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Maximum number of results to return per page',
+    },
+    cursor: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Pagination cursor from a previous response',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const url = new URL(`${SQUARE_BASE_URL}/v2/invoices`)
+      url.searchParams.append('location_id', params.locationId)
+      if (params.limit !== undefined) url.searchParams.append('limit', params.limit.toString())
+      if (params.cursor) url.searchParams.append('cursor', params.cursor)
+      return url.toString()
+    },
+    method: 'GET',
+    headers: (params) => squareHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const invoices = data.invoices ?? []
+    return {
+      success: true,
+      output: {
+        invoices,
+        metadata: {
+          count: invoices.length,
+          cursor: data.cursor ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    invoices: {
+      type: 'array',
+      description: 'Array of invoice objects',
+      items: INVOICE_OUTPUT,
+    },
+    metadata: {
+      type: 'json',
+      description: 'List pagination metadata',
+      properties: LIST_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/list_locations.ts

@@ -0,0 +1,56 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { ListLocationsParams, LocationListResponse } from '@/tools/square/types'
+import { LOCATION_OUTPUT, SQUARE_BASE_URL, squareHeaders } from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareListLocationsTool: ToolConfig<ListLocationsParams, LocationListResponse> = {
+  id: 'square_list_locations',
+  name: 'Square List Locations',
+  description: 'List all locations associated with the Square account',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+  },
+
+  request: {
+    url: () => `${SQUARE_BASE_URL}/v2/locations`,
+    method: 'GET',
+    headers: (params) => squareHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const locations = data.locations ?? []
+    return {
+      success: true,
+      output: {
+        locations,
+        metadata: {
+          count: locations.length,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    locations: {
+      type: 'array',
+      description: 'Array of location objects',
+      items: LOCATION_OUTPUT,
+    },
+    metadata: {
+      type: 'json',
+      description: 'List metadata',
+      properties: {
+        count: { type: 'number', description: 'Number of locations returned' },
+      },
+    },
+  },
+}

apps/sim/tools/square/list_payments.ts

@@ -0,0 +1,98 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { ListPaymentsParams, PaymentListResponse } from '@/tools/square/types'
+import {
+  LIST_METADATA_OUTPUT_PROPERTIES,
+  PAYMENT_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareListPaymentsTool: ToolConfig<ListPaymentsParams, PaymentListResponse> = {
+  id: 'square_list_payments',
+  name: 'Square List Payments',
+  description: 'List payments taken by the account, optionally filtered by location and time range',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    locationId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Filter payments by location ID',
+    },
+    beginTime: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'RFC 3339 timestamp for the beginning of the reporting period',
+    },
+    endTime: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'RFC 3339 timestamp for the end of the reporting period',
+    },
+    limit: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Maximum number of results to return per page',
+    },
+    cursor: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Pagination cursor from a previous response',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const url = new URL(`${SQUARE_BASE_URL}/v2/payments`)
+      if (params.locationId) url.searchParams.append('location_id', params.locationId)
+      if (params.beginTime) url.searchParams.append('begin_time', params.beginTime)
+      if (params.endTime) url.searchParams.append('end_time', params.endTime)
+      if (params.limit !== undefined) url.searchParams.append('limit', params.limit.toString())
+      if (params.cursor) url.searchParams.append('cursor', params.cursor)
+      return url.toString()
+    },
+    method: 'GET',
+    headers: (params) => squareHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const payments = data.payments ?? []
+    return {
+      success: true,
+      output: {
+        payments,
+        metadata: {
+          count: payments.length,
+          cursor: data.cursor ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    payments: {
+      type: 'array',
+      description: 'Array of payment objects',
+      items: PAYMENT_OUTPUT,
+    },
+    metadata: {
+      type: 'json',
+      description: 'List pagination metadata',
+      properties: LIST_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/list_refunds.ts

@@ -0,0 +1,105 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { ListRefundsParams, RefundListResponse } from '@/tools/square/types'
+import {
+  LIST_METADATA_OUTPUT_PROPERTIES,
+  REFUND_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareListRefundsTool: ToolConfig<ListRefundsParams, RefundListResponse> = {
+  id: 'square_list_refunds',
+  name: 'Square List Refunds',
+  description: 'List payment refunds, optionally filtered by location, status, and time range',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    locationId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Filter refunds by location ID',
+    },
+    status: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Filter by refund status (PENDING, COMPLETED, REJECTED, or FAILED)',
+    },
+    beginTime: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'RFC 3339 timestamp for the beginning of the reporting period',
+    },
+    endTime: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'RFC 3339 timestamp for the end of the reporting period',
+    },
+    limit: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Maximum number of results to return per page',
+    },
+    cursor: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Pagination cursor from a previous response',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const url = new URL(`${SQUARE_BASE_URL}/v2/refunds`)
+      if (params.locationId) url.searchParams.append('location_id', params.locationId)
+      if (params.status) url.searchParams.append('status', params.status)
+      if (params.beginTime) url.searchParams.append('begin_time', params.beginTime)
+      if (params.endTime) url.searchParams.append('end_time', params.endTime)
+      if (params.limit !== undefined) url.searchParams.append('limit', params.limit.toString())
+      if (params.cursor) url.searchParams.append('cursor', params.cursor)
+      return url.toString()
+    },
+    method: 'GET',
+    headers: (params) => squareHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const refunds = data.refunds ?? []
+    return {
+      success: true,
+      output: {
+        refunds,
+        metadata: {
+          count: refunds.length,
+          cursor: data.cursor ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    refunds: {
+      type: 'array',
+      description: 'Array of refund objects',
+      items: REFUND_OUTPUT,
+    },
+    metadata: {
+      type: 'json',
+      description: 'List pagination metadata',
+      properties: LIST_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/pay_order.ts

@@ -0,0 +1,90 @@
+import { generateId } from '@sim/utils/id'
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { OrderResponse, PayOrderParams } from '@/tools/square/types'
+import {
+  ORDER_METADATA_OUTPUT_PROPERTIES,
+  ORDER_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squarePayOrderTool: ToolConfig<PayOrderParams, OrderResponse> = {
+  id: 'square_pay_order',
+  name: 'Square Pay Order',
+  description: 'Pay for an order using one or more already-approved payments',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    orderId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the order to pay for',
+    },
+    paymentIds: {
+      type: 'array',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'IDs of approved payments to apply to the order',
+    },
+    orderVersion: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Version of the order being paid (for optimistic concurrency)',
+    },
+    idempotencyKey: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Unique key to make the request idempotent (auto-generated if omitted)',
+    },
+  },
+
+  request: {
+    url: (params) => `${SQUARE_BASE_URL}/v2/orders/${encodeURIComponent(params.orderId)}/pay`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => {
+      const body: Record<string, unknown> = {
+        idempotency_key: params.idempotencyKey || generateId(),
+      }
+      if (params.paymentIds) body.payment_ids = params.paymentIds
+      if (params.orderVersion !== undefined) body.order_version = params.orderVersion
+      return body
+    },
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const order = data.order ?? {}
+    return {
+      success: true,
+      output: {
+        order,
+        metadata: {
+          id: order.id,
+          state: order.state ?? null,
+          location_id: order.location_id ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    order: { ...ORDER_OUTPUT, description: 'The paid order object' },
+    metadata: {
+      type: 'json',
+      description: 'Order summary metadata',
+      properties: ORDER_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/publish_invoice.ts

@@ -0,0 +1,81 @@
+import { generateId } from '@sim/utils/id'
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { InvoiceResponse, PublishInvoiceParams } from '@/tools/square/types'
+import {
+  INVOICE_METADATA_OUTPUT_PROPERTIES,
+  INVOICE_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squarePublishInvoiceTool: ToolConfig<PublishInvoiceParams, InvoiceResponse> = {
+  id: 'square_publish_invoice',
+  name: 'Square Publish Invoice',
+  description: 'Publish a draft invoice so it is sent to the customer and becomes payable',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    invoiceId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the invoice to publish',
+    },
+    version: {
+      type: 'number',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Current version of the invoice (use the version returned by Create Invoice)',
+    },
+    idempotencyKey: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Unique key to make the request idempotent (auto-generated if omitted)',
+    },
+  },
+
+  request: {
+    url: (params) =>
+      `${SQUARE_BASE_URL}/v2/invoices/${encodeURIComponent(params.invoiceId)}/publish`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => ({
+      version: params.version,
+      idempotency_key: params.idempotencyKey || generateId(),
+    }),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const invoice = data.invoice ?? {}
+    return {
+      success: true,
+      output: {
+        invoice,
+        metadata: {
+          id: invoice.id,
+          status: invoice.status ?? null,
+          version: invoice.version ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    invoice: { ...INVOICE_OUTPUT, description: 'The published invoice object' },
+    metadata: {
+      type: 'json',
+      description: 'Invoice summary metadata',
+      properties: INVOICE_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/refund_payment.ts

@@ -0,0 +1,97 @@
+import { generateId } from '@sim/utils/id'
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { RefundPaymentParams, RefundResponse } from '@/tools/square/types'
+import {
+  REFUND_METADATA_OUTPUT_PROPERTIES,
+  REFUND_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareRefundPaymentTool: ToolConfig<RefundPaymentParams, RefundResponse> = {
+  id: 'square_refund_payment',
+  name: 'Square Refund Payment',
+  description: 'Refund all or part of a completed payment',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    paymentId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the payment to refund',
+    },
+    amount: {
+      type: 'number',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Amount to refund in the smallest currency denomination (e.g. 100 = $1.00)',
+    },
+    currency: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Three-letter ISO 4217 currency code (e.g. USD)',
+    },
+    idempotencyKey: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Unique key to make the request idempotent (auto-generated if omitted)',
+    },
+    reason: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Reason for the refund',
+    },
+  },
+
+  request: {
+    url: () => `${SQUARE_BASE_URL}/v2/refunds`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => {
+      const body: Record<string, unknown> = {
+        idempotency_key: params.idempotencyKey || generateId(),
+        payment_id: params.paymentId,
+        amount_money: { amount: params.amount, currency: params.currency },
+      }
+      if (params.reason) body.reason = params.reason
+      return body
+    },
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const refund = data.refund ?? {}
+    return {
+      success: true,
+      output: {
+        refund,
+        metadata: {
+          id: refund.id,
+          status: refund.status ?? null,
+          payment_id: refund.payment_id ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    refund: { ...REFUND_OUTPUT, description: 'The created refund object' },
+    metadata: {
+      type: 'json',
+      description: 'Refund summary metadata',
+      properties: REFUND_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/search_catalog_objects.ts

@@ -0,0 +1,96 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CatalogListResponse, SearchCatalogObjectsParams } from '@/tools/square/types'
+import {
+  CATALOG_OBJECT_OUTPUT,
+  LIST_METADATA_OUTPUT_PROPERTIES,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareSearchCatalogObjectsTool: ToolConfig<
+  SearchCatalogObjectsParams,
+  CatalogListResponse
+> = {
+  id: 'square_search_catalog_objects',
+  name: 'Square Search Catalog Objects',
+  description: 'Search catalog objects by type and query filters',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    objectTypes: {
+      type: 'array',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Array of catalog object types to search (e.g. ["ITEM","CATEGORY"])',
+    },
+    query: {
+      type: 'json',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Square catalog query object (e.g. {"text_query":{"keywords":["coffee"]}} or {"prefix_query":{...}})',
+    },
+    limit: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Maximum number of results to return per page',
+    },
+    cursor: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Pagination cursor from a previous response',
+    },
+  },
+
+  request: {
+    url: () => `${SQUARE_BASE_URL}/v2/catalog/search`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => {
+      const body: Record<string, unknown> = {}
+      if (params.objectTypes) body.object_types = params.objectTypes
+      if (params.query) body.query = params.query
+      if (params.limit !== undefined) body.limit = params.limit
+      if (params.cursor) body.cursor = params.cursor
+      return body
+    },
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const objects = data.objects ?? []
+    return {
+      success: true,
+      output: {
+        objects,
+        metadata: {
+          count: objects.length,
+          cursor: data.cursor ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    objects: {
+      type: 'array',
+      description: 'Array of matching catalog objects',
+      items: CATALOG_OBJECT_OUTPUT,
+    },
+    metadata: {
+      type: 'json',
+      description: 'List pagination metadata',
+      properties: LIST_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/search_customers.ts

@@ -0,0 +1,86 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CustomerListResponse, SearchCustomersParams } from '@/tools/square/types'
+import {
+  CUSTOMER_OUTPUT,
+  LIST_METADATA_OUTPUT_PROPERTIES,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareSearchCustomersTool: ToolConfig<SearchCustomersParams, CustomerListResponse> = {
+  id: 'square_search_customers',
+  name: 'Square Search Customers',
+  description: 'Search customer profiles using filters such as email, phone, or creation date',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    query: {
+      type: 'json',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Square customer query object with optional filter and sort (e.g. {"filter":{"email_address":{"exact":"a@b.com"}}})',
+    },
+    limit: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Maximum number of results to return per page',
+    },
+    cursor: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Pagination cursor from a previous response',
+    },
+  },
+
+  request: {
+    url: () => `${SQUARE_BASE_URL}/v2/customers/search`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => {
+      const body: Record<string, unknown> = {}
+      if (params.query) body.query = params.query
+      if (params.limit !== undefined) body.limit = params.limit
+      if (params.cursor) body.cursor = params.cursor
+      return body
+    },
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const customers = data.customers ?? []
+    return {
+      success: true,
+      output: {
+        customers,
+        metadata: {
+          count: customers.length,
+          cursor: data.cursor ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    customers: {
+      type: 'array',
+      description: 'Array of matching customer objects',
+      items: CUSTOMER_OUTPUT,
+    },
+    metadata: {
+      type: 'json',
+      description: 'List pagination metadata',
+      properties: LIST_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/search_invoices.ts

@@ -0,0 +1,88 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { InvoiceListResponse, SearchInvoicesParams } from '@/tools/square/types'
+import {
+  INVOICE_OUTPUT,
+  LIST_METADATA_OUTPUT_PROPERTIES,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareSearchInvoicesTool: ToolConfig<SearchInvoicesParams, InvoiceListResponse> = {
+  id: 'square_search_invoices',
+  name: 'Square Search Invoices',
+  description: 'Search invoices across one or more locations',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    locationId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the location to search within (Square allows one location per search)',
+    },
+    limit: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Maximum number of results to return per page',
+    },
+    cursor: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Pagination cursor from a previous response',
+    },
+  },
+
+  request: {
+    url: () => `${SQUARE_BASE_URL}/v2/invoices/search`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => {
+      const body: Record<string, unknown> = {
+        query: {
+          filter: { location_ids: [params.locationId] },
+        },
+      }
+      if (params.limit !== undefined) body.limit = params.limit
+      if (params.cursor) body.cursor = params.cursor
+      return body
+    },
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const invoices = data.invoices ?? []
+    return {
+      success: true,
+      output: {
+        invoices,
+        metadata: {
+          count: invoices.length,
+          cursor: data.cursor ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    invoices: {
+      type: 'array',
+      description: 'Array of matching invoice objects',
+      items: INVOICE_OUTPUT,
+    },
+    metadata: {
+      type: 'json',
+      description: 'List pagination metadata',
+      properties: LIST_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/search_orders.ts

@@ -0,0 +1,94 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { OrderListResponse, SearchOrdersParams } from '@/tools/square/types'
+import {
+  LIST_METADATA_OUTPUT_PROPERTIES,
+  ORDER_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareSearchOrdersTool: ToolConfig<SearchOrdersParams, OrderListResponse> = {
+  id: 'square_search_orders',
+  name: 'Square Search Orders',
+  description: 'Search orders across one or more locations using filters and sorting',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    locationIds: {
+      type: 'array',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Array of location IDs to search within',
+    },
+    query: {
+      type: 'json',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Square order query object with optional filter and sort (e.g. {"filter":{"state_filter":{"states":["OPEN"]}}})',
+    },
+    limit: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Maximum number of results to return per page',
+    },
+    cursor: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Pagination cursor from a previous response',
+    },
+  },
+
+  request: {
+    url: () => `${SQUARE_BASE_URL}/v2/orders/search`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => {
+      const body: Record<string, unknown> = {
+        location_ids: params.locationIds,
+      }
+      if (params.query) body.query = params.query
+      if (params.limit !== undefined) body.limit = params.limit
+      if (params.cursor) body.cursor = params.cursor
+      return body
+    },
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const orders = data.orders ?? []
+    return {
+      success: true,
+      output: {
+        orders,
+        metadata: {
+          count: orders.length,
+          cursor: data.cursor ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    orders: {
+      type: 'array',
+      description: 'Array of matching order objects',
+      items: ORDER_OUTPUT,
+    },
+    metadata: {
+      type: 'json',
+      description: 'List pagination metadata',
+      properties: LIST_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/update_customer.ts

@@ -0,0 +1,138 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CustomerResponse, UpdateCustomerParams } from '@/tools/square/types'
+import {
+  CUSTOMER_METADATA_OUTPUT_PROPERTIES,
+  CUSTOMER_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareUpdateCustomerTool: ToolConfig<UpdateCustomerParams, CustomerResponse> = {
+  id: 'square_update_customer',
+  name: 'Square Update Customer',
+  description: 'Update fields on an existing customer profile',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    customerId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the customer to update',
+    },
+    givenName: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'First name of the customer',
+    },
+    familyName: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Last name of the customer',
+    },
+    companyName: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Business name of the customer',
+    },
+    nickname: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Nickname of the customer',
+    },
+    emailAddress: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Email address of the customer',
+    },
+    phoneNumber: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Phone number of the customer',
+    },
+    birthday: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Birthday in YYYY-MM-DD or MM-DD format',
+    },
+    note: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Note about the customer',
+    },
+    referenceId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Optional external reference for the customer',
+    },
+    address: {
+      type: 'json',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Square address object for the customer',
+    },
+  },
+
+  request: {
+    url: (params) => `${SQUARE_BASE_URL}/v2/customers/${encodeURIComponent(params.customerId)}`,
+    method: 'PUT',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => {
+      const body: Record<string, unknown> = {}
+      if (params.givenName !== undefined) body.given_name = params.givenName
+      if (params.familyName !== undefined) body.family_name = params.familyName
+      if (params.companyName !== undefined) body.company_name = params.companyName
+      if (params.nickname !== undefined) body.nickname = params.nickname
+      if (params.emailAddress !== undefined) body.email_address = params.emailAddress
+      if (params.phoneNumber !== undefined) body.phone_number = params.phoneNumber
+      if (params.birthday !== undefined) body.birthday = params.birthday
+      if (params.note !== undefined) body.note = params.note
+      if (params.referenceId !== undefined) body.reference_id = params.referenceId
+      if (params.address !== undefined) body.address = params.address
+      return body
+    },
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const customer = data.customer ?? {}
+    return {
+      success: true,
+      output: {
+        customer,
+        metadata: {
+          id: customer.id,
+          email_address: customer.email_address ?? null,
+          given_name: customer.given_name ?? null,
+          family_name: customer.family_name ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    customer: { ...CUSTOMER_OUTPUT, description: 'The updated customer object' },
+    metadata: {
+      type: 'json',
+      description: 'Customer summary metadata',
+      properties: CUSTOMER_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/square/upsert_catalog_object.ts

@@ -0,0 +1,78 @@
+import { generateId } from '@sim/utils/id'
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import type { CatalogObjectResponse, UpsertCatalogObjectParams } from '@/tools/square/types'
+import {
+  CATALOG_OBJECT_METADATA_OUTPUT_PROPERTIES,
+  CATALOG_OBJECT_OUTPUT,
+  SQUARE_BASE_URL,
+  squareHeaders,
+} from '@/tools/square/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const squareUpsertCatalogObjectTool: ToolConfig<
+  UpsertCatalogObjectParams,
+  CatalogObjectResponse
+> = {
+  id: 'square_upsert_catalog_object',
+  name: 'Square Upsert Catalog Object',
+  description: 'Create or update a catalog object such as an item, variation, or category',
+  version: '1.0.0',
+  errorExtractor: ErrorExtractorId.SQUARE_ERRORS,
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Square access token (personal access token)',
+    },
+    object: {
+      type: 'json',
+      required: true,
+      visibility: 'user-or-llm',
+      description:
+        'Square catalog object to create or update. Use ID "#name" for new objects (e.g. {"type":"ITEM","id":"#Coffee","item_data":{"name":"Coffee"}})',
+    },
+    idempotencyKey: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Unique key to make the request idempotent (auto-generated if omitted)',
+    },
+  },
+
+  request: {
+    url: () => `${SQUARE_BASE_URL}/v2/catalog/object`,
+    method: 'POST',
+    headers: (params) => squareHeaders(params.apiKey),
+    body: (params) => ({
+      idempotency_key: params.idempotencyKey || generateId(),
+      object: params.object,
+    }),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    const object = data.catalog_object ?? {}
+    return {
+      success: true,
+      output: {
+        object,
+        metadata: {
+          id: object.id,
+          type: object.type ?? null,
+          version: object.version ?? null,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    object: { ...CATALOG_OBJECT_OUTPUT, description: 'The created or updated catalog object' },
+    metadata: {
+      type: 'json',
+      description: 'Catalog object summary metadata',
+      properties: CATALOG_OBJECT_METADATA_OUTPUT_PROPERTIES,
+    },
+  },
+}