Square Data Provider

[nickmazurenko]

Add Square Data Provider Integration

Summary

Add a complete Square payments and commerce platform integration consisting of two new modules:

• SquareRestClient - REST client with OAuth2 authentication
• SquareDataProvider - Data provider with 26 actions and 7 triggers

Details

Square is a comprehensive commerce platform for payments, online stores, invoicing, and business management. This integration covers:

Resources: Customers, Orders, Payments, Invoices, Bookings, Catalog, Services, Refunds, Inventory

REST Client (SquareRestClient.qm):

• OAuth2 authentication with squareres:// URL scheme
• Base URL: https://connect.squareup.com/v2
• Auto-refresh tokens with access_type: "offline" / prompt: "consent"
• Rate limit handling with exponential backoff
• Cursor-based pagination helpers for both GET and POST endpoints

Actions (26):

Group	Actions
Customers	Create, Update, Get, Find by ID, List, Add to Group, Remove from Group
Orders	Create, Create Paid, Get (batch), Search, Find by ID
Payments	Complete, Refund, List, Get
Invoices	Create, Send, List
Bookings	Create, List
Catalog	Search
Inventory	Change
Refunds	List
Services	Find
Other	API Request (execute-api-call)

Triggers (7):

• Watch Customers (new customer created)
• Watch Orders (order created or updated)
• Watch Payments (payment created or updated)
• New Appointment (booking created)
• New Catalog Item (item added)
• New Invoice (invoice created)
• Watch New Events (Square Events API - 17 event types)

User-friendly design:

• Money objects flattened to separate amount (cents) + currency fields
• Appointment segments flattened to top-level booking fields
• Idempotency keys auto-generated for all mutations
• location_id auto-detected when not provided
• Reference data dropdowns for locations and customers

Files

New files (44):

• qlib/SquareRestClient.qm
• qlib/SquareDataProvider/ (42 files: .qm, .qc, .svg)
• examples/test/qlib/SquareDataProvider/SquareDataProvider.qtest

Modified files (6):

• qlib/ConnectionProvider/ConnectionSchemeCache.qc - added squareres scheme
• qlib/DataProvider/DataProvider.qc - added square factory
• CMakeLists.txt - 2 qore_user_module() entries
• Makefile.am - 5 sections updated
• doxygen/lang/120_modules.dox.tmpl - module documentation entries
• doxygen/lang/900_release_notes.dox.tmpl - release notes

Testing

Integration tests in examples/test/qlib/SquareDataProvider/SquareDataProvider.qtest:

• Unit tests (no credentials): factory, metadata, child providers, data types, trigger examples, negative cases, connection scheme
• Integration tests (sandbox credentials): CRUD customers, list payments, list refunds, execute API call, cleanup

Run with:

export SQUARE_ACCESS_TOKEN=... SQUARE_CLIENT_ID=... SQUARE_CLIENT_SECRET=... SQUARE_LOCATION_ID=...
qore examples/test/qlib/SquareDataProvider/SquareDataProvider.qtest -v