diff --git a/.gitignore b/.gitignore index 0f5e540f..044ca66b 100644 --- a/.gitignore +++ b/.gitignore @@ -34,3 +34,7 @@ sqlfile.dbml report_summary migration-results streamlit + + +apps/docs/build/* +apps/backend/report.xlsx \ No newline at end of file diff --git a/Makefile b/Makefile index cae748b7..72c25cdc 100644 --- a/Makefile +++ b/Makefile @@ -342,8 +342,6 @@ drop: @docker exec -it $(PROJECT)-db psql -U postgres -d pcc -c "DROP SCHEMA public CASCADE;" @docker exec -it $(PROJECT)-db psql -U postgres -d pcc -c "CREATE SCHEMA public;" -dev-docs: - @docker exec -it $(PROJECT)-backend yarn run compodoc # =================================== @@ -424,3 +422,32 @@ version-minor: version-patch: @yarn run version:patch + aws ec2-instance-connect send-ssh-public-key --instance-id $(BASTION_INSTANCE_ID) --instance-os-user ec2-user --ssh-public-key file://ssh-keypair.pub + ssh -i ssh-keypair ec2-user@$(BASTION_INSTANCE_ID) -L 5454:$(DB_HOST):5432 -o ProxyCommand="aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'" + + +# =================================== +# Project Documentation +# =================================== + +update-docs: + @echo "+\n++ Updating docs: ...\n+" + @./apps/docs/docs.sh + +build-docs: + @docker-compose up -d --build docs + @echo "docs: http://localhost:3001" + +run-docs: + @docker-compose up -d docs + @echo "docs: http://localhost:3001" + + +# =================================== +# Developer Documentation +# =================================== + +dev-docs: + @echo "Wait for 1 minute, then visit: http://localhost:8081" + @docker exec -it $(PROJECT)-backend yarn run compodoc + \ No newline at end of file diff --git a/apps/backend/package.json b/apps/backend/package.json index 78512e98..c3b795f2 100644 --- a/apps/backend/package.json +++ b/apps/backend/package.json @@ -28,7 +28,7 @@ "typeorm:generate-migration": "yarn run typeorm migration:generate -d ./src/database/datasource.ts ./src/database/migrations/migration", "typeorm:create-migration": "yarn run typeorm migration:create ./src/database/migrations/migration", "typeorm:revert-migration": "yarn run typeorm -d ./src/database/datasource.ts migration:revert", - "docs": "npx @compodoc/compodoc -c compodoc.yaml", + "docs": "npx @compodoc/compodoc -o -c compodoc.yaml", "version:major": "yarn version major", "version:minor": "yarn version minor", "version:patch": "yarn version patch" @@ -66,7 +66,7 @@ "winston": "3.10.0" }, "devDependencies": { - "@compodoc/compodoc": "1.1.21", + "@compodoc/compodoc": "1.1.22", "@faker-js/faker": "8.0.2", "@golevelup/ts-jest": "0.4.0", "@nestjs/cli": "10.1.11", diff --git a/apps/docs/api.json b/apps/docs/api.json new file mode 100644 index 00000000..23b2eb5d --- /dev/null +++ b/apps/docs/api.json @@ -0,0 +1 @@ +{"openapi":"3.0.0","paths":{"/api/v1/version":{"get":{"operationId":"AppController_getVersion","parameters":[],"responses":{"200":{"description":""}},"tags":["Health API"],"security":[{"basic":[]}]}},"/api/v1/error":{"get":{"operationId":"AppController_getError","parameters":[],"responses":{"200":{"description":""}},"tags":["Health API"],"security":[{"basic":[]}]}},"/api/v1/health":{"get":{"operationId":"AppController_getHealth","summary":"","parameters":[],"responses":{"200":{"description":""}},"tags":["Health API"],"security":[{"basic":[]}]}},"/api/v1/transaction":{"post":{"operationId":"TransactionController_saveTransactionEvent","summary":"Post Sales Event","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"example":[{"transaction_id":"72cbe1da-b08e-49d4-9a87-69afd660d14b","transaction_date":"2023-01-01","transaction_time":"13.33.31.875973","fiscal_close_date":"2023-01-02","total_transaction_amount":30.2,"void_indicator":false,"miscellaneous":{"employee_id":"SC61350"},"source":{"source_id":"SBC","location_id":61,"accepted_payment_methods":["CASH","CHQ","P","M","V"]},"payments":[{"amount":20,"foreign_currency_amount":15,"currency":"USD","exchange_rate":1.34,"payment_method":"CASH","payment_channel":"in-person"},{"amount":10.2,"currency":"CAD","payment_method":"V","payment_channel":"in-person","terminal":{"card_no":"5253","merchant_id":"20777441","device_id":"GA2077744108","invoice_no":""},"online":{"tran_id":"","order_no":""},"pos":{"approval_code":"ASWQD24342"}}],"accounting":[{"sequence":"001","details":{"code":"1234","description":"passport photocopy"},"distributions":[{"line_number":"00001","line_description":"passport photocopy","line_dollar_amount":10,"disbursment_gl_account":{"dist_client_code":"074","dist_resp_code":"66020","dist_service_line_code":"44275","dist_stob_code":"1278","dist_project_code":"6600000","dist_location_code":"000000","dist_future_code":"0000","supplier_code":"000000","EFT":{"vendor":"xxx"}},"revenue_gl_account":{"dist_client_code":"074","dist_resp_code":"66020","dist_service_line_code":"44275","dist_stob_code":"1474","dist_project_code":"6600000","dist_location_code":"000000","dist_future_code":"0000","supplier_code":"000000"}},{"line_number":"00002","line_description":"PST G/L ","line_dollar_amount":0.7,"disbursment_gl_account":{"dist_client_code":"022","dist_resp_code":"12345","dist_service_line_code":"66123","dist_stob_code":"4123","dist_project_code":"3200000","dist_location_code":"000000","dist_future_code":"0000","supplier_code":"000000"},"revenue_gl_account":{"dist_client_code":"074","dist_resp_code":"66020","dist_service_line_code":"44275","dist_stob_code":"1474","dist_project_code":"6600000","dist_location_code":"000000","dist_future_code":"0000","supplier_code":"000000"}},{"line_number":"00003","line_dollar_amount":0.5,"line_description":"GST G/L ","disbursment_gl_account":{"dist_client_code":"022","dist_resp_code":"4567","dist_service_line_code":"88123","dist_stob_code":"4123","dist_project_code":"3200000","dist_location_code":"000000","dist_future_code":"0000","supplier_code":"000000"},"revenue_gl_account":{"dist_client_code":"074","dist_resp_code":"66020","dist_service_line_code":"44275","dist_stob_code":"1474","dist_project_code":"6600000","dist_location_code":"000000","dist_future_code":"0000","supplier_code":"000000"}}]},{"sequence":"002","details":{"code":"1234","description":"driving lic renewal"},"distributions":[{"line_number":"00001","line_description":"driving lic renewal","line_dollar_amount":14,"disbursment_gl_account":{"dist_client_code":"010","dist_resp_code":"66213","dist_service_line_code":"44275","dist_stob_code":"1278","dist_project_code":"6600000","dist_location_code":"000000","dist_future_code":"0000","supplier_code":"000000","EFT":{"vendor":"xxx"}},"revenue_gl_account":{"dist_client_code":"074","dist_resp_code":"66020","dist_service_line_code":"44275","dist_stob_code":"1474","dist_project_code":"6600000","dist_location_code":"000000","dist_future_code":"0000","supplier_code":"000000"}}]}]}]}}}},"responses":{"default":{"description":"Returns the parsed sales reconciliation data","content":{"application/json":{"schema":{"example":{"data":[]}}}}}},"tags":["Transaction API"],"security":[{"basic":[]}]}},"/api/v1/parse/upload":{"post":{"operationId":"ParseController_uploadFile","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"program":{"type":"string","enum":["SBC","LABOUR"],"nullable":false},"source":{"type":"string","enum":["bcm","sbc"],"nullable":false},"fileType":{"type":"string","enum":["TDI17","TDI34","SBC_SALES"],"nullable":false},"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":""}},"tags":["Parser API"],"security":[{"basic":[]}]}}},"info":{"title":"PayCoCo API Docs","description":"Payment Common Component API Documentation","version":"1.0.0","contact":{}},"tags":[],"servers":[],"components":{"securitySchemes":{"basic":{"type":"http","scheme":"basic"}},"schemas":{}}} \ No newline at end of file diff --git a/apps/docs/docs.sh b/apps/docs/docs.sh new file mode 100755 index 00000000..5e93b8f2 --- /dev/null +++ b/apps/docs/docs.sh @@ -0,0 +1,22 @@ +#! /bin/bash + +REQUIRED_PKG="widdershins" +PKG_OK=$(widdershins --version) + +echo Checking for $REQUIRED_PKG: $PKG_OK +if [ "" = "$PKG_OK" ]; then + echo "No $REQUIRED_PKG" + read -p "Would you like to install $REQUIRED_PKG ? (y/n) " -n 1 -r + if [[ ! $REPLY =~ ^[Yy]$ ]] + then + exit 1 + fi + npm i -g widdershins +else + curl --location --request GET '[::1]:3000/api-json' > ./apps/docs/api.json; + widdershins --omit-header --environment ./apps/docs/env.json ./apps/docs/api.json -o ./apps/docs/source/includes/_api.md + + +fi + + diff --git a/apps/docs/env.json b/apps/docs/env.json new file mode 100644 index 00000000..5ec6afbc --- /dev/null +++ b/apps/docs/env.json @@ -0,0 +1,3 @@ +{ + "language_tabs": [{ "typescript": "Typescript" }] +} diff --git a/apps/docs/readme.md b/apps/docs/readme.md new file mode 100644 index 00000000..5bc4d398 --- /dev/null +++ b/apps/docs/readme.md @@ -0,0 +1,20 @@ +## Payment Common Component Docs + +### Technical Setup + +- Run `make update-docs` to get the latest API spec and to install widdershins, if required. + +- Run `make build-docs` to build the docs in a docker container. + +- Run `make run-docs` to run. + +- Click [HERE](http://localhost:3001) to view docs + +#### Updating Docs + +When you run `make update-docs` the api section of the documentation will update automatically, based on the Swagger API tags from the running application. + +To update the written content, images, and other sources, you can make changes to the "source files" + +Visit [Slate Docs](https://github.com/slatedocs/slate) for detailed information + diff --git a/apps/docs/source/fonts/BCSans-Bold.woff b/apps/docs/source/fonts/BCSans-Bold.woff new file mode 100644 index 00000000..f2ecf167 Binary files /dev/null and b/apps/docs/source/fonts/BCSans-Bold.woff differ diff --git a/apps/docs/source/fonts/BCSans-BoldItalic.woff b/apps/docs/source/fonts/BCSans-BoldItalic.woff new file mode 100644 index 00000000..9a3353c2 Binary files /dev/null and b/apps/docs/source/fonts/BCSans-BoldItalic.woff differ diff --git a/apps/docs/source/fonts/BCSans-Italic.woff b/apps/docs/source/fonts/BCSans-Italic.woff new file mode 100644 index 00000000..fb061a3e Binary files /dev/null and b/apps/docs/source/fonts/BCSans-Italic.woff differ diff --git a/apps/docs/source/fonts/BCSans-Regular.woff b/apps/docs/source/fonts/BCSans-Regular.woff new file mode 100644 index 00000000..07f8f0b7 Binary files /dev/null and b/apps/docs/source/fonts/BCSans-Regular.woff differ diff --git a/apps/docs/source/fonts/FONTLOG_README.txt b/apps/docs/source/fonts/FONTLOG_README.txt new file mode 100644 index 00000000..ca0ffb97 --- /dev/null +++ b/apps/docs/source/fonts/FONTLOG_README.txt @@ -0,0 +1,30 @@ +FONTLOG for the BC Sans font + +This file provides detailed information on the BC Sans font software. + +This information should be distributed along with the BC Sans fonts and any derivative works. + +Basic Font Information + +BC Sans is a Unicode typeface family that supports languages that use the Latin and syllabic scripts, and it's variants. + +BC Sans is a modified version of Noto Sans, developed by Google. Modifications have been done to provide support for Indigenous languages unique to British Columbia. + +BC Sans comes in four styles: regular, bold, italic, and bold italic + +ChangeLog + +20 July 2019 (B.C Government) BCSansFontFamily Version 1.0 +- Initial release +- Combined NotoSans font with NotoSansCanadianAboriginal font into single font file +- Renamed Noto Sans to BC Sans +- Fixed combining position of "combining lowline" (U+0332) for dz and ts combinations +- Added right spacing to the "combining comma above right" (U+0315) +- Added syllabic variant positioning for the Dakelh syllabics + +Acknowledgements + +N: Chris Harvey +E: languagegeek@gmail.com +W: http://www.languagegeek.com +D: Contributor diff --git a/apps/docs/source/fonts/LICENSE_OFL.txt b/apps/docs/source/fonts/LICENSE_OFL.txt new file mode 100644 index 00000000..1e5c88ba --- /dev/null +++ b/apps/docs/source/fonts/LICENSE_OFL.txt @@ -0,0 +1,94 @@ +Copyright (c) 2015, Google Inc., copyright (c) 2019, Province of B.C. 2019 + +This Font Software is licensed under the SIL Open Font License, +Version 1.1. + +This license is copied below, and is also available with a FAQ at: +http://scripts.sil.org/OFL + +----------------------------------------------------------- +SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007 +----------------------------------------------------------- + +PREAMBLE +The goals of the Open Font License (OFL) are to stimulate worldwide +development of collaborative font projects, to support the font +creation efforts of academic and linguistic communities, and to +provide a free and open framework in which fonts may be shared and +improved in partnership with others. + +The OFL allows the licensed fonts to be used, studied, modified and +redistributed freely as long as they are not sold by themselves. The +fonts, including any derivative works, can be bundled, embedded, +redistributed and/or sold with any software provided that any reserved +names are not used by derivative works. The fonts and derivatives, +however, cannot be released under any other type of license. The +requirement for fonts to remain under this license does not apply to +any document created using the fonts or their derivatives. + +DEFINITIONS +"Font Software" refers to the set of files released by the Copyright +Holder(s) under this license and clearly marked as such. This may +include source files, build scripts and documentation. + +"Reserved Font Name" refers to any names specified as such after the +copyright statement(s). + +"Original Version" refers to the collection of Font Software +components as distributed by the Copyright Holder(s). + +"Modified Version" refers to any derivative made by adding to, +deleting, or substituting -- in part or in whole -- any of the +components of the Original Version, by changing formats or by porting +the Font Software to a new environment. + +"Author" refers to any designer, engineer, programmer, technical +writer or other person who contributed to the Font Software. + +PERMISSION & CONDITIONS +Permission is hereby granted, free of charge, to any person obtaining +a copy of the Font Software, to use, study, copy, merge, embed, +modify, redistribute, and sell modified and unmodified copies of the +Font Software, subject to the following conditions: + +1) Neither the Font Software nor any of its individual components, in +Original or Modified Versions, may be sold by itself. + +2) Original or Modified Versions of the Font Software may be bundled, +redistributed and/or sold with any software, provided that each copy +contains the above copyright notice and this license. These can be +included either as stand-alone text files, human-readable headers or +in the appropriate machine-readable metadata fields within text or +binary files as long as those fields can be easily viewed by the user. + +3) No Modified Version of the Font Software may use the Reserved Font +Name(s) unless explicit written permission is granted by the +corresponding Copyright Holder. This restriction only applies to the +primary font name as presented to the users. + +4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font +Software shall not be used to promote, endorse or advertise any +Modified Version, except to acknowledge the contribution(s) of the +Copyright Holder(s) and the Author(s) or with their explicit written +permission. + +5) The Font Software, modified or unmodified, in part or in whole, +must be distributed entirely under this license, and must not be +distributed under any other license. The requirement for fonts to +remain under this license does not apply to any document created using +the Font Software. + +TERMINATION +This license becomes null and void if any of the above conditions are +not met. + +DISCLAIMER +THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT +OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE +COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL +DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM +OTHER DEALINGS IN THE FONT SOFTWARE. diff --git a/apps/docs/source/fonts/slate.eot b/apps/docs/source/fonts/slate.eot new file mode 100644 index 00000000..13c4839a Binary files /dev/null and b/apps/docs/source/fonts/slate.eot differ diff --git a/apps/docs/source/fonts/slate.svg b/apps/docs/source/fonts/slate.svg new file mode 100644 index 00000000..5f349823 --- /dev/null +++ b/apps/docs/source/fonts/slate.svg @@ -0,0 +1,14 @@ + + + +Generated by IcoMoon + + + + + + + + + + diff --git a/apps/docs/source/fonts/slate.ttf b/apps/docs/source/fonts/slate.ttf new file mode 100644 index 00000000..ace9a46a Binary files /dev/null and b/apps/docs/source/fonts/slate.ttf differ diff --git a/apps/docs/source/fonts/slate.woff b/apps/docs/source/fonts/slate.woff new file mode 100644 index 00000000..1e72e0ee Binary files /dev/null and b/apps/docs/source/fonts/slate.woff differ diff --git a/apps/docs/source/fonts/slate.woff2 b/apps/docs/source/fonts/slate.woff2 new file mode 100644 index 00000000..7c585a72 Binary files /dev/null and b/apps/docs/source/fonts/slate.woff2 differ diff --git a/apps/docs/source/images/HTTPerrors.png b/apps/docs/source/images/HTTPerrors.png new file mode 100644 index 00000000..f725dbcf Binary files /dev/null and b/apps/docs/source/images/HTTPerrors.png differ diff --git a/apps/docs/source/images/logo.jpeg b/apps/docs/source/images/logo.jpeg new file mode 100644 index 00000000..5799aa78 Binary files /dev/null and b/apps/docs/source/images/logo.jpeg differ diff --git a/apps/docs/source/images/method.jpeg b/apps/docs/source/images/method.jpeg new file mode 100644 index 00000000..ac143ca5 Binary files /dev/null and b/apps/docs/source/images/method.jpeg differ diff --git a/apps/docs/source/images/navbar.png b/apps/docs/source/images/navbar.png new file mode 100644 index 00000000..df38e90d Binary files /dev/null and b/apps/docs/source/images/navbar.png differ diff --git a/apps/docs/source/images/pa7.jpeg b/apps/docs/source/images/pa7.jpeg new file mode 100644 index 00000000..f930a7db Binary files /dev/null and b/apps/docs/source/images/pa7.jpeg differ diff --git a/apps/docs/source/images/pay.jpeg b/apps/docs/source/images/pay.jpeg new file mode 100644 index 00000000..ef24a525 Binary files /dev/null and b/apps/docs/source/images/pay.jpeg differ diff --git a/apps/docs/source/images/pay3.jpeg b/apps/docs/source/images/pay3.jpeg new file mode 100644 index 00000000..a4efeafa Binary files /dev/null and b/apps/docs/source/images/pay3.jpeg differ diff --git a/apps/docs/source/images/pay5.jpeg b/apps/docs/source/images/pay5.jpeg new file mode 100644 index 00000000..43cb241d Binary files /dev/null and b/apps/docs/source/images/pay5.jpeg differ diff --git a/apps/docs/source/images/pay6.png b/apps/docs/source/images/pay6.png new file mode 100644 index 00000000..d14ee5b3 Binary files /dev/null and b/apps/docs/source/images/pay6.png differ diff --git a/apps/docs/source/images/placeholder.jpeg b/apps/docs/source/images/placeholder.jpeg new file mode 100644 index 00000000..24ed5514 Binary files /dev/null and b/apps/docs/source/images/placeholder.jpeg differ diff --git a/apps/docs/source/images/recon.png b/apps/docs/source/images/recon.png new file mode 100755 index 00000000..f74dcd71 Binary files /dev/null and b/apps/docs/source/images/recon.png differ diff --git a/apps/docs/source/images/recon2.jpg b/apps/docs/source/images/recon2.jpg new file mode 100644 index 00000000..59a5dc35 Binary files /dev/null and b/apps/docs/source/images/recon2.jpg differ diff --git a/apps/docs/source/images/step10.png b/apps/docs/source/images/step10.png new file mode 100644 index 00000000..d35c90f5 Binary files /dev/null and b/apps/docs/source/images/step10.png differ diff --git a/apps/docs/source/images/step2.png b/apps/docs/source/images/step2.png new file mode 100644 index 00000000..0aea6e7e Binary files /dev/null and b/apps/docs/source/images/step2.png differ diff --git a/apps/docs/source/images/step3.png b/apps/docs/source/images/step3.png new file mode 100644 index 00000000..89eea415 Binary files /dev/null and b/apps/docs/source/images/step3.png differ diff --git a/apps/docs/source/images/step4.png b/apps/docs/source/images/step4.png new file mode 100644 index 00000000..0b6fa51a Binary files /dev/null and b/apps/docs/source/images/step4.png differ diff --git a/apps/docs/source/images/step5.png b/apps/docs/source/images/step5.png new file mode 100644 index 00000000..01413f7f Binary files /dev/null and b/apps/docs/source/images/step5.png differ diff --git a/apps/docs/source/images/step8.png b/apps/docs/source/images/step8.png new file mode 100644 index 00000000..fbe6e61d Binary files /dev/null and b/apps/docs/source/images/step8.png differ diff --git a/apps/docs/source/images/step9.png b/apps/docs/source/images/step9.png new file mode 100644 index 00000000..fe6fa67f Binary files /dev/null and b/apps/docs/source/images/step9.png differ diff --git a/apps/docs/source/includes/_api.md b/apps/docs/source/includes/_api.md new file mode 100644 index 00000000..eda1dc2e --- /dev/null +++ b/apps/docs/source/includes/_api.md @@ -0,0 +1,353 @@ + + +

PayCoCo API Docs v1.0.0

+ +> Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu. + +Payment Common Component API Documentation + +Base URLs: + +# Authentication + +- HTTP Authentication, scheme: basic + +

Health API

+ +## AppController_getVersion + + + +> Code samples + +`GET /api/v1/version` + +

Responses

+ +|Status|Meaning|Description|Schema| +|---|---|---|---| +|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|none|None| + + + +## AppController_getError + + + +> Code samples + +`GET /api/v1/error` + +

Responses

+ +|Status|Meaning|Description|Schema| +|---|---|---|---| +|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|none|None| + + + +## AppController_getHealth + + + +> Code samples + +`GET /api/v1/health` + +

Responses

+ +|Status|Meaning|Description|Schema| +|---|---|---|---| +|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|none|None| + + + +

Transaction API

+ +## TransactionController_saveTransactionEvent + + + +> Code samples + +`POST /api/v1/transaction` + +*Post Sales Event* + +> Body parameter + +```json +[ + { + "transaction_id": "72cbe1da-b08e-49d4-9a87-69afd660d14b", + "transaction_date": "2023-01-01", + "transaction_time": "13.33.31.875973", + "fiscal_close_date": "2023-01-02", + "total_transaction_amount": 30.2, + "void_indicator": false, + "miscellaneous": { + "employee_id": "SC61350" + }, + "source": { + "source_id": "SBC", + "location_id": 61, + "accepted_payment_methods": [ + "CASH", + "CHQ", + "P", + "M", + "V" + ] + }, + "payments": [ + { + "amount": 20, + "foreign_currency_amount": 15, + "currency": "USD", + "exchange_rate": 1.34, + "payment_method": "CASH", + "payment_channel": "in-person" + }, + { + "amount": 10.2, + "currency": "CAD", + "payment_method": "V", + "payment_channel": "in-person", + "terminal": { + "card_no": "5253", + "merchant_id": "20777441", + "device_id": "GA2077744108", + "invoice_no": "" + }, + "online": { + "tran_id": "", + "order_no": "" + }, + "pos": { + "approval_code": "ASWQD24342" + } + } + ], + "accounting": [ + { + "sequence": "001", + "details": { + "code": "1234", + "description": "passport photocopy" + }, + "distributions": [ + { + "line_number": "00001", + "line_description": "passport photocopy", + "line_dollar_amount": 10, + "disbursment_gl_account": { + "dist_client_code": "074", + "dist_resp_code": "66020", + "dist_service_line_code": "44275", + "dist_stob_code": "1278", + "dist_project_code": "6600000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000", + "EFT": { + "vendor": "xxx" + } + }, + "revenue_gl_account": { + "dist_client_code": "074", + "dist_resp_code": "66020", + "dist_service_line_code": "44275", + "dist_stob_code": "1474", + "dist_project_code": "6600000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000" + } + }, + { + "line_number": "00002", + "line_description": "PST G/L ", + "line_dollar_amount": 0.7, + "disbursment_gl_account": { + "dist_client_code": "022", + "dist_resp_code": "12345", + "dist_service_line_code": "66123", + "dist_stob_code": "4123", + "dist_project_code": "3200000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000" + }, + "revenue_gl_account": { + "dist_client_code": "074", + "dist_resp_code": "66020", + "dist_service_line_code": "44275", + "dist_stob_code": "1474", + "dist_project_code": "6600000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000" + } + }, + { + "line_number": "00003", + "line_dollar_amount": 0.5, + "line_description": "GST G/L ", + "disbursment_gl_account": { + "dist_client_code": "022", + "dist_resp_code": "4567", + "dist_service_line_code": "88123", + "dist_stob_code": "4123", + "dist_project_code": "3200000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000" + }, + "revenue_gl_account": { + "dist_client_code": "074", + "dist_resp_code": "66020", + "dist_service_line_code": "44275", + "dist_stob_code": "1474", + "dist_project_code": "6600000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000" + } + } + ] + }, + { + "sequence": "002", + "details": { + "code": "1234", + "description": "driving lic renewal" + }, + "distributions": [ + { + "line_number": "00001", + "line_description": "driving lic renewal", + "line_dollar_amount": 14, + "disbursment_gl_account": { + "dist_client_code": "010", + "dist_resp_code": "66213", + "dist_service_line_code": "44275", + "dist_stob_code": "1278", + "dist_project_code": "6600000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000", + "EFT": { + "vendor": "xxx" + } + }, + "revenue_gl_account": { + "dist_client_code": "074", + "dist_resp_code": "66020", + "dist_service_line_code": "44275", + "dist_stob_code": "1474", + "dist_project_code": "6600000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000" + } + } + ] + } + ] + } +] +``` + +

Parameters

+ +|Name|In|Type|Required|Description| +|---|---|---|---|---| +|body|body|any|true|none| + +> Example responses + +> default Response + +```json +{ + "data": [] +} +``` + +

Responses

+ +|Status|Meaning|Description|Schema| +|---|---|---|---| +|default|Default|Returns the parsed sales reconciliation data|Inline| + +

Response Schema

+ + + +

Parser API

+ +## ParseController_uploadFile + + + +> Code samples + +`POST /api/v1/parse/upload` + +> Body parameter + +```yaml +program: SBC +source: bcm +fileType: TDI17 +file: string + +``` + +

Parameters

+ +|Name|In|Type|Required|Description| +|---|---|---|---|---| +|body|body|object|true|none| +|» program|body|string|false|none| +|» source|body|string|false|none| +|» fileType|body|string|false|none| +|» file|body|string(binary)|false|none| + +#### Enumerated Values + +|Parameter|Value| +|---|---| +|» program|SBC| +|» program|LABOUR| +|» source|bcm| +|» source|sbc| +|» fileType|TDI17| +|» fileType|TDI34| +|» fileType|SBC_SALES| + +

Responses

+ +|Status|Meaning|Description|Schema| +|---|---|---|---| +|201|[Created](https://tools.ietf.org/html/rfc7231#section-6.3.2)|none|None| + + + +# Schemas + diff --git a/apps/docs/source/includes/_developers.md b/apps/docs/source/includes/_developers.md new file mode 100644 index 00000000..a6d63cf5 --- /dev/null +++ b/apps/docs/source/includes/_developers.md @@ -0,0 +1,327 @@ +# Developers + +## Pre-requisites + +1. Have you communicated with your finance responsible and is s/he onboard with this? +2. Information about your GL coding is required. + +## Explore our APIs +Common Component for Payments' APIs power its platform to perform automated reconciliation of payments across the various lines of businesses across British Columbia. Behind these APIs is a software layer connecting and optimizing communications networks to allow your users to simplify and streamline the payment processes and technology across the BC government payment ecosystem. + +## Before you begin +You must have one of the following accounts for login to the API Services Portal: GitHub, IDIR or BC Services Card. + +## Initial setup +Step 1: Navigate to the API Services Portal + +Step 2: Click on "For Developers". + +![For Developers](../images/step2.png?raw=true "For Developers") + +Step 3: Scroll down and click on the "Payment" API directory. + +![Payment](../images/step3.png?raw=true "Payment") + +Step 4: Click on "Request Access". + +![Request Access](../images/step4.png?raw=true "Request Access") + +Step 5: Click on "Login with IDIR". + +![Login](../images/step5.png?raw=true "Login") + +Step 6: Enter your credentials and click "Continue". + +Step 7: Click on "Create Application" and enter a name in the field titled "Application Name". Click on "Create". + +![Create Application](../images/step8.png?raw=true "Create Application") + +Step 8: Select the desired API environment and click on "Request Access". + +Step 9: Click on "Request Access" again. + +![Request Again](../images/step9.png?raw=true "Request Again") + +Step 10: Click on "Click for Credentials". + +Step 11: Save your secret credentials (client id, secret, and token) in a safe place; otherwise they will be lost once the screen disappears. Do not get the credentials checked into a public GitHub repository. If credentials are lost, you can regenerate a new secret from the API Services Portal. + +Step 12: Wait for your API Service Provider to grant access. + +Step 13: You will receive an email once access is granted. + +You are all set to start using our API. + +## Authentication +The API is secured using API keys and you need to be authenticated to receive a key. + +## Transaction API + +### View our Transaction API spec +View our sample API spec. + +### Send your first API request using cURL +### Endpoints + +#### Submit Transaction +This endpoint enables ministries to submit transaction files for processing. The endpoint expects a POST request with the transaction file attached as a binary payload. The request should also include a header with the API key for authentication. The endpoint returns a 200 OK status code if the submission is successful. If there are errors in the transaction file, the endpoint returns a 400 Bad Request status code, along with a JSON response that details the errors. +#### Endpoint URL: +/api/v1/transaction +#### Example Request: +POST /api//v1/transaction + +Host: paymentcomponent.gov.bc.ca + +Authorization: API Key + +Content-Type: application/octet-stream + +Content-Disposition: attachment; filename="transaction_file.txt" + +#### Example Response (Success): +HTTP/1.1 200 OK + +#### Example Response (Error): +HTTP/1.1 400 Bad Request +Content-Type: application/json + +{ + "errors": [ + { + "code": "INVALID_AMOUNT", + "message": "Invalid amount format" + }, + { + "code": "DUPLICATE_TRANSACTION", + "message": "Duplicate transaction found" + } + ] +} +### Send your first API request using Postman +In the Postman app, complete the following: + +Set the verb to POST. +Enter https://api-m.sandbox.paypal.com/v1/oauth2/token as the request URL. +Select the Authorization tab. +From the TYPE list, select Basic Auth. +In the Username field, enter your client ID. +In the Password field, enter your secret. +Select the Body tab. +Select the x-www-form-urlencoded option. +In the KEY field, enter grant_type. +In the VALUE field, enter client_credentials. +Select Send. + +### View logs and events +### Store your API keys +### Code Snippets +```python +url = "/api/v1/transaction" + +payload = json.dumps({ + "transaction_id": "72cbe1da-b08e-49d4-9a87-69afd660d14b", + "transaction_date": "2023-01-01", + "transaction_time": "13.33.31.875973", + "fiscal_close_date": "2023-01-02", + "total_transaction_amount": 30.2, + "void_indicator": False, + "miscellaneous": { + "employee_id": "SC61350" + }, + "source": { + "source_id": "SBC", + "location_id": 61, + "accepted_payment_methods": [ + "CASH", + "CHQ", + "P", + "M", + "V" + ] + }, + "payments": [ + { + "amount": 20, + "foreign_currency_amount": 15, + "currency": "USD", + "exchange_rate": 1.34, + "payment_method": "CASH", + "payment_channel": "in-person" + }, + { + "amount": 10.2, + "currency": "CAD", + "payment_method": "V", + "payment_channel": "in-person", + "terminal": { + "card_no": "5253", + "merchant_id": "20777441", + "device_id": "GA2077744108", + "invoice_no": "" + }, + "online": { + "tran_id": "", + "order_no": "" + }, + "pos": { + "approval_code": "ASWQD24342" + } + } + ], + "accounting": [ + { + "sequence": "001", + "details": { + "code": "1234", + "description": "passport photocopy" + }, + "distributions": [ + { + "line_number": "00001", + "line_description": "passport photocopy", + "line_dollar_amount": 10, + "disbursment_gl_account": { + "dist_client_code": "074", + "dist_resp_code": "66020", + "dist_service_line_code": "44275", + "dist_stob_code": "1278", + "dist_project_code": "6600000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000", + "EFT": { + "vendor": "xxx" + } + }, + "revenue_gl_account": { + "dist_client_code": "074", + "dist_resp_code": "66020", + "dist_service_line_code": "44275", + "dist_stob_code": "1474", + "dist_project_code": "6600000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000" + } + }, + { + "line_number": "00002", + "line_description": "PST G/L ", + "line_dollar_amount": 0.7, + "disbursment_gl_account": { + "dist_client_code": "022", + "dist_resp_code": "12345", + "dist_service_line_code": "66123", + "dist_stob_code": "4123", + "dist_project_code": "3200000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000" + }, + "revenue_gl_account": { + "dist_client_code": "074", + "dist_resp_code": "66020", + "dist_service_line_code": "44275", + "dist_stob_code": "1474", + "dist_project_code": "6600000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000" + } + }, + { + "line_number": "00003", + "line_dollar_amount": 0.5, + "line_description": "GST G/L ", + "disbursment_gl_account": { + "dist_client_code": "022", + "dist_resp_code": "4567", + "dist_service_line_code": "88123", + "dist_stob_code": "4123", + "dist_project_code": "3200000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000" + }, + "revenue_gl_account": { + "dist_client_code": "074", + "dist_resp_code": "66020", + "dist_service_line_code": "44275", + "dist_stob_code": "1474", + "dist_project_code": "6600000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000" + } + } + ] + }, + { + "sequence": "002", + "details": { + "code": "1234", + "description": "driving lic renewal" + }, + "distributions": [ + { + "line_number": "00001", + "line_description": "driving lic renewal", + "line_dollar_amount": 14, + "disbursment_gl_account": { + "dist_client_code": "010", + "dist_resp_code": "66213", + "dist_service_line_code": "44275", + "dist_stob_code": "1278", + "dist_project_code": "6600000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000", + "EFT": { + "vendor": "xxx" + } + }, + "revenue_gl_account": { + "dist_client_code": "074", + "dist_resp_code": "66020", + "dist_service_line_code": "44275", + "dist_stob_code": "1474", + "dist_project_code": "6600000", + "dist_location_code": "000000", + "dist_future_code": "0000", + "supplier_code": "000000" + } + } + ] + } + ] +}) +headers = { + 'Content-Type': 'application/json' +} + +response = requests.request("POST", url, headers=headers, data=payload) + +print(response.text) +``` + +## Reconciliaiton Report API +### Endpoints +#### Endpoint URL: +/api/v1/transaction + +#### Example Request: +POST /api/v1/transaction +Host: paymentcomponent.gov.bc.ca + +#### Example Response +#### Get Reconciliation Report +This endpoint enables ministries to retrieve a daily report of the reconciliation results. The report includes details such as the number of transactions processed, the total amount processed, and any errors encountered during reconciliation. The report is generated automatically and sent to the ministry's designated email address. The endpoint does not require any parameters or headers. +#### Endpoint URL: +#### Example Request: +GET /api/daily-report HTTP/1.1 +Host: paymentcomponent.gov.bc.ca + +#### Example Response +HTTP/1.1 200 OK +Content-Type: application/pdf +Content-Disposition: attachment; filename="daily_report.pdf" diff --git a/apps/docs/source/includes/_developers2.md b/apps/docs/source/includes/_developers2.md new file mode 100644 index 00000000..1867d63a --- /dev/null +++ b/apps/docs/source/includes/_developers2.md @@ -0,0 +1,69 @@ +# Developers + +## 2.1 Installation/Running The Project + +Please see the Readme.md + +## 2.2 Code Walkthrough + +### Generate GL Lambda + +> Code samples + +```typescript +generateGL.ts; + +export const handler = async (event?: any, context?: Context) => { + const app = await NestFactory.createApplicationContext(AppModule); + const s3manager = app.get(S3ManagerService); + const appLogger = app.get(AppLogger); + appLogger.log({ event }); + appLogger.log({ context }); + + try { + appLogger.log('...start GL Generation'); + const contents = await s3manager.getContents( + process.env.S3_LOCATION || 'bc-pcc-data-files-local', + 'aggregate/gl.json', + ); + const json = contents.Body?.toString() || ''; + const glRecord = JSON.parse(json) as GLRecord; + + const output = generateGL(glRecord); + await s3manager.putObject( process.env.S3_LOCATION || 'bc-pcc-data-files-local', 'outputs/cgigl', output); + } catch (e) { + appLogger.error(e); + } + appLogger.log('...end GL Generation'); +}; + +const generateGL = (glRecord: GLRecord) => { + return convertToFixedWidth(new GLRecord(glRecord)); +}; + +const convertToFixedWidth = (glRecord: GLRecord) => { + const BH = glRecord.batchHeader.convertFromJson(); + const BT = glRecord.trailer.convertFromJson(); + + let result = Buffer.concat([BH]); + glRecord.jv.forEach((key) => { + result = Buffer.concat([ + result, + key.header?.convertFromJson() || Buffer.from(''), + ]); + key.details?.forEach((key1) => { + result = Buffer.concat([ + result, + key1?.convertFromJson() || Buffer.from(''), + ]); + }); + }); + return Buffer.concat([result, BT]); +}; + +handler(); + +``` + +> + diff --git a/apps/docs/source/includes/_glossary.md b/apps/docs/source/includes/_glossary.md new file mode 100644 index 00000000..42f83abf --- /dev/null +++ b/apps/docs/source/includes/_glossary.md @@ -0,0 +1,12 @@ +# Glossary + +| Term | Definition | +|-------------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| API | An Application Programming Interface (API) is a software-to-software interface that provides a secure and standardized way for applications to communicate with each other to deliver requested data without user intervention. | +| API Consumer | API Consumers (organizations providing services to end-users) use the APIs available through the APS Platform in the delivery of their services. API Consumers integrate the APIs into their applications. | +| API Gateway | The API Gateway is a service that facilitates the management and execution of APIs by routing requests. It extends the capabilities of APIs with the use of controls such as authentication, authorization, rate limiting, and IP limitations allowing systems to be safely and efficiently integrated. | +| API Key | An API Key is a unique identifier (a random series of letters and numbers) used to authenticate an application accessing a specific API. The application includes the Key in each API request, and the API uses the Key to identify the application and authorize the request. The API Key is used in combination with an API Secret. | +| API Secret | The API Secret is a software-level credential (password) used to securely authenticate an application or user. The Secret is included in all API requests to identify the Consumer. The API Secret is used in combination with an API Key. The Secret is known only to the Consumer and the API gateway. It is only displayed upon creation and must be recorded by the Consumer. | +| API Provider | An API Provider, usually a developer, creates, publishes, operates, and maintains APIs in the APS Management Platform. | +| Environment | An environment in software development is the collection of stages that an application moves through during development and include development, testing, staging and production. - The development environment is the workspace for developers to design, program, debug, change, etc. an application or system. - Test teams use the testing environment to conduct tests and ensure the quality and functionality of the application or system. Testers can identify bugs, errors, or defects and review fixes. - A staging environment is a replica of a production environment with the purpose of testing code, builds, and updates to ensure quality in a production-like environment before deploying the application or system to the live (production) environment. - Production is the environment where the application or system is in operation and available to end-users. | + \ No newline at end of file diff --git a/apps/docs/source/includes/_introduction.md b/apps/docs/source/includes/_introduction.md new file mode 100644 index 00000000..0a0e0051 --- /dev/null +++ b/apps/docs/source/includes/_introduction.md @@ -0,0 +1,55 @@ +# Introduction + +## Overview + +This document provides guidance for onboarding to the Common Component for Payments' APIs, specifically for bank deposit reconciliation. + +![pay](../images/pa7.jpeg?raw=true "Pay") + +### Our Digital Government Payments Site + +Welcome to our Digital Government Payments Site your go-to resource for all things related to sending or receiving payments in the British Columbia Government. By visiting our site, you'll have access to everything you need to know to manage payments efficiently and securely. Whether you're a government program looking to collect payments or an individual seeking to make a payment, our site provides comprehensive information and tools to simplify the payment process. + +### What is the Common Component for Payments? + +The Common Component for Payments is an API-driven system designed to streamline and automate the repetitive and manual tasks that ministries face when receiving and sending payments. The system aims to enhance the quality of data and traceability of payment transactions, while reducing the possibility of errors when re-entering data between systems. + +The initial use cases for this project have been provided by Service BC to support the modernization of the Government Agent Revenue Management System (GARMS), as well as the Ministry of Labour’s Employment Standards Branch. The project team has also engaged broadly with stakeholders across government to identify opportunities for incremental improvement within government’s existing payments ecosystem. + +### Why use the Common Component for Payments? +The Common Component for Payments is being implemented to address several gaps in the current payment ecosystem in British Columbia. By providing automated reconciliation and reporting of payments, the system aims to simplify the payment processes and technology across the BC government payment ecosystem. Here are some key reasons why the Common Component for Payments is being used: + +Simplification: The Common Component for Payments is designed to simplify payment processes and technology across the BC government payment ecosystem. This means that users will not need to become financial experts to use the financial systems. + +Automated Reconciliation: The system includes automated reconciliation of payments for a variety of payment methods: credit card, cheque, cash, in-person point of sale, online payments, payments over the phone, wire transfers, Electronic Fund Transfers. This helps to reduce manual efforts and save time for ministries across British Columbia. + +Consistency: The Common Component for Payments ensures consistency in the reconciliation processes across Lines of Business (LOBs) and eliminates inconsistencies that arise due to different systems being used by different LOBs. + +Integration: The system integrates financial components such as the Provincial Treasury and CAS, which helps to streamline payment processes and ensure that all financial data is accurate and up to date. + +Error Handling: The system provides error handling where possible, which helps to minimize errors and ensure that payments are processed accurately. + +Overall, the Common Component for Payments provides a more streamlined, consistent, and efficient payment ecosystem for the BC government. + +### How does the Common Component for Payments work? +The Common Component for Payments works by receiving transaction files from ministry line of businesses through an API endpoint. These transaction files are then ingested and parsed into JSON format and loaded into the system's database. Bank files from the Provincial Treasury are also ingested and parsed into the system. + +Once the files are loaded into the database, the system's reconciliation engine compares the transaction files against the bank files received from the Provincial Treasury. + +The Common Component for Payments is designed to handle a wide range of payment types and sources across the BC government payment ecosystem, including in-person cash, cheque, and point of sale transactions. + +For Service BC, the transaction file includes line details for these types of transactions. The system then receives two Treasury files, TDI 17 and TDI 34, which contain information on the total sum of cash and cheques for each office location and line detail point of sale transactions for each office location, respectively. + +The system then uses its reconciliation engine to reconcile the transaction file against the Treasury files. Specifically, the system sums up the cash and cheques in the transaction file and reconciles them with the total sum of cash and cheques in TDI 17. The system also reconciles the line detail point of sale transactions in the transaction file with the line detail point of sale transactions in TDI 34. The reconciliation engine performs a match and kill function to automatically reconcile the transactions and detect any discrepancies. Unmatched entries are flagged as exceptions, which are further investigated and resolved by the line of business finance staff. + +## Audience +This documentation is designed for developers and product owners. + +## Project GitHub Repository +We are hosting on Amazon Web Services (AWS) for BC Government. +View the +Common Component Project repository to explore the Common Component codebase. + +## Diagrams + +![Automated Reconciliation Diagram](../images/recon.png?raw=true "Reconciliation Diagram") diff --git a/apps/docs/source/includes/_knowledgebase.md b/apps/docs/source/includes/_knowledgebase.md new file mode 100644 index 00000000..3a40fe66 --- /dev/null +++ b/apps/docs/source/includes/_knowledgebase.md @@ -0,0 +1,95 @@ +# Knowledge Base + +## What is a REST API? +API is an acronym for ‘Application Programming Interface’. It is a set of rules that allow programs communicate with each other, exposing data and functionality across the Internet in a uniform format. + +REST is short for ‘Representational State Transfer’ - an architectural pattern that describes how distributed systems can expose an interface. The term ‘REST API’ commonly refers to an API accessed using the HTTP protocol at a predefined set of URLs. + +These URLs represent any information accessed at that location, which can be returned as JSON, HTML, images, or audio files. There are one or more methods that can be performed on the given resources/information over HTTP such as: GET, POST, PUT, and DELETE. The general rule is: use GET to obtain resources, use POST to create resources, use PUT to update them, and DELETE to remove them. + +## API Best Practices +Here are some API best practices to follow: + +Consistent and intuitive API design: Your API should be designed in a way that is easy to understand, consistent across endpoints, and intuitive for developers to use. Use clear and descriptive naming conventions, standard HTTP methods, and clear documentation. + +Versioning: APIs should be versioned to ensure that changes to the API do not break existing client applications. Use semantic versioning to ensure that each new version of the API is backwards compatible with the previous version. + +Security: APIs should be secured to prevent unauthorized access and protect user data. Use standard authentication and authorization mechanisms such as OAuth2 or API keys and encrypt sensitive data with HTTPS. + +Error handling: Your API should provide clear and descriptive error messages to help developers understand what went wrong and how to fix it. Use standard HTTP status codes and error formats. + +Performance: Your API should be designed to be fast and efficient. Use caching where appropriate, minimize unnecessary data transfers, and use compression to reduce response sizes. + +Documentation: Your API should be well-documented to help developers understand how to use it. Use a consistent and easy-to-understand format for documentation, such as Swagger or OpenAPI. + +Testing: Your API should be thoroughly tested to ensure that it functions as expected. Use automated tests to verify that each endpoint works as intended, and test for performance and scalability. + +Monitoring: Your API should be monitored to ensure that it is functioning correctly and to identify issues before they become problems. Use logging and monitoring tools to track API usage, error rates, and response times. + +By following these best practices, you can ensure that your API is easy to use, secure, and reliable for your users. + +## Working with cURL +Curl is a command-line tool used to transfer data over various protocols such as HTTP, HTTPS, FTP, FTPS, SFTP, etc. Here is a beginner's guide to using the curl command line: + +### Basic GET request: + +To make a basic GET request, simply use the curl command followed by the URL: + +`curl https://www.example.com` + +This will retrieve the HTML content of the webpage at https://www.example.com. + +### Adding headers: + +You can add headers to your request using the -H option followed by the header name and value: + +`curl -H "Content-Type: application/json" https://api.example.com/data` + +This will add the "Content-Type" header with a value of "application/json" to your request. + +### Sending data: + +You can send data with your request using the -d option followed by the data: + +`curl -d '{"name": "John", "age": 30}' https://api.example.com/data` + +This will send the JSON data {"name": "John", "age": 30} with your request. + +### Authentication: + +You can add authentication to your request using the -u option followed by your username and password: + +`curl -u username:password https://api.example.com/data` + +This will send your username and password with your request for authentication. + +### Saving response: + +You can save the response to a file using the -o option followed by the filename: + +`curl -o output.html https://www.example.com` + + +This will save the HTML content of the webpage at `https://www.example.com` to the file "output.html". + +### Basic POST request: + +To send a POST request with CURL, you can use the following command: + +`curl -X POST -H "Content-Type: application/json" -d '{"key1":"value1", "key2":"value2"}' http://example.com/api/endpoint` + +Here's a breakdown of the command: + +`curl`: the command to use CURL + +`-X POST`: specifies that we want to use the HTTP POST method + +`-H "Content-Type: application/json"`: sets the content type header to JSON + +`-d '{"key1":"value1", "key2":"value2"}'`: specifies the data to send in the POST request, in this case a JSON object + +`http://example.com/api/endpoint`: the URL of the API endpoint to which the request is being sent +You can modify the data and URL to match the specific requirements of the API you are using. + +These are some of the basic features of curl. There are many more options and configurations available, so it's worth reading the documentation to learn more. + diff --git a/apps/docs/source/includes/_readme.md b/apps/docs/source/includes/_readme.md new file mode 100644 index 00000000..56e188ac --- /dev/null +++ b/apps/docs/source/includes/_readme.md @@ -0,0 +1,28 @@ + +## Payments Common Component + +[![Lifecycle:Experimental](https://img.shields.io/badge/Lifecycle-Experimental-339999)]() + +### Scope Of Project + + TBD + +### Technical Setup + +Prerequisites: + +- Docker +- Docker Compose +- Python 3 & pip +- AWS Cli V2 - (https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) +- Localstack `awslocal` https://docs.localstack.cloud/integrations/aws-cli/#localstack-aws-cli-awslocal +- Cyberduck - To browse s3 files + + +#### Yarn Workspaces Setup + +This project is setup using yarn workspaces for the lambda functions. + +Yarn V2 is the latest version. + +Yarn V2 needs to be enabled in node js versions 16 and above - Follow these steps to get yarn setup locally - https://yarnpkg.com/getting-started/install \ No newline at end of file diff --git a/apps/docs/source/includes/_support.md b/apps/docs/source/includes/_support.md new file mode 100644 index 00000000..691c2c5e --- /dev/null +++ b/apps/docs/source/includes/_support.md @@ -0,0 +1,2 @@ +# Support +For any issues or questions related to the Common Component for Payments API, please contact our support team. \ No newline at end of file diff --git a/apps/docs/source/includes/_troubleshooting.md b/apps/docs/source/includes/_troubleshooting.md new file mode 100644 index 00000000..6cced469 --- /dev/null +++ b/apps/docs/source/includes/_troubleshooting.md @@ -0,0 +1,6 @@ +# Troubleshooting and Security + +## Error Handling +Common Component for Payments uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided, returning a JSON response that includes a list of errors encountered during processing. Codes in the 5xx range indicate an error with the server. + +![Errors](../images/HTTPerrors.png?raw=true "Errors") \ No newline at end of file diff --git a/apps/docs/source/includes/_userguide.md b/apps/docs/source/includes/_userguide.md new file mode 100644 index 00000000..97a06415 --- /dev/null +++ b/apps/docs/source/includes/_userguide.md @@ -0,0 +1,18 @@ +# User Guide - Endpoints + +**BaseURL(s):** + +- local: `url` +- dev: `url` + + +## 1.1 Sales (POST) + +### Example: + +- endpoint: `/sales` +- params: + - example + - exmaple: + - example + diff --git a/apps/docs/source/index.html.md b/apps/docs/source/index.html.md new file mode 100644 index 00000000..6325db81 --- /dev/null +++ b/apps/docs/source/index.html.md @@ -0,0 +1,25 @@ +--- +title: Common Component for Payments +language_tabs: + - typescript: Typescript + +toc_footers: [] +includes: + - introduction + - developers + - troubleshooting + - support + - glossary + - readme.md + - api + +search: true +highlight_theme: darkula +headingLevel: 1 + +code_clipboard: true + +meta: + - name: description + content: Documentation for CCFP +--- diff --git a/apps/docs/source/javascripts/all.js b/apps/docs/source/javascripts/all.js new file mode 100644 index 00000000..5f5d4067 --- /dev/null +++ b/apps/docs/source/javascripts/all.js @@ -0,0 +1,2 @@ +//= require ./all_nosearch +//= require ./app/_search diff --git a/apps/docs/source/javascripts/all_nosearch.js b/apps/docs/source/javascripts/all_nosearch.js new file mode 100644 index 00000000..026e5a20 --- /dev/null +++ b/apps/docs/source/javascripts/all_nosearch.js @@ -0,0 +1,27 @@ +//= require ./lib/_energize +//= require ./app/_copy +//= require ./app/_toc +//= require ./app/_lang + +function adjustLanguageSelectorWidth() { + const elem = $('.dark-box > .lang-selector'); + elem.width(elem.parent().width()); +} + +$(function() { + loadToc($('#toc'), '.toc-link', '.toc-list-h2', 10); + setupLanguages($('body').data('languages')); + $('.content').imagesLoaded( function() { + window.recacheHeights(); + window.refreshToc(); + }); + + $(window).resize(function() { + adjustLanguageSelectorWidth(); + }); + adjustLanguageSelectorWidth(); +}); + +window.onpopstate = function() { + activateLanguage(getLanguageFromQueryString()); +}; diff --git a/apps/docs/source/javascripts/app/_copy.js b/apps/docs/source/javascripts/app/_copy.js new file mode 100644 index 00000000..4dfbbb6c --- /dev/null +++ b/apps/docs/source/javascripts/app/_copy.js @@ -0,0 +1,15 @@ +function copyToClipboard(container) { + const el = document.createElement('textarea'); + el.value = container.textContent.replace(/\n$/, ''); + document.body.appendChild(el); + el.select(); + document.execCommand('copy'); + document.body.removeChild(el); +} + +function setupCodeCopy() { + $('pre.highlight').prepend('
Copy to Clipboard
'); + $('.copy-clipboard').on('click', function() { + copyToClipboard(this.parentNode.children[1]); + }); +} diff --git a/apps/docs/source/javascripts/app/_lang.js b/apps/docs/source/javascripts/app/_lang.js new file mode 100644 index 00000000..cc5ac8b6 --- /dev/null +++ b/apps/docs/source/javascripts/app/_lang.js @@ -0,0 +1,171 @@ +//= require ../lib/_jquery + +/* +Copyright 2008-2013 Concur Technologies, Inc. + +Licensed under the Apache License, Version 2.0 (the "License"); you may +not use this file except in compliance with the License. You may obtain +a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +License for the specific language governing permissions and limitations +under the License. +*/ +;(function () { + 'use strict'; + + var languages = []; + + window.setupLanguages = setupLanguages; + window.activateLanguage = activateLanguage; + window.getLanguageFromQueryString = getLanguageFromQueryString; + + function activateLanguage(language) { + if (!language) return; + if (language === "") return; + + $(".lang-selector a").removeClass('active'); + $(".lang-selector a[data-language-name='" + language + "']").addClass('active'); + for (var i=0; i < languages.length; i++) { + $(".highlight.tab-" + languages[i]).hide(); + $(".lang-specific." + languages[i]).hide(); + } + $(".highlight.tab-" + language).show(); + $(".lang-specific." + language).show(); + + window.recacheHeights(); + + // scroll to the new location of the position + if ($(window.location.hash).get(0)) { + $(window.location.hash).get(0).scrollIntoView(true); + } + } + + // parseURL and stringifyURL are from https://github.com/sindresorhus/query-string + // MIT licensed + // https://github.com/sindresorhus/query-string/blob/7bee64c16f2da1a326579e96977b9227bf6da9e6/license + function parseURL(str) { + if (typeof str !== 'string') { + return {}; + } + + str = str.trim().replace(/^(\?|#|&)/, ''); + + if (!str) { + return {}; + } + + return str.split('&').reduce(function (ret, param) { + var parts = param.replace(/\+/g, ' ').split('='); + var key = parts[0]; + var val = parts[1]; + + key = decodeURIComponent(key); + // missing `=` should be `null`: + // http://w3.org/TR/2012/WD-url-20120524/#collect-url-parameters + val = val === undefined ? null : decodeURIComponent(val); + + if (!ret.hasOwnProperty(key)) { + ret[key] = val; + } else if (Array.isArray(ret[key])) { + ret[key].push(val); + } else { + ret[key] = [ret[key], val]; + } + + return ret; + }, {}); + }; + + function stringifyURL(obj) { + return obj ? Object.keys(obj).sort().map(function (key) { + var val = obj[key]; + + if (Array.isArray(val)) { + return val.sort().map(function (val2) { + return encodeURIComponent(key) + '=' + encodeURIComponent(val2); + }).join('&'); + } + + return encodeURIComponent(key) + '=' + encodeURIComponent(val); + }).join('&') : ''; + }; + + // gets the language set in the query string + function getLanguageFromQueryString() { + if (location.search.length >= 1) { + var language = parseURL(location.search).language; + if (language) { + return language; + } else if (jQuery.inArray(location.search.substr(1), languages) != -1) { + return location.search.substr(1); + } + } + + return false; + } + + // returns a new query string with the new language in it + function generateNewQueryString(language) { + var url = parseURL(location.search); + if (url.language) { + url.language = language; + return stringifyURL(url); + } + return language; + } + + // if a button is clicked, add the state to the history + function pushURL(language) { + if (!history) { return; } + var hash = window.location.hash; + if (hash) { + hash = hash.replace(/^#+/, ''); + } + history.pushState({}, '', '?' + generateNewQueryString(language) + '#' + hash); + + // save language as next default + if (localStorage) { + localStorage.setItem("language", language); + } + } + + function setupLanguages(l) { + var defaultLanguage = null; + if (localStorage) { + defaultLanguage = localStorage.getItem("language"); + } + + languages = l; + + var presetLanguage = getLanguageFromQueryString(); + if (presetLanguage) { + // the language is in the URL, so use that language! + activateLanguage(presetLanguage); + + if (localStorage) { + localStorage.setItem("language", presetLanguage); + } + } else if ((defaultLanguage !== null) && (jQuery.inArray(defaultLanguage, languages) != -1)) { + // the language was the last selected one saved in localstorage, so use that language! + activateLanguage(defaultLanguage); + } else { + // no language selected, so use the default + activateLanguage(languages[0]); + } + } + + // if we click on a language tab, activate that language + $(function() { + $(".lang-selector a").on("click", function() { + var language = $(this).data("language-name"); + pushURL(language); + activateLanguage(language); + return false; + }); + }); +})(); diff --git a/apps/docs/source/javascripts/app/_search.js b/apps/docs/source/javascripts/app/_search.js new file mode 100644 index 00000000..0b0ccd97 --- /dev/null +++ b/apps/docs/source/javascripts/app/_search.js @@ -0,0 +1,102 @@ +//= require ../lib/_lunr +//= require ../lib/_jquery +//= require ../lib/_jquery.highlight +;(function () { + 'use strict'; + + var content, searchResults; + var highlightOpts = { element: 'span', className: 'search-highlight' }; + var searchDelay = 0; + var timeoutHandle = 0; + var index; + + function populate() { + index = lunr(function(){ + + this.ref('id'); + this.field('title', { boost: 10 }); + this.field('body'); + this.pipeline.add(lunr.trimmer, lunr.stopWordFilter); + var lunrConfig = this; + + $('h1, h2').each(function() { + var title = $(this); + var body = title.nextUntil('h1, h2'); + lunrConfig.add({ + id: title.prop('id'), + title: title.text(), + body: body.text() + }); + }); + + }); + determineSearchDelay(); + } + + $(populate); + $(bind); + + function determineSearchDelay() { + if (index.tokenSet.toArray().length>5000) { + searchDelay = 300; + } + } + + function bind() { + content = $('.content'); + searchResults = $('.search-results'); + + $('#input-search').on('keyup',function(e) { + var wait = function() { + return function(executingFunction, waitTime){ + clearTimeout(timeoutHandle); + timeoutHandle = setTimeout(executingFunction, waitTime); + }; + }(); + wait(function(){ + search(e); + }, searchDelay); + }); + } + + function search(event) { + + var searchInput = $('#input-search')[0]; + + unhighlight(); + searchResults.addClass('visible'); + + // ESC clears the field + if (event.keyCode === 27) searchInput.value = ''; + + if (searchInput.value) { + var results = index.search(searchInput.value).filter(function(r) { + return r.score > 0.0001; + }); + + if (results.length) { + searchResults.empty(); + $.each(results, function (index, result) { + var elem = document.getElementById(result.ref); + searchResults.append("
  • " + $(elem).text() + "
    • "); + }); + highlight.call(searchInput); + } else { + searchResults.html('
  • '); + $('.search-results li').text('No Results Found for "' + searchInput.value + '"'); + } + } else { + unhighlight(); + searchResults.removeClass('visible'); + } + } + + function highlight() { + if (this.value) content.highlight(this.value, highlightOpts); + } + + function unhighlight() { + content.unhighlight(highlightOpts); + } +})(); + diff --git a/apps/docs/source/javascripts/app/_toc.js b/apps/docs/source/javascripts/app/_toc.js new file mode 100644 index 00000000..f70bdc0f --- /dev/null +++ b/apps/docs/source/javascripts/app/_toc.js @@ -0,0 +1,122 @@ +//= require ../lib/_jquery +//= require ../lib/_imagesloaded.min +;(function () { + 'use strict'; + + var htmlPattern = /<[^>]*>/g; + var loaded = false; + + var debounce = function(func, waitTime) { + var timeout = false; + return function() { + if (timeout === false) { + setTimeout(function() { + func(); + timeout = false; + }, waitTime); + timeout = true; + } + }; + }; + + var closeToc = function() { + $(".toc-wrapper").removeClass('open'); + $("#nav-button").removeClass('open'); + }; + + function loadToc($toc, tocLinkSelector, tocListSelector, scrollOffset) { + var headerHeights = {}; + var pageHeight = 0; + var windowHeight = 0; + var originalTitle = document.title; + + var recacheHeights = function() { + headerHeights = {}; + pageHeight = $(document).height(); + windowHeight = $(window).height(); + + $toc.find(tocLinkSelector).each(function() { + var targetId = $(this).attr('href'); + if (targetId[0] === "#") { + headerHeights[targetId] = $("#" + $.escapeSelector(targetId.substring(1))).offset().top; + } + }); + }; + + var refreshToc = function() { + var currentTop = $(document).scrollTop() + scrollOffset; + + if (currentTop + windowHeight >= pageHeight) { + // at bottom of page, so just select last header by making currentTop very large + // this fixes the problem where the last header won't ever show as active if its content + // is shorter than the window height + currentTop = pageHeight + 1000; + } + + var best = null; + for (var name in headerHeights) { + if ((headerHeights[name] < currentTop && headerHeights[name] > headerHeights[best]) || best === null) { + best = name; + } + } + + // Catch the initial load case + if (currentTop == scrollOffset && !loaded) { + best = window.location.hash; + loaded = true; + } + + var $best = $toc.find("[href='" + best + "']").first(); + if (!$best.hasClass("active")) { + // .active is applied to the ToC link we're currently on, and its parent