✨ Add new example for iterating over data

docs/source/examples.md

@@ -17,4 +17,5 @@ Be sure to update the example files with your own credentials in place of `<your
   examples/authorization_flow
   examples/create_invoice
   examples/create_invoice_extended
+  examples/export_clients_outstanding_balance
 ```

docs/source/examples/export_clients_outstanding_balance.md

@@ -0,0 +1,8 @@
+
+# Export Clients Outstanding Balance
+
+```{eval-rst}
+.. literalinclude:: ../../../examples/export_clients_outstanding_balance.py
+  :language: python
+  :linenos:
+```

examples/authorization_flow.py

@@ -4,14 +4,14 @@
 from types import SimpleNamespace
 from freshbooks import Client as FreshBooksClient
 
-fb_client_id = "<your client id>"
-secret = "<your client secret>"
-redirect_uri = "<your redirect uri>"
+FB_CLIENT_ID = "<your client id>"
+SECRET = "<your client secret>"
+REDIRECT_URI = "<your redirect uri>"
 
 freshBooksClient = FreshBooksClient(
-    client_id=fb_client_id,
-    client_secret=secret,
-    redirect_uri=redirect_uri
+    client_id=FB_CLIENT_ID,
+    client_secret=SECRET,
+    redirect_uri=REDIRECT_URI
 )
 
 authorization_url = freshBooksClient.get_auth_request_url(
@@ -20,7 +20,7 @@
 print(f"Go to this URL to authorize: {authorization_url}")
 
 # Going to that URL will prompt the user to log into FreshBooks and authorize the application.
-# Once authorized, FreshBooks will redirect the user to your `redirect_uri` with the authorization 
+# Once authorized, FreshBooks will redirect the user to your `redirect_uri` with the authorization
 # code will be a parameter in the URL.
 auth_code = input("Enter the code you get after authorization: ")
 

examples/create_invoice.py

@@ -4,17 +4,17 @@
 from freshbooks import Client as FreshBooksClient
 from freshbooks import FreshBooksError
 
-fb_client_id = "<your client id>"
-access_token = "<your access token>"
-account_id = "<your account id>"
+FB_CLIENT_ID = "<your client id>"
+ACCESS_TOKEN = "<your access token>"
+ACCOUNT_ID = "<your account id>"
 
-freshBooksClient = FreshBooksClient(client_id=fb_client_id, access_token=access_token)
+freshBooksClient = FreshBooksClient(client_id=FB_CLIENT_ID, access_token=ACCESS_TOKEN)
 
 # Create the client
 print("Creating client...")
 try:
     client_data = {"organization": "Python SDK Test Client"}
-    client = freshBooksClient.clients.create(account_id, client_data)
+    client = freshBooksClient.clients.create(ACCOUNT_ID, client_data)
 except FreshBooksError as e:
     print(e)
     print(e.status_code)
@@ -49,7 +49,7 @@
 }
 print("Creating invoice...")
 try:
-    invoice = freshBooksClient.invoices.create(account_id, invoice_data)
+    invoice = freshBooksClient.invoices.create(ACCOUNT_ID, invoice_data)
 except FreshBooksError as e:
     print(e)
     print(e.status_code)
@@ -64,7 +64,7 @@
     "action_mark_as_sent": True
 }
 try:
-    invoice = freshBooksClient.invoices.update(account_id, invoice.id, invoice_data)
+    invoice = freshBooksClient.invoices.update(ACCOUNT_ID, invoice.id, invoice_data)
 except FreshBooksError as e:
     print(e)
     print(e.status_code)

examples/create_invoice_extended.py

@@ -5,21 +5,21 @@
 from freshbooks import Client as FreshBooksClient
 from freshbooks import FreshBooksError
 
-fb_client_id = "<your client id>"
-access_token = "<your access token>"
-account_id = "<your account id>"
-destination_email = "<your email>"  # Don't use the same email as the account owner.
+FB_CLIENT_ID = "<your client id>"
+ACCESS_TOKEN = "<your access token>"
+ACCOUNT_ID = "<your account id>"
+DESTINATION_EMAIL = "<your email>"  # Don't use the same email as the account owner.
 
-freshBooksClient = FreshBooksClient(client_id=fb_client_id, access_token=access_token)
+freshBooksClient = FreshBooksClient(client_id=FB_CLIENT_ID, access_token=ACCESS_TOKEN)
 
 # Create the client
 print("Creating client...")
 try:
     client_data = {
-        "email": destination_email,
+        "email": DESTINATION_EMAIL,
         "organization": "Python SDK Test Client"
     }
