{"id":20643121,"url":"https://github.com/armintalaie/squareup","last_synced_at":"2026-05-08T06:03:11.694Z","repository":{"id":133165515,"uuid":"419859488","full_name":"armintalaie/SquareUp","owner":"armintalaie","description":"A Square application that combines multiple stores' loyalty programs","archived":false,"fork":false,"pushed_at":"2021-11-22T21:49:08.000Z","size":1574,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-17T09:10:09.060Z","etag":null,"topics":["firebase","square","typescript"],"latest_commit_sha":null,"homepage":"https://square-4797a.web.app/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/armintalaie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-21T19:55:34.000Z","updated_at":"2025-01-11T05:23:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"db9712b1-570c-4423-ac1d-618f609f38fd","html_url":"https://github.com/armintalaie/SquareUp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armintalaie%2FSquareUp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armintalaie%2FSquareUp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armintalaie%2FSquareUp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armintalaie%2FSquareUp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/armintalaie","download_url":"https://codeload.github.com/armintalaie/SquareUp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242704001,"owners_count":20172147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["firebase","square","typescript"],"created_at":"2024-11-16T16:11:34.063Z","updated_at":"2026-05-08T06:03:06.618Z","avatar_url":"https://github.com/armintalaie.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Inner Circle - An application for Square ;)\n\n\n\n#### Inner Circle ⭕️ uses Square's native Loyalty services to create an enhanced group loyalty program while mainitaining each store's individual loyalties. \n\n\n[using this app as a client](#for-the-user)\n\n[behind the works](#how-it-works)\n\n\n## What This App Can Do for a Seller\n\n- By creating an enhanced loyalty program, you can give a customer more options to redeem their points\n- A shared Loyalty system will encourage a customer to return to your store\n- By bringing in more stores, customers will redeem their points from multiple stores, rather than redeeming it all from your store\n- It can provide incentive to small businesses to compete with large corporations with various stores\n\n\n\n## Security and Flexibility\n\n- Your store can easily leave a program and it will not affect your current loyalty program\n- Nothing besides the added/redeemed points will be shared with other stores\n- Circle will only update exisiting customers in your store and not add external ones\n  - You can check where point changes for a customer by clicking on their profile\n    - it will show which store updated your cutomer's points and by how much\n\n- You can set up a conversion ratio between your partner points and yours giving you the option to choose what's best for your store\n\n\n\n## For the User\n\n#### How to Get Started\n\n\n\n###### Step 1: Authorizing Circle\n\n- easily authorize Circle with a few clicks to enrol\n\n\n\n###### Step 2: Creating or Joining a Partner Program\n\nafter integrating with Circle, you can easily create a program by giving it a name or join a program\n\n- Any Square seller with an active Loyalty program can authorize this app to \u003cu\u003ecreate\u003c/u\u003e a **Partner Program** \n- Other Square sellers can \u003cu\u003ejoin\u003c/u\u003e a Partner Program via a **Partner Id**\n\n\n\n###### Step 3: Monitor and modify your program \n\nafter step 2, you can view your loyalty statistics from the app:\n\n- View your instore and external points\n- Change your point conversion ratio\n- See the participating stores and invite others\n- Leave the partner program\n\n\n\n\n\n## How it Works\n\n\u003chr\u003e\n\nUnder the hood, Circle uses\n- Square's **MerchantsAPI**, **LoyaltyAPI**, **CustomersAPI**, **oAuthAPI**\n- **Firebase**'s **Cloud functions** for the backend written in **Typescript**\n- **Firebase**'s **Firestore** as a database to store and fetch data relevant to the programs and sellers\n- A **React** Client and **MaterialUI** for the web application hosted on Firebase\n\u003chr\u003e\n\n\n#### Authentication\n\nEach user is authenticated via Square's Authentication. The app will recieve an authorization code and the backend server will Call the OAuth API to get an access token\n\n\n\n#### Creating or joining a Partner Program \n\nAfter initiating create/join a program, the backend will create a collection in FireStore uniqely created for that user and store the user's program infromation. \n\n- if user is already in a program it will direct them there\n\nFor each store, Circle stores:\n\n###### A document with information about a store as a client of Circle\n\n```typescript\n{\n    programId: string; // id of their program\n    storeId: string; // merchant id\n    storeName: string; // name of the store\n    isActive: boolean; // if store is in an active partner program\n}\n```\n\nEach Program Collection contains:\n\n###### A document with general program information\n\n```typescript\n{\n  stores: string[]; // list of store names\n  storeActivities: StoreMap; // under construction\n  storeCount: number; // number of stores in the program\n  programName: string; // name of the program\n  id: string; // unique program id\n}\n```\n\n###### A document for each participating store\n\n```typescript\n{\n  storeId: string; // merchant id\n  storeToken: string; // seller's access token\n  storeName: string; // name of the store\n  InternalPointsRecieved: number; // internal points given to customers \n  InternalPointsRedeemed: number; // internal points taken from customers \n  ExternalPointsRecieved: number; // external points given to customers \n  ExternalPointsRedeemed: number; // external points taken to customers \n  conversionRate: number; // the conversion ratio to apply to external points before applying to store\n}\n```\n\n#### Leaving a Partner Program \n\n- Circle will use the stores info to delete the store's information from Firestore\n- it will not affect store's own loyalty program\n- any future changes to the partner program will not be applied to the store\n- other participating stores will not lose their statisitics or program; but only have one less store in their program\n- if no store is left in a program, Circle will delete the program\n\n\n\n#### Behind the scenes' Flow\n\n\n\n##### Customer interaction with a store\n\n1. Everytime a customer buys something or redeems a reward, Square will send a **webhook** in response to the **loyalty event** to Circle. \n\n2. Circle uses Square's **LoyaltyAPI** to find customer's id and then the **CustomersAPI** to find the customers number\n\n   - if event type is redeem, Circle will use the reward id and the **LoyaltyAPI** to find the points for that reward\n\n3. Circle will go over the *partner program collection* in firestore and use the MerchantAPI to find all the partner stores\n\n   - Then it uses the **CutomersAPI** to find the customer with the matching number and if found their loyalty account id\n\n   - using **LoyaltyAPI's** adjust points, Circle increments or decrements the customer's point for the other stores based on the conversion ratio for each store and set a message to track for each seller\n   - Lastly, will update firestore with the changed points\n\n\n\n##### Dashboard\n\n1. Circle will fetch the the program from **Firestore** based on user's credentials\n   - Partner stores\n   - Points applied internally or externally\n\n\n\n\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmintalaie%2Fsquareup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farmintalaie%2Fsquareup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmintalaie%2Fsquareup/lists"}