Create SDK Documentation

[sfaria27]

As a team member, I need to create straightforward documentation for the SDK, covering scraping, authentication, and licensing. The documentation should be easily understandable for developers integrating the SDK into their applications.

The scraping feature should include:

• tokenization
• fetching emails for the list of known receipt senders
• extraction of receipt data
• sending data to the cloud
• the ability to scan for only new emails upon logins after the initial scrape

[ricardobrg]

TIKI Data Provider Client Library (Capacitor + Vue.js)

The TIKI Data Provider API is structured on HTTP, allowing seamless compatibility with any standard HTTP client for sending requests and handling responses.

Functioning as a Capacitor Plugin, the Client Library serves as a convenient wrapper for interactions with the TIKI Data Provider API. It simplifies the process by managing API authentication and data upload. Additionally, it provides methods for authenticating with the Gmail API, streamlining the download of receipt emails from a predefined list of known receipt senders, thereby enhancing the efficiency of email scraping.

Although the client library presents the option for authentication with Gmail and Outlook APIs, it remains entirely optional. Users can leverage the library to send email data to the TIKI API without integrating with Gmail or Outlook.

Authentication

TIKI API

Authentication with the TIKI Data Provider API is handled internally by the Client Library. Upon initialization, the library requests JWT tokens from TIKI Auth and manages their lifecycle, refreshing when necessary.

Gmail and Outlook APIs

Authentication with Gmail and Outlook APIs is handled with OAuth2 following Gmail API guidelines. To authenticate with these APIs, the user is redirected to an external login URL from the requested service, which will prompt the user's email and password. After authenticating with Gmail or Outlook, the user is redirected back to the app. An authentication token from the service is saved in the device's encrypted storage and is only accessible internally by the app during its execution.

NOTE: To use Gmail or Outlook APIs, the app must have an API key from these services.

Data Protection

The client library does not persist email data and serves as a wrapper for transporting data between the email APIs, the client app, and the TIKI Data Provider API. Data is kept in the device's memory while being downloaded from email APIs and sent to the TIKI API and is completely removed when the information is sent or the app is closed. The authentication tokens' lifecycle is handled by the respective services and can be revoked by the user at any time. All HTTP requests are conducted through HTTPS using TLS 1.3, encrypting the information during transport between the user's device and TIKI Data Provider API.

Initialization

To initialize, inject the TikiService and pass in your system's unique identifier for the user. If you use emails (you shouldn't 😝), it's recommended to hash them first.

With Vue >=3.0.0

<script setup lang="ts">
  import { inject } from "vue";
  import { type TikiService } from "@mytiki/data-provider";
  
  const tiki: TikiService | undefined = inject("Tiki");
  tiki?.initialize(id).then(() => console.log("Tiki Initialized"));
</script>

With Vue 2.7.15

<script setup lang="ts">
  import { inject } from "vue";
  import { type TikiService } from "@mytiki/data-provider-vue2";
  
  const tiki: TikiService | undefined = inject("Tiki");
  tiki?.initialize(id).then(() => console.log("Tiki Initialized"));
</script>

Send E-mail Data

Utilize the TikiService.email method to send email data to the TIKI API. This method returns a Promise containing the receipt ID, which can be employed to monitor the progress of receipt parsing through the API.

This method receives a TikiEmailRequest object composed of:

• Sender Email (String)
• Email body (String)
• Email attachments (Array of Files)

Before sending the email data, the /licenses API endpoint is invoked to validate the user's license. In case of an invalid license, the user is prompted to accept the license terms before any data can be submitted to the server.

Example

const emailRequest = {
  senderEmail: "john.doe@example.com",
  emailBody: "Thank you for your purchase!",
  attachments: [file1, file2]
};

const receiptId = await TikiService.email(emailRequest);

Monitoring Receipt Parsing Progress

To check the parsing progress of a receipt, utilize the TikiService.progress(receiptId) method. This method calls the /emails endpoint passing a receiptId which returns one of the following statuses: PROCESSING, REJECTED, or PUBLISHED.

const status = await TikiService.progress(receiptId);

Scrape Receipts from Gmail/Outlook

The client library wraps the Gmail and Outlook API calls to handle authorization and email parsing. It handles user authentication, email download from hundreds of known receipt senders, and sending the data to TIKI API. The authentication is handled with OAuth2, and the authorization token is encrypted in the user's device. No user email data is retained in the app. Downloaded emails are discarded after sending the data to TIKI. The last scrape date is saved locally on the device to prevent the download of duplicate emails, which would be discarded when uploaded because of duplicate receipts.

Initialization

To use Gmail and/or Outlook APIs, the app must be configured with an API key from these services.

Gmail

<script setup lang="ts">
  import { inject } from "vue";
  import { type TikiService } from "@mytiki/data-provider";
  
  const tiki: TikiService | undefined = inject("Tiki");
  tiki?.gmailApiKey("GMAIL_API_KEY").then(() => console.log("Gmail configured"));
</script>

Outlook

<script setup lang="ts">
  import { inject } from "vue";
  import { type TikiService } from "@mytiki/data-provider";
  
  const tiki: TikiService | undefined = inject("Tiki");
  tiki?.outlookApiKey("OUTLOOK_API_KEY").then(() => console.log("Outlook configured"));
</script>

Authentication

The client library handles the authentication with Gmail and Outlook APIs with OAuth2. The user is redirected to the login page from the respective services where they will be prompted for their email and password. After login, the user is redirected back to the app, and the authentication token is encrypted and saved in the device's secure storage. It will be used to download the emails.

The user can add multiple Gmail and Outlook accounts in the client library.

Gmail

<script setup lang="ts">
  import { inject } from "vue";
  import { type TikiService } from "@mytiki/data-provider";
  
  const tiki: TikiService | undefined = inject("Tiki");
  tiki?.gmailApiKey("GMAIL_API_KEY").then(() => console.log("Gmail configured"));
</script>

Outlook

<script setup lang="ts">
  import { inject } from "vue";
  import { type TikiService } from "@mytiki/data-provider";
  
  const tiki: TikiService | undefined = inject("Tiki");
  tiki?.outlookApiKey("OUTLOOK_API_KEY").then(() => console.log("Outlook configured"));
</script>

List Connected Accounts

To get a list of all connected accounts, use the TikiService.accounts() method. It will return an array of the emails that are currently connected.

Example

const connectedAccounts = await TikiService.accounts();
console.log(connectedAccounts);

Email Scraping

To scrape data from all connected email accounts, call the TikiService.scrape() method. It will download the latest receipt emails from all connected accounts and send them to the TIKI Data Provider API. It returns a Promise that completes with a list of the receiptIds that were sent in the request.

Example

const scrapedReceipts = await TikiService.scrape();
console.log(scrapedReceipts);