You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
*[BigCommerce sandbox store](https://developer.bigcommerce.com/docs/ZG9jOjM4MzMyNTE-create-a-sandbox-store?source=subscription-foundation) (required to develop and test apps)
14
+
* a database (BigCommerce recommends MongoDB)
15
+
* a shipping zone with a [Pickup in Store](https://support.bigcommerce.com/s/article/Free-Shipping?language=en_US#in-store) shipping method
16
+
* a [Stripe POS terminal and card reader](https://stripe.com/terminal)
17
+
* Experience using [npm](https://www.npmjs.com/)
18
+
* Node.js 14.x
12
19
13
-
#### 1) Create Local Environment File
20
+
## Getting started
21
+
1. Start by forking the point-of-sale-foundation repository.
22
+
2. Navigate to the root directory of your project and install npm packages.
14
23
15
-
```bash
16
-
cp .env.sample .env
17
-
```
18
-
19
-
At a minimum, the following .env variables need to be updated for the app to sucessfully run.
20
-
21
-
-`DATABASE_URL`
22
-
- Follow the "Set up Database" step below to get this.
23
-
-`BC_STORE_HASH`, `BC_AUTH_TOKEN`, `BC_CHANNEL_ID`, and `BC_GQL_URL`
24
-
- Follow the BigCommerce setup instructions below to get these.
25
-
-`STRIPE_SECRET_KEY`
26
-
- Follow the Stripe setup instructions below to get these.
27
-
28
-
#### 2) Install App Dependencies
29
-
30
-
_We recommend using node v14.17.0_
31
-
32
-
```bash
24
+
```shell
33
25
npm install
34
26
```
27
+
## BigCommerce setup
35
28
36
-
#### 3) Set up Database
29
+
1.[Create BigCommerce store](https://developer.bigcommerce.com/docs/ZG9jOjM4MzMyNTE-create-a-sandbox-store?source=subscription-foundation): go to [https://www.bigcommerce.com/essentials/](https://www.bigcommerce.com/essentials/?source=pos-foundation) and signup for a free trial if you don't have one.
30
+
2. The Bigcommerce store you are connected to must have "Pickup in Store" as a shipping option for orders to be created on the POS. Go to "Settings -> Shipping" in your admin to turn it on.
37
31
38
-
This app works with MongoDB. The `provider` setting in the `/prisma/schema.prisma` should be set to `mongodb`. We highly recommend using MongoDB, but if you would like to use another type of database, you will need to udpate the configuration to work with the database of your choice. View the available database options here: https://www.prisma.io/docs/reference/tools-and-interfaces/prisma-schema/data-sources/)
39
-
40
-
Update the `DATABASE_URL` var in `/prisma/.env` to match your new DB connection string generated from Mongo Cloud ( https://cloud.mongodb.com ).
32
+
3. Create BigCommerce v2/v3 API credentials. Go to Advanced Settings > API Accounts and create and API Account with these scopes:
41
33
42
-
<details>
34
+
```
35
+
Customers: MODIFY
36
+
Information & settings: READ-ONLY
37
+
Orders: MODIFY
38
+
Create payments: CREATE
39
+
Get payment methods: READ-ONLY
40
+
Products: READ-ONLY
41
+
Carts: MODIFY
42
+
Checkouts: MODIFY
43
+
Channel Settings: MODIFY
44
+
Storefront API tokens: MANAGE
45
+
```
46
+
4. Copy the `ACCESS_TOKEN`, `CLIENT ID`, and `CLIENT SECRET` credentials. In a later step, you will need these credentials to update `BC_APP_CLIENT_ID`, `BC_APP_SECRET`, and `BC_AUTH_TOKEN` environment variables in the .env file.
43
47
44
-
<summary>Guide on setting up Mongo Cloud</summary>
48
+
## Stripe setup
45
49
46
-
1. Click [here](https://account.mongodb.com/) and log in there, if you dont have an account you can click [SignUp](https://account.mongodb.com/account/register)
50
+
1. Go to your Stripe dashboard: https://dashboard.stripe.com/test/developers
51
+
2. Copy the Stripe secret key. In a later step, you will use the secret key to update the environment variable `STRIPE_SECRET_KEY` in the .env file.
52
+
3. Go to "More > Terminal" in the dashboard. Press "Get Started" when asked to activate the Terminal section.
53
+
4. Add a location, then click on the location row to manage details.
3. From there click on "ADD NEW DATABASE USER" and fill username and password and leave all fields as it is.
62
+
We highly recommend using MongoDB, but if you would like to use another type of database, you will need to update the configuration to work with the database of your choice. View the available database options here: https://www.prisma.io/docs/reference/tools-and-interfaces/prisma-schema/data-sources/
Mongo Cloud (https://cloud.mongodb.com) generates the `DATABASE_URL` as shown in the setup instructions below. In a later step, you will need the `DATABASE_URL` to update the environment variable in .env file.
57
65
58
-
4. Then click `Network Access` on left hand sidebar,
66
+
Click on the arrow below and follow the Mongo Cloud setup instructions.
1. Click [here](https://account.mongodb.com/) and log in. If you don't have an account, you can click [SignUp](https://account.mongodb.com/account/register).
65
73
66
-
6. Then click `Database` on left hand sidebar, which opens the first page when you logged in
74
+
2. On the left-hand sidebar, click "Database Access" > "ADD NEW DATABASE USER".
75
+
76
+
a. Fill in your username and password, and leave all remaining fields as is.
8. Then Click "Connect your application" button in the popup modal
89
+
4. On the left-hand sidebar, click "Database".
90
+
91
+
a. Click the "Connect" button in your running cluster.
92
+
93
+
b. Click "Connect your application" in the popup modal.
94
+
95
+
c. Copy the connection string and replace \<password> with the password and \<username> with the username created in step 2a. Also add "myFirstDatabase" to the connection string as shown below.
9. Then you can see MongoDB connection string in 2nd section, replace <username> and <password> with one of the user you created in 3rd step and just copy it.
101
+
_Note: This MongoDB connection string is what you should use to update the `DATABASE_URL` variable in the .env file._
That's your MongoDB connection string which you should use as `DATABASE_URL` in .env
107
+
## Create local environment file
83
108
84
-
</details>
109
+
1. Create a `.env` file in the root directory of your project.
110
+
2. Copy the content of `.env-sample` to `.env`.
111
+
```bash
112
+
cp .env.sample .env
113
+
```
114
+
At a minimum, the following .env variables need to be updated for the app to sucessfully run.
85
115
86
-
Once your Mongo Cloud account is setup, you are going to want to create the database in your new Mongo Cloud account and seed it with data:
116
+
- `DATABASE_URL`
117
+
- Follow the [Set up Database](#set-up-database) instructions to get this.
118
+
- `BC_STORE_HASH`, `BC_AUTH_TOKEN`, `BC_CHANNEL_ID`, `BC_GQL_URL, `BC_APP_CLIENT_ID`, and `BC_APP_SECRET`
119
+
- Follow the [BigCommerce setup](#bigcommerce-setup) instructions to get these.
120
+
- `STRIPE_SECRET_KEY`
121
+
- Follow the [Stripe setup](#stripe-setup) instructions to get these.
122
+
123
+
124
+
## Create and seed database
125
+
126
+
1. Once you set up your Mongo Cloud account, create the database and seed it with data by doing the following:
87
127
88
128
```
89
129
$ npx prisma db push
90
130
91
131
$ npm run seed
92
132
```
93
133
94
-
Then you need to generate a new prisma client using your database provider settings.
134
+
2. Generate a new prisma client using your database provider settings.
95
135
96
136
```
97
137
$ npx prisma generate
98
138
```
99
139
100
-
_Note: `npx prisma generate` is what creates the DB tables and initial client. If you miss this step, you'll see errors about prisma missing._
140
+
_Note: `npx prisma generate` is what creates the DB tables and initial client. If you miss this step, you'll see errors about prisma missing._
101
141
102
-
Now you'll be able to access this database locally via a visual editor and verify the table have been created.
142
+
3. Now you'll be able to access this database locally via a visual editor and verify you have created the table correctly.
103
143
104
144
```
105
145
$ npx prisma studio
106
146
```
107
147
108
-
You can also use Mongo Compass as your database GUI. Download and install to connect: [Mongo Compass](https://www.mongodb.com/products/compass)
148
+
_Note: You can also use Mongo Compass as your database GUI. Download and install to connect: [Mongo Compass](https://www.mongodb.com/products/compass)_
109
149
110
-
#### 4) Run App
150
+
4. Run app
111
151
112
152
```bash
113
153
npm run dev
@@ -117,49 +157,23 @@ Now, the app will be running locally!
117
157
118
158
Login as an admin role here: http://localhost:3000/signin (the default admin PIN in the seed data is: 1234)
119
159
120
-
Once logged in, navigate to the Settings screen to save your store address. This is the address that will be used for your checkout tax calculations.
121
-
122
-
## BigCommerce Setup
123
-
124
-
1. Create BigCommerce store: go to [https://www.bigcommerce.com/essentials/](https://www.bigcommerce.com/essentials/?source=pos-foundation) and signup for a free trial if you don't have one
125
-
126
-
2. The Bigcommerce store you are connected to must have "Pickup in Store" as a shipping option for orders to be created on the POS. Go to "Store Setup -> Shipping" in your admin to turn it on.
160
+
Once logged in, navigate to the "Settings" screen to save your store address. The app uses your store address for checkout tax calculations. You will receive the following error if you do not supply the store address.
3. Create BigCommerce v2/v3 API credentials. Go to Advanced Settings > API Accounts and create and API Account with these scopes:
129
-
130
-
```
131
-
Customers: MODIFY
132
-
Information & settings: READ-ONLY
133
-
Orders: MODIFY
134
-
Create payments: CREATE
135
-
Get payment methods: READ-ONLY
136
-
Products: READ-ONLY
137
-
Carts: MODIFY
138
-
Checkouts: MODIFY
139
-
Channel Settings: MODIFY
140
-
Storefront API tokens: MANAGE
141
-
```
142
-
143
-
## Stripe Setup
144
-
145
-
1. Go to your Stripe dashboard: https://dashboard.stripe.com/test/developers
146
-
2. Copy the Stripe secret key and add to your .env file
147
-
3. Go to 'More > Terminal' in the dashboard. Press 'Get Started' when asked to activate the Terminal section.
148
-
4. Add a location, then click on the location row to manage details.
149
-
5. Add a new reader to the location.
150
164
151
165
## Connecting to a reader in the POS
152
166
153
-
When on the main register screen, press the 'wifi' icon, which will read all of your terminals from Stripe and check if they are active on your network.
167
+
On the main register screen, press the 'wifi' icon, which will read all of your terminals from Stripe and check if they are active on your network.
154
168
155
-
Press 'Connect' for the active terminal you'd like to use to take payment at checkout.
169
+
Press "Connect"for the active terminal you'd like to use to take payment at checkout.
156
170
157
171
## Key areas of codebase
158
172
159
173
- `/backend`
160
-
- Where the auth and various API services live. These are uses within the internal API endpoints to keep routes secure and reach out to external APIs.
174
+
- Where the auth and various API services live. These are used within the internal API endpoints to keep routes secure and reach out to external APIs.
161
175
- `/prisma`
162
-
- Where the DB models and initial seed data lives. Prisma uses this to generate DB clients for the app.
176
+
- Where the DB models and initial seed data live. Prisma uses this to generate DB clients for the app.
163
177
- `/shared`
164
178
- Where the types are located.
165
179
- `/src/pages`
@@ -170,46 +184,46 @@ Press 'Connect' for the active terminal you'd like to use to take payment at che
- Where the context providers used within pages and components live.
173
-
- Most are built using the concept of an 'ActionBuilder' that manages execution, loading status, and data setting in a consistent manner.
174
-
-`/{provider}/context.ts`: The types used througout the provider
187
+
- Most are built using the concept of an 'ActionBuilder' that manages execution, loading status, and data setting consistently.
188
+
- `/{provider}/context.ts`: The types used throughout the provider
175
189
- `/{provider}/index.ts`: The actions available to the pages and components using the context providers
176
190
- `/{provider}/ methods.ts`: The functions used within the actions to fetch / modify data
177
191
178
192
## Contributing
179
193
180
-
Want to help expand this foundation? We'd love to collaborate! To kickoff, here's a breakdown of items we've itemized as either potential improvements to the existing codebase or features worth adding.
194
+
Want to help expand this foundation? We'd love to collaborate! To kick-off, here's a breakdown of items we've itemized as either potential improvements to the existing codebase or features worth adding.
181
195
182
196
- Improvements:
183
197
- Improve error handling and types within try/catch in the employee service: backend/services/employee.service.ts
184
198
- Create types for CreatePaymentIntentResponse and CapturePaymentIntentResponse: src/providers/CartProvider/context.ts
185
-
- Move transaction success screen shown when payment is completed to be it's own component: src/components/modules/Orders/TenderDialog.tsx
199
+
- Move the transaction success screen shown when payment is completed to be its own component: src/components/modules/Orders/TenderDialog.tsx
186
200
- Move numeric entry pad functionality into component: src/components/modules/Orders/TenderCash.tsx
187
201
- Incorporate more graceful error handling for API calls and supply a generic method to show error messages on the FE
188
-
- Add shared component to handle loading indicators (overall and within buttons)
202
+
- Add the shared component to handle loading indicators (overall and within buttons)
- Utilize the BigCommerce API Client types instead of the custom types (pending release of new client)
191
-
- Prevent loading of app if environment variables or BigCommerce store setup is invalid, along with instructions on how to fix
205
+
- Prevent loading of the app if environment variables or BigCommerce store setup is invalid, along with instructions on how to fix
192
206
- Features:
193
207
- Ship-to-Customer checkout flow (creation / selection of shipping address)
194
208
- Customer management section
195
-
- Recall and finalize payment on incomplete orders
209
+
- Recall and finalize the payment on incomplete orders
196
210
- Receipt Printer Hardware Support
197
211
- Barcode Scanner Hardware Support
198
212
- Cash Drawer Support
199
213
- Product Lookup / Search
200
214
- Basic Loyalty / Gift Card integration
201
215
- Support forMulti-location Inventory, unlocking BOPIS (Buy Online, Pickupin Store)
202
-
- Selection of store currency from list of transactional currencies active on the POS channel
203
-
- Returns, refunds and store credit flows
216
+
- Selection of store currency from the list of transactional currencies active on the POS channel
217
+
- Returns, refunds, and store credit flows
204
218
- Shift Change Operations
205
219
206
-
## Learn More
220
+
## Learn more
207
221
208
-
### Additional Point of Sale Solutions
222
+
### Additional point of sale solutions
209
223
210
224
Check out the wide variety of POS apps on the [BigCommerce App Marketplace](https://www.bigcommerce.com/apps/in-store/?source=pos-foundation).
211
225
212
-
### The BigCommerce Platform
226
+
### The BigCommerce platform
213
227
214
228
Looking to help the world's leading brands and the next generation of successful merchants take flight? To learn more about developing on top of the BigCommerce platform, take a look at the following resources:
0 commit comments