-    client = freshBooksClient.clients.create(account_id, client_data)
+    client = freshBooksClient.clients.create(ACCOUNT_ID, client_data)
 except FreshBooksError as e:
     print(e)
     print(e.status_code)
@@ -31,12 +31,12 @@
 try:
     print("Uploading invoice logo")
     # We upload a file by providing the path to the file.
-    logo = freshBooksClient.images.upload(account_id, file_path="./assets/sample_logo.png")
+    logo = freshBooksClient.images.upload(ACCOUNT_ID, file_path="./assets/sample_logo.png")
 
     print("Uploading invoice attachment")
     # We upload a file by opening it and providing the file stream.
     attachment = freshBooksClient.attachments.upload(
-        account_id, file_stream=open("./assets/sample_attachment.pdf", "rb")
+        ACCOUNT_ID, file_stream=open("./assets/sample_attachment.pdf", "rb")
     )
 except FreshBooksError as e:
     print(e)
@@ -91,7 +91,7 @@
 }
 print("Creating invoice...")
 try:
-    invoice = freshBooksClient.invoices.create(account_id, invoice_data)
+    invoice = freshBooksClient.invoices.create(ACCOUNT_ID, invoice_data)
 except FreshBooksError as e:
     print(e)
     print(e.status_code)
@@ -109,7 +109,7 @@
     "has_credit_card": True
 }
 try:
-    freshBooksClient.invoice_payment_options.create(account_id, invoice.id, payment_option_data)
+    freshBooksClient.invoice_payment_options.create(ACCOUNT_ID, invoice.id, payment_option_data)
 except FreshBooksError as e:
     print(e)
     print(e.status_code)
@@ -127,7 +127,7 @@
     }
 }
 try:
-    invoice = freshBooksClient.invoices.update(account_id, invoice.id, invoice_data)
+    invoice = freshBooksClient.invoices.update(ACCOUNT_ID, invoice.id, invoice_data)
 except FreshBooksError as e:
     print(e)
     print(e.status_code)

examples/export_clients_outstanding_balance.py

@@ -0,0 +1,59 @@
+# This is an example where we fetch all clients and their outstanding balances and export
+# them to a csv file.
+# It demostrates pagination and extra included fields.
+
+# Each csv row will contain the outstanding balance for a particular currency for a client.
+# Thus clients with multiple currencies will have multiple rows.
+# Eg.
+# 123, Bob, 200, CAD
+# 123, Bob, 100, USD
+# 456, Alice, 300, CAD
+
+import csv
+
+from freshbooks import Client as FreshBooksClient
+from freshbooks import FreshBooksError, IncludesBuilder, PaginateBuilder
+
+FB_CLIENT_ID = "<your client id>"
+ACCESS_TOKEN = "<your access token>"
+ACCOUNT_ID = "<your account id>"
+PAGE_SIZE = 100
+
+freshBooksClient = FreshBooksClient(client_id=FB_CLIENT_ID, access_token=ACCESS_TOKEN)
+
+with open("clients.csv", 'w', newline='') as csvfile:
+    writer = csv.writer(csvfile)
+    writer.writerow(["Client Id", "Organization", "Outstanding Balance", "Currency"])
+
+    print("Fetching all clients...")
+    # Setup paginator to iterate through all clients
+    paginator = PaginateBuilder(1, PAGE_SIZE)
+    # Include outstanding balances in the response
+    includes = IncludesBuilder().include("outstanding_balance")
+
+    clients = None
+    while not clients or clients.pages.page < clients.pages.pages:
+        try:
+            # Get page of clients with outstanding balance included
+            clients = freshBooksClient.clients.list(ACCOUNT_ID, builders=[paginator, includes])
+        except FreshBooksError as e:
+            print(e)
+            print(e.status_code)
+            exit(1)
+
+        for client in clients:
+            print(f"Writing client {client.organization} ({client.id}) to csv...")
+            # Clients will have a outstanding_balance for each currency
+            if not client.outstanding_balance:
+                writer.writerow([client.id, client.organization])
+            else:
+                for outstanding_balance in client.outstanding_balance:
+                    writer.writerow([
+                        client.id,
+                        client.organization,
+                        outstanding_balance.amount.amount,
+                        outstanding_balance.amount.code
+                    ])
+
+        # Update paginator to get next page
+        paginator.page(clients.pages.page + 1)