square_connect 0.2.5+4

Pub GitHub PRs Welcome

Square Connect Flutter #

This project is a wip extending the Square Connect APIs. You can learn more about them here https://developer.squareup.com/docs/api/connect/v2.

Getting Started #

First, ensure you've added the dependency to your project

dependencies:
    square-connect: <latest-version>

Initialize #

Start by getting an instance of the SquareConnect client

var client = SquareConnect.instance;

Then set two config options:

REQUIRED First, enter your developer token. You can find this at https://developer.squareup.com/apps. (More/better authentication options planned for the future).

client.setAuthToken(token: 'YOUR-TOKEN-HERE');

ALTERNATIVELY You can combine the .instance and the setAuthToken(token) to one call that does both, which is often more convenient.

client.getInstanceWithToken('YOUR-TOKEN-HERE');

OPTIONAL Second, you may add a different HttpClient to use. By defauly, the IOClient is used (the object that flutter needs to make http calls). This is useful for testing (you can enter a Mock client) or using BrowserClient if developing for web.

var httpClient = BrowserClient();
client.setAuthToken(client: httpClient);

ADITIONAL TIP If using Flutter, and excelent strategy is to use the Provider package to manage the SquareConnect client. You can initalize like so :

Provider<SquareConnect>.value(
  value: SquareConnect.getInstanceWithToken('YOUR-TOKEN-HERE'),
  child: MaterialApp(
    home: Home(),
  )
)

and then retrieve anywhere in the widget tree like so:

Provider.of<SquareConnect>(context).xxxApi.someMethod();

This way, you only need to enter your token once, and you can use the same client anywhere your app. Of course, you could use a MultiProvider intead if you had multiple items to provide.

Usage #

Now that you have a SquareConnect client set up, you can access it's methods. The seperate APIs are contained in their own objects for better organization. For example, to access the Catalog API, you can use:

client.catalogApi.methodHere();

Errors #

Instead of throwing errors caused by Square's API, methods return a list of errors returned by Square's API. To check if errors were thrown, you can call .hasErrors on the Response object, or simply check if the errors property is null.

Example

var response = await client.catalogApi.retrieveCatalogObject(objectId: 'fake-obj-id');
if (response.hasErrors) {
  // at least 1 error occured
  response.errors.forEach((error) => print(error.detail));
} else {
  // no errors occured, you can access your payload
  var object = response.object;
}

Pagination #

On methods that support it, you can paginate your calls. On some calls, there are hard limits to how many items can be returned (eg. listCatalog() can return 200 objects by default). You can programatically find limits with the getCatalogInfo() method.

If pagination is supported/needed, the response will contain a cursor string returned by Square's API. To retrieve it, you can call response.cursor. If the field is null, then no cursor exists and there are no more items to be returned. If it was not null, you can pass it into another call of the specific method.

Of course you can use this cursor for lazy loading or write a recursive function to get all objects either time. We build the pagination exactly as Square implements it to allow for flexibility.

Example

List<CatalogObject> listOfObjects = [];

var firstResponse = await client.catalogApi.listCatalogObjects();
if (firstResponse.cursor != null) {
  // Max elements for this call, but there are more to return
  listOfObjects.addAll(firstResponse.objects);
  
  var secondResponse = await client.catalogApi.listCatalogObjects(cursor: firstResponse.cursor);
  if (secondResponse.cursor != null) {
    // could go on more, could write function recursivly
    
  } else {
    // All the elements have been returned
    listOfObjects.addAll(secondResponse.objects);
  }
}

