The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Jun 15, 2026 8:15am

@greptile

PR Summary

Medium Risk
New payment/refund and money-moving operations plus server-side handling of Square access tokens and file uploads, but changes are additive and follow existing integration patterns.

Overview
Adds a new Square commerce integration authenticated with a personal access token, exposed as a workflow block with an operation dropdown and 34 mapped tools (payments, refunds, customers, locations, orders, invoices, catalog, inventory).

Most calls hit Square’s REST API directly from tool configs; catalog image upload is the exception—a new internal POST /api/tools/square/catalog-image route downloads the user’s file from storage (with auth and file access checks), then forwards multipart data to Square.

Docs, SquareIcon, integration metadata, block registry, tool registry, and a square-errors API error extractor are wired in alongside templates/skills on the block.

^{Reviewed by Cursor Bugbot for commit 6b161a7. Configure here.}

@cursor review

Greptile Summary

This PR adds a comprehensive Square commerce integration with 34 operations across Payments, Refunds, Customers, Locations, Orders, Invoices, Catalog, and Inventory. The implementation follows established patterns in the codebase — a multi-operation block with per-field conditions and a shared params coercion function, individual tool files for each operation, a dedicated square-errors extractor, and a specialized internal API route for multipart catalog image uploads.

• Block (square.ts): Uses a robust parseJsonField / coerceNumber / coerceBoolean helper pattern with per-field error messages so users know exactly which input is malformed; all 34 tools are wired to the registry and the block operation selector.
• Route (catalog-image/route.ts): Follows the same Box-style file-download-then-multipart pattern, properly checks response.ok before parsing the body, preserves Square's HTTP status code on errors, and uses assertToolFileAccess for authorization.
• Types (types.ts): Shared output-property constants and TypeScript interfaces are thorough and consistently used across all 34 tool files.

Confidence Score: 5/5

Safe to merge — the integration is additive (no changes to existing paths) and follows established tool/block patterns throughout.

All 34 tools correctly use encodeURIComponent on path parameters, auto-generate idempotency keys, set visibility: 'user-only' on credentials, and wire into the registry. The catalog-image route properly handles auth, file authorization, MIME type derivation, and Square error forwarding. The single observation (search_invoices not exposing its filter/sort surface) is cosmetic and does not affect correctness or security.

apps/sim/tools/square/search_invoices.ts — the exposed interface is more limited than the underlying Square Search Invoices endpoint allows.

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Block["Square Block\n(operation dropdown)"] --> Coerce["tools.config.params\nJSON parse · number coerce · boolean coerce"]
    Coerce --> ToolSel["tools.config.tool\nsquare_\${operation}"]

    ToolSel --> PayTools["Payment Tools\ncreate / get / list / cancel / complete"]
    ToolSel --> RefTools["Refund Tools\nrefund / get / list"]
    ToolSel --> CustTools["Customer Tools\ncreate / get / list / search / update / delete"]
    ToolSel --> LocTools["Location Tools\nlist / get"]
    ToolSel --> OrdTools["Order Tools\ncreate / get / search / pay"]
    ToolSel --> InvTools["Invoice Tools\ncreate / get / list / search / publish / cancel / delete"]
    ToolSel --> CatTools["Catalog Tools\nupsert / get / list / search / delete"]
    ToolSel --> ImgTool["Catalog Image\n(create_catalog_image)"]
    ToolSel --> InvCounts["Inventory\nbatch_retrieve_counts"]

    PayTools --> SquareAPI["Square REST API\nconnect.squareup.com\n+ Square-Version header"]
    RefTools --> SquareAPI
    CustTools --> SquareAPI
    LocTools --> SquareAPI
    OrdTools --> SquareAPI
    InvTools --> SquareAPI
    CatTools --> SquareAPI
    InvCounts --> SquareAPI

    ImgTool --> InternalRoute["/api/tools/square/catalog-image\nDownload file · Build multipart form"]
    InternalRoute --> SquareCatImg["Square Catalog Images API\nPOST /v2/catalog/images"]

    SquareAPI --> ErrExt["square-errors extractor\nerrors[0].detail + code"]

_{Reviews (11): Last reviewed commit: "fix(square): validate parsed JSON field ..." | Re-trigger Greptile}

Greptile Summary

This PR adds a complete Square integration with 34 operations spanning Payments, Refunds, Customers, Locations, Orders, Invoices, Catalog, and Inventory. Authentication uses a personal access token (PAT) via user-only visibility, consistent with the project's credential policy.

• Adds 34 tool files, a multi-operation block with conditional subfields, a square-errors extractor, and an internal catalog-image route that follows the established Box upload pattern with UserFile + multipart forwarding.
• Wires the block and tools into their respective registries, adds the Square integration to integrations.json, and updates the API validation contract baseline.
• Includes 7 block templates and 4 agent skills in SquareBlockMeta, plus full docs and icon additions across both the sim and docs apps.

Confidence Score: 4/5

• The Square integration is a well-structured addition that faithfully follows established codebase patterns for tool definitions, block configs, error extraction, and file-upload proxying. Auth is handled correctly (user-only PAT, internal route guard, file-access assertions), URL parameters are encoded properly, and idempotency keys are auto-generated where needed. The two issues found are edge-case UX/diagnostic concerns rather than correctness problems.
• The catalog-image route parses the Square response body as JSON before checking whether the response was successful, which can mask upstream HTTP status codes in rare error conditions. The block's JSON-parsing try-catch collapses all nine JSON fields into one error message, making it hard for users to identify which field is malformed. Neither issue causes incorrect behaviour under normal operation, but both would frustrate debugging in production.
• apps/sim/app/api/tools/square/catalog-image/route.ts (parse-order issue) and apps/sim/blocks/blocks/square.ts (single try-catch across all JSON fields).

Important Files Changed

Sequence Diagram

sequenceDiagram
    participant UI as Block UI
    participant Exec as Tool Executor (index.ts)
    participant Proxy as /api/tools/square/catalog-image
    participant Square as Square API

    UI->>Exec: "run square_${operation}"
    Exec->>Exec: check !response.ok → errorExtractor(SQUARE_ERRORS)
    alt Direct Square tool (e.g. create_payment)
        Exec->>Square: POST /v2/payments (Bearer token)
        Square-->>Exec: "200 OK {payment}"
        Exec->>Exec: transformResponse → return output
    else Catalog image upload
        Exec->>Proxy: POST /api/tools/square/catalog-image
        Proxy->>Proxy: checkInternalAuth + assertToolFileAccess
        Proxy->>Proxy: downloadFileFromStorage
        Proxy->>Square: POST /v2/catalog/images (multipart)
        Square-->>Proxy: "200 OK {image}"
        Proxy-->>Exec: "200 {success:true, output:{object, metadata}}"
        Exec->>Exec: transformResponse checks data.success
    end
    Exec-->>UI: tool output

_{Reviews (2): Last reviewed commit: "feat(square): add Square integration wit..." | Re-trigger Greptile}

@greptile recheck

@cursor review

@greptile

@greptile

@cursor review

@greptile

@greptile review

@greptile

@cursor review

@greptile

@cursor review

@greptile

@cursor review

@greptile

@cursor review