square_connect 1.1.0

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.

What is it? #

The past #

This package has recently pivoted directions due to security concerns in previous iterations. In the past, this package worked by sending HTTP requests directly from a device through Flutter, which you should NOT do. This is because you should not store your API key in your mobile app under any circumstances!. Both myself and Square put lots of time trying to figure out how to securly store your API key on device; no matter how you do it, there are security problems.

What can this package be used for now? #

This package is still useful for developing with Square and Flutter in my experience. It serves nicely as great wrapper for all the data objects and enums that Square uses in their APIs. This gives you native Dart objects for Customers, Orders, and more.

Usage #

Every call avalible to you in Square's set of APIs has a defined response object. For example, the List Refunds endpoint has an associated class called ListCustomersResponse. Every response object has supports error handling and cursors when appropriate (see below). Here's the process to use the API:

  1. Set up server backend to handle requests from Flutter and send requests to Square APIs
  2. Send response from Square API back to Flutter device.
  3. Parse response using json.decode()
  4. Pass decode results into Enpoint'sRepsonseObject.fromJson()

Example

import 'package:square_connect/square_connect.dart';

async listCustomers() {
  String response = await CustomBackend.listCustomers();

  var responseObj = ListCustomersResponse.fromJson(json.decode(reponse));

  return responseObj.customers;
}

Alternate Usage #

If you don't want to parse an entire API reponse on the Flutter end, you can still get native Dart objects! Every object, from Customers to Orders, have a .fromJson() method and .toJson() method. Thus, you can send those data objects directly from your back end and parse them individually. The freedom is in your hands!

Where this could be useful

  • Perhaps you want to handle errors from Square on the server, and send a reponse back to Flutter only when you have a finished successful call. That way you could skip all the error handling in the Request object
  • Alternatively, maybe you want to combine individual calls from Square using cursors on the server side, and send the full response to Flutter. Then, you wounldn't have to worry about cursors in you Flutter code
  • Finally, you can combine calls on the server side and send the raw data to Flutter. Maybe you want to retrieve locations and orders on the server, then send both payloads in one response back to Flutter. This is a way you could do that!

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

import 'package:square_connect/square_connect.dart';

async listCustomers() {
  String response = await CustomBackend.listCustomers();

  var responseObj = ListCustomersResponse.fromJson(json.decode(reponse));

  if (responseObj.hasErrors) {
    throw new Error(responseObj.errors)
  } else {
    return responseObj.customers;
  }
}

Pagination #

If pagination is supported/needed, the response object 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.

Contributions #

If you have any feedback on how to improve the package for usablility, or bugs to report, please do so at https://github.com/mtwichel/square-connect-flutter-library/issues.

1.1.0 #

  • Removed Flutter from the dependencies. This will allow to use the package as a pure Dart library (i.e. backend or AngularDart).

1.0.1 #

  • Removing Android and iOS folder as they aren't needed for this package.

1.0.0 #

  • Big Changes in Direction on Package, so I'm designating 1.0.0.
  • I suggest you read the updated readme, but TL;DR
    • There were some serious security concerns from Square on previous package implementation around storing your API key on the device. It belongs on a server you control.
    • There is now no support for calling API functions directly from this package
    • This also means no support for creating an instance of the API.
    • It's primary purpose is a library of native Dart objects that mirror the conceptual objects used in the Square API.
    • You can create these objects by specifiying ObjectName.fromJson(response)
  • If you have feedback on these changes, feel free to create an issue on https://github.com/mtwichel/square-connect-flutter-library/issues, or send them to marcust@citybrew.com

0.2.6 #

  • Fixed some bugs in Payments API
  • Removed InApp payments (and all realted converter methods) from this project as it was causing configuration problems.

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: ^1.1.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or 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]
51
Health:
Code health derived from static analysis. [more]
75
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
68
Learn more about scoring.

We analyzed this package on Feb 24, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.1
  • pana: 0.13.5

Health suggestions

Fix lib/src/orders/orders-objects.dart. (-25 points)

Analysis of lib/src/orders/orders-objects.dart reported 74 hints, including:

line 152 col 7: DO use curly braces for all flow control structures.

line 154 col 7: DO use curly braces for all flow control structures.

line 156 col 7: DO use curly braces for all flow control structures.

line 158 col 7: DO use curly braces for all flow control structures.

line 161 col 7: DO use curly braces for all flow control structures.

Fix lib/src/catalog/catalog-objects.dart. (-20.99 points)

Analysis of lib/src/catalog/catalog-objects.dart reported 47 hints, including:

line 104 col 7: DO use curly braces for all flow control structures.

line 106 col 7: DO use curly braces for all flow control structures.

line 108 col 7: DO use curly braces for all flow control structures.

line 113 col 7: DO use curly braces for all flow control structures.

line 117 col 7: DO use curly braces for all flow control structures.

Fix lib/src/payments/payments-objects.dart. (-4.89 points)

Analysis of lib/src/payments/payments-objects.dart reported 10 hints, including:

line 111 col 7: DO use curly braces for all flow control structures.

line 113 col 7: DO use curly braces for all flow control structures.

line 121 col 7: DO use curly braces for all flow control structures.

line 127 col 7: DO use curly braces for all flow control structures.

line 221 col 7: DO use curly braces for all flow control structures.

Fix additional 7 files with analysis or formatting issues. (-21.20 points)

Additional issues in the following files:

  • lib/src/shared-objects.dart (10 hints)
  • lib/src/inventory/inventory-objects.dart (8 hints)
  • lib/src/customer/customer-objects.dart (6 hints)
  • lib/src/locations/locations-objects.dart (6 hints)
  • lib/src/refunds/refunds-objects.dart (5 hints)
  • lib/src/labor/labor-objects.dart (4 hints)
  • lib/src/transactions/transactions-objects.dart (4 hints)

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.2.2 <3.0.0
Dev dependencies
test ^1.6.0