Methods Supported (for more info, see API documentation, and Square's documentation):

Catalog API (SquareConnect.catalogApi) #

MethodDescription
listCatalog(types, cursor)Gets all catalog objects, can filter with specifying types list and pagination support.
retrieveCatalogObject(objectId, includeRelatedObjects)Gets specified catalog object by id.
deleteCatalogObject(objectId)Deletes secified catalog object by id.
batchDeleteCatalogObjects(objectIds)Batch deletes catalog objects from list of ids.
getCatalogInfo()Gets metadata about catalog.
searchCatalogObjects(various inputs)Seaches catalog objects in a variety of ways. See documentation.
batchUpsertCatalogObjects(batches)Creates or updates catalog objects in bulk.
batchRetrieveCatalogObjects(objectIds, includeRelatedObjects)Retrieves Catalog Objects in bulk.
upsertCatalogObject(object)Creates or updates a catalog object.
updateItemModifierLists(itemIds, modifierListsToEnable, modifierListsToDisable)Seaches catalog objects in a variety of ways. See documentation.
updateItemTaxes(itemIds, taxesToEnable, taxesToDisable)Updates the taxes that apply to an item.

Customer API (SquareConnect.customerApi) #

MethodDescription
createCustomer(various inputs)Creates a customer object with specified information and returns the created customer.
createCustomerCard(customerId, card inputs)Creates a card on file for specified customer and returns the created card.
deleteCustomer(customerId)Deletes secified customer object by id.
deleteCustomerCard(customerId, cardId)Deletes secified card on file belonging to customer by id.
listCustomers(cursor, sortField, sortOrder)Lists customers by optional cursor, sort field, and sort order.
retrieveCustomer(customerId)Retrieves customer object by id.
searchCustomers(various query inputs, cursor, limit)Searches for customer by filters and sorts, as well as cursor and limit.
updateCustomer(customerId, various inputs)Updates specified customer object (by id) and returns the created customer.

Locations API (SquareConnect.locationsApi) #

MethodDescription
listLocations()Lists all a merchant's locations.

Orders API (SquareConnect.ordersApi) #

MethodDescription
createOrder(various inputs)Creates and order from Catalog ids. Custom line items not yet supported.
searchOrders(various inputs)Searches for orders with different filter and sorting options.
batchRetrieveOrders(locationId, orderIds)Retrieves one or more orders given their Order ID.
updateOrder(various inputs)Updates an order given a Order Id and version.
payOrder(various inputs)Pays for an order with either multiple payment ids or a 0 balance.

Payments API (SquareConnect.paymentsApi) #

MethodDescription
listPayments(various inputs)Lists payments meeting certain crieteria.
createPayment(various inputs)Creates and optionally processes a payment from card on file or in app payments sdk.
cancelPaymentByIdempotencyKey(idempotencyKey)Cancels a payment by given idempotency key.
getPayment(paymentId)Retrieves a payment given its id.
cancelPayment(paymentId)Cancels a payment given its id.
completePayment(paymentId)Completes a payment given its id.

Refunds API (SquareConnect.refundsApi) #

MethodDescription
listPaymentRefunds(various inputs)Lists payment refunds meeting certain crieteria.
refundPayment(various inputs)Refunds a payment given a payment id and amounts to refund.
getPaymentRefund(paymentRefundId)Retrieves a payment refund given its id.

Employees API (SquareConnect.employeesApi) #

MethodDescription
listEmployees(locationId, status, limit, cursor,)Gets a list of Employee objects for a business.
retrieveEmployee(employeeId)Gets an Employee from Employee Id.

Inventory API (SquareConnect.inventoryApi) #

MethodDescription
batchChangeInventory(various inputs)Changes the inventory of multiple items in bulk.
batchRetrieveInventoryChanges(various inputs)Retrieves inventory changes in bulk from various inputs.
batchRetrieveInventoryCounts(various inputs)Retrieves inventory counts in bulk from various inputs.
retrieveInventoryAdjustment(adjustmentId)Retrieves an inventory adjustment given its id.
retrieveInventoryChanges(catalogObjectId, locationIds)Retrieves inventory changes to a catalog object given its id some locations.
retrieveInventoryCount(catalogObjectId, locationIds)Retrieves inventory counts for a catalog object given its id some locations.
retrieveInventoryPhysicalCount(catalogObjectId, locationIds)Retrieves inventory counts for a catalog object given its id some locations.

Labor API (SquareConnect.laborApi) #

MethodDescription
createBreakType(various inputs)Creates a break type.
createShift(various inputs)Creates a shift for an employee.
deleteBreakType(breakTypeId)Deletes a break type by its id.
deleteShift(shiftId)Deletes a shift by its id.
getBreakType(breakTypeId)Retrieves a break type by its id.
getEmployeeWage(employeeWageId)Retrieves an employee wage by its id.
getShift(shiftId)Retrieves a shift by its id.
listBreakTypes(various inputs)Lists the break types at a location.
listEmployeeWages(various inputs)Lists the employee wages for an employee.
listWorkweekConfigs(limit, cursor)Lists the workweek configs for a business.
seachShifts(various inputs)Searches for shifts based on the inputs.
updateBreakType(various inputs)Updates a break type by its id.
updateShift(various inputs)Updates a shift by its id.
updateWorkweekConfig(various inputs)Updates a workweek config based on its id.

Transactions API (SquareConnect.transactionsApi) #

NOTE: This set of APIs has been deprecated by Square. #

MethodDescription
captureTransaction(locationId, transactionId)Fully processes Transaction when deloyCapture is set to true in the charge() method.
charge(various inputs)Charges a card represented by a card nonce or a customer's card on file.
createRefund(various inputs)Retrieves one or more orders given their Order ID.
listRefunds(various inputs)Lists refunds for one of a business's locations.
listTransactions(various inputs)Lists transactions for a particular location.
retrieveTransaction(locationId, transactionId)Retrieves details for a single transaction.
listRefunds(various inputs)Cancels a Transaction that was created with the charge() method with a delayCapture value of true.

0.2.5+4 #

  • Fixed bug in CatalogItem

0.2.5+3 #

  • Fixed bug in UpdateOrder - changed from POST request to PUT

0.2.5+2 #

  • Fixed bug in UpdateOrder

0.2.5+1 #

  • Fixed bug in UpdateOrder

0.2.5 #

  • Added Refunds API and Payments API
    • Initial implementation. Still needs documentation and tests.
  • Added changes to Orders API from 8/14 update
    • Added payOrder() and updateOrder() methods, as well as shippment fulfillemnt type.
  • BREAKING CHANGE: Deprecated FulfillmentRequest and renamed input in createOrder() to fulfillemntRequest. fulfillment property now refers to a OrderFulfillment object.
  • Added a Card factory method from In App Payments Card.

0.2.4 #

  • Added toJson() methods to every data object so they can easily be saved in formats that require simple maps, such as Cloud Firestore. Can be converted back with fromJson().
  • Added autoCompleteDuration, prepTimeDuration, and pickupWindowDuration to FulfillmentRequest.

0.2.3+2 #

  • Fixed bug in hasErrors method in new response superclass

0.2.3+1 #

  • Fixed bug in BatchRetrieveCatalogObjectsResponse

0.2.3 #

  • Added full implementation of the Inventory API
    • Still needs documentation and testing
  • Refactored how response objects work behind the scenes
  • Not code related, but added a bunch more to the github projects, including some issues for direction on helping.

0.2.2 #

  • Added auth methods to help with OAuth and Reader SDK methods:
    • Use SquareConnect().getAuthEndpoint(clientId, permissions, locale, session, state) to get the url for requesting permissions for OAuth.
    • Use SquareConnect().createMobileAuthorizationCode(locationId) to get Mobile Auth Code.

0.2.1 #

  • Added option for using refresh tokens instead of auth token - consider this beta at this point.
    • To use, call SquareConnect.getInstanceWithRefreshToken(refreshToken, clientId, clientSecret)
    • Make Sure You Secure Your Client Secret!
  • Removed cursor from Requst Obj helper funciton. Won't change any API, just makes things simplier to maintain.

0.2.0 #

  • Adding full implementation for Labor API.
    • Still need tests and documentation.
  • Finished out CatalogApi methods.
  • Added timerange and durations where appropriate.

0.1.3 #

  • Adding full implementation for Employees API.
    • Still needs tests.
    • Added documentation to Transactions API.

0.1.2 #

  • Adding full implementation for Transactions API.
    • Still needs documentation and tests.

0.1.1 #

  • Adding more documentation.
  • Fixing scope issues for some enums.
  • Initial work behind the scenes for Transactions API.

0.1.0 #

  • WooHoo first major release!!!
    • This doesn't mean the package is anywhere near complete, but the direction seems clear and now it's time to plug and chug.
    • Still missing many API endpoints, documentation on a few items, and testing on lots of items.
  • Added a bunch of documentation
  • Refactored enums
    • Converter methods are now out of public facing API scope
    • Now only the enums themselves will be accessible through the API
  • Added shared enums and shared objects
    • This shouldn't affect public facing API, just internally making general things easier to find
  • Moved Api Objects into documenation scope
    • There should now be documentation of API methods in the docs
    • Also made tokens and clients private so they cannot be accessed once set
  • Added and optional SquareConnect constructor that allows you to input token when you get your instance
    • The method is SquareConnect.getInstanceWithToken(String token)
  • Added periodsAsMap to [BusinessHours] object in [LocationsApi] to easily get periods grouped into days of the week.
  • Various minor improvements throughout

0.0.12 #

  • Adding on by default and ordinal to modifier

0.0.11 #

  • small fixes to Catalog Object parsing

0.0.10 #

  • inital implementing Create Orders API

0.0.9 #

  • Added initial work on implementing Orders API

0.0.8 #

  • Added .hasErrors to Response objects for easier error handeling
  • Added searchCatalogObjects() method
    • Still needs tests and documentation

0.0.7 #

  • Minor changes to Locations API

0.0.6 #

  • Added full support for Locations API
    • Missing test suite
    • Full functionality for all functions
    • Missing full documentation

0.0.5 #

  • Added full support for Customer API!
    • Full test suite
    • Full functionality for all functions
    • Missing full documentation

0.0.4 #

  • Added some formating on multiple files

0.0.3 #

  • Fixed return type on lots of methods

0.0.2 #

  • Added android and ios folders

0.0.1 #

  • Initial Release
  • Initial framework decisions and implementaion of most of the Catalog API

example/README.md

example #

A new Flutter project.

Getting Started #

This project is a starting point for a Flutter application.

A few resources to get you started if this is your first Flutter project:

For help getting started with Flutter, view our online documentation, which offers tutorials, samples, guidance on mobile development, and a full API reference.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  square_connect: ^0.2.5+4

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:square_connect/square_connect.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
48
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
74
Learn more about scoring.

We analyzed this package on Aug 21, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.4.0
  • pana: 0.12.19
  • Flutter: 1.7.8+hotfix.4

Platforms

Detected platforms: Flutter

References Flutter, and has no conflicting libraries.

Health suggestions

Format lib/src/catalog/catalog-objects.dart.

Run flutter format to format lib/src/catalog/catalog-objects.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.2.2 <3.0.0
flutter 0.0.0
http ^0.12.0+2 0.12.0+2
square_in_app_payments ^1.2.2 1.2.2
uuid ^2.0.2 2.0.2
Transitive dependencies
async 2.3.0
built_collection 4.2.2
built_value 6.7.0
charcode 1.1.2
collection 1.14.11 1.14.12
convert 2.1.1
crypto 2.1.2
fixnum 0.10.9
http_parser 3.1.3
matcher 0.12.5
meta 1.1.6 1.1.7
path 1.6.4
pedantic 1.8.0+1
quiver 2.0.5
sky_engine 0.0.99
source_span 1.5.5
stack_trace 1.9.3
string_scanner 1.0.5
term_glyph 1.1.0
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
flutter_test
mockito ^4.1.0