@bilyai/types

Reference Documentation for BilyPayload Data Type

Overview

This document describes the BilyPayload type used in systems requiring a comprehensive payload incorporating client data, order details, and product information. It's primarily utilized in contexts like user activity tracking, analytics, and data integration tasks.

BilyPayload Type Definition

BilyPayload consolidates multiple pieces of data about a user session or activity, potentially including client details, order information, and a list of products being interacted with.

Fields Description

Field	Type	Optional	Description
client	Client	Yes	Details of the client involved in the transaction.
order	Order	Yes	Order details, if applicable.
products	Array	Yes	List of products involved in the transaction.
pageTitle	string	Yes	The title of the page from which the payload is sent.
userAgent	string	Yes	Browser or client identifier string.
ip	string	Yes	IP address from which the session is initiated.
referrer	string	Yes	Referring URL, if the user came from another site.
sourceUrl	string	Yes	The URL of the page that initiated the payload.
source	'app' | 'web'	Yes	Indicates whether the payload comes from an app or web platform.
searchQuery	string	Yes	Contains the search terms input by the user, reflecting the user's interests or immediate needs.
category	string	Yes	Page category visited
[key: string]	any	Yes	Allows for additional properties as needed for flexibility.

Automatic Data Detection

• Fields such as pageTitle, userAgent, ip, referrer, and sourceUrl can be detected automatically by Bily tracking systems, especially in browser-based environments. These fields are optional when tracking via client devices and can be auto-populated to reduce manual data entry and ensure accuracy.

Client, Order, and Product Documentation

The BilyPayload utilizes several complex types that are documented separately:

• Client: Client Type Documentation
• Order: Order Type Documentation
• Product: Product Type Documentation

Implementation Guidelines

1. Automation and Flexibility:

   • Leverage Bily's capability to automatically detect certain fields to streamline data collection processes and reduce client-side scripting requirements.
   • Flexibly integrate additional data as needed with the [key: string]: any pattern for dynamic adaptation to varied business needs.

2. Data Integrity:

   • Validate data types and enforce quality checks before processing payloads to ensure that received data conforms to expected formats.

3. Integration with Existing Systems:

   • Seamlessly integrate BilyPayload into existing CRM, e-commerce platforms, or custom business applications using well-documented APIs and data handling protocols.

Example Usage

Here is how a minimal BilyPayload might be structured in a JSON format:

{
  "client": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "[e-mail]"
  },
  "products": [
    {
      "id": "prod001",
      "name": "Wireless Keyboard",
      "price": 99.99,
      "currency": "USD",
      "quantity": 1
    }
  ]
}

Reference Documentation for User Data Type Management

Overview

This documentation details the data structures for managing personal and sensitive user information. Bily assures robust encryption of all sensitive data tracked, ensuring compliance with global data protection standards.

Data Encryption Policy

Bily is committed to encrypting all sensitive data, including data in transit and at rest, using industry-standard cryptographic methods.

Types of Data to be Encrypted:

• Personal identification information (e.g., names, emails, phone numbers).
• Demographic information (e.g., date of birth, gender).
• Location data (e.g., addresses).

Data Type Definitions

Address Type

Represents the postal address of a user or client, with all fields encrypted.

Field	Type	Optional	Description	Encryption
city	string	Yes	City or locality of the address.	Encrypted
state	string	Yes	State, province, or region of the address.	Encrypted
zip	string	Yes	Postal or ZIP code of the address.	Encrypted
country	string	Yes	Country of the address.	Encrypted

Client Type

Contains personal and contact details of a user, ensuring encryption of sensitive data.

Field	Type	Optional	Description	Encryption
firstname	string	Yes	First name of the client.	Encrypted
lastname	string	Yes	Last name of the client.	Encrypted
dateOfBirth	string	Yes	Date of birth in ISO 8601 format.	Encrypted
email	string	Yes	Email address of the client.	Encrypted
phone	string	Yes	Telephone number of the client.	Encrypted
gender	string	Yes	Gender of the client.	Encrypted
address	Address	Yes	Nested Address object with location details.	Encrypted

Implementation Guidelines

1. Optional Fields:

All fields in the types are optional. Ensure that the application logic treats unspecified fields appropriately and provides graceful handling or defaults as necessary.

2. Validation:

• For email fields, implement standard email format validation.
• For phone fields, consider validating based on the international phone number format.
• For dateOfBirth, ensure the format is strictly verified and logically valid (e.g., not future-dated).

3. Security and Privacy:

Securely store sensitive information such as personal details, especially email, phone, and address.

4. Security and Privacy:

Respect privacy laws applicable to the user's data jurisdiction, such as GDPR in Europe or CCPA in California, which govern the handling of personal information.

Example Usage in API

Example JSON payload for creating a new client, demonstrating encryption:

{
  "client": {
    "firstname": "John",
    "lastname": "Doe",
    "dateOfBirth": "1990-05-15",
    "email": "[e-mail]",
    "phone": "[phone]",
    "gender": "male",
    "address": {
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "USA"
    }
  }
}

Reference Documentation for Product Data Type

Overview

This document outlines the structure for the Product data type, utilized in systems like e-commerce platforms, inventory management systems, and other applications that require detailed product information.

Product Type Definition

Describes the details of products, including identifiers, pricing, and classification.

Fields Description

Field	Type	Optional	Description
id	string	No	Unique identifier for the product.
name	string	No	Name of the product.
price	number	No	Cost of one unit of the product.
currency	string	No	Currency in which the price is expressed (e.g., USD, EUR).
quantity	number	Yes	Number of units available or in the order.
sku	string	Yes	Stock Keeping Unit; unique inventory identifier.
category	string	Yes	Category of the product.
brand	string	Yes	Brand of the product.
image	string	Yes	URL or path to an image of the product.

Implementation Guidelines

1. Required vs. Optional Fields:

   • Fields id, name, price, currency, and quantity are mandatory.
   • Fields sku, category, brand, and image are optional and should be included when relevant.

2. Validation:

   • ID: Ensure uniqueness.
   • Price: Must be a non-negative number.
   • Currency: Validate based on standard currency codes.
   • SKU: Should be unique if provided.
   • Image URLs: Should be valid and accessible.

3. API Use:

   • Secure endpoints that expose product data.
   • Include comprehensive API documentation outlining field values and examples.

Example Usage

An example JSON representation of a Product:

{
  "id": "prod123",
  "name": "Wireless Mouse",
  "price": 25.99,
  "currency": "USD",
  "quantity": 100,
  "sku": "WM12345",
  "category": "Electronics",
  "brand": "TechGadget",
  "image": "https://example.com/images/wireless-mouse.jpg"
}

Reference Documentation for Order Data Type

Overview

This document specifies the Order data type used for managing and recording transactions in systems such as e-commerce platforms, point of sale systems, and inventory management software. The structure captures all essential aspects of an order transaction.

Order Type Definition

The Order data type holds data related to a customer's order, including identification, total pricing, and product details included in the order.

Fields Description

Field	Type	Optional	Description
id	string	No	Unique identifier for the order.
total	number	Yes	The total cost of the order.
currency	string	Yes	The currency in which the total cost is expressed (e.g., USD, EUR).
products	Array	Yes	A list of products included in the order.
tax	number	Yes	The value of payed taxes.
shippingFees	number	Yes	The value of shipping fees.
discount	number	Yes	Value of discount.
discountCode	string	Yes	Used discount code.

Details of Embedded Type Product

Refer to product data type documentation.

1. Order Validation:

   • Ensure the id is unique across the order management system.
   • Validate total to reflect the sum of products included, considering their price and quantity.
   • Confirm currency consistency across total and all Product prices, or implement accurate currency conversion methods.

2. Data Integrity:

   • Ensure that product details are accurate and correspond with the current catalog data at the time of the order.
   • Handle changes in product availability or price adjustments efficiently.

Example Usage

An example JSON representation of an Order:

{
  "id": "order123",
  "total": 299.99,
  "currency": "USD",
  "products": [
    {
      "id": "prod001",
      "name": "Bluetooth Keyboard",
      "price": 59.99,
      "currency": "USD",
      "quantity": 1,
      "sku": "BK987",
      "category": "Electronics",
      "brand": "KeyTech",
      "image": "https://example.com/images/keyboard.jpg"
    },
    {
      "id": "prod002",
      "name": "Wireless Mouse",
      "price": 24.99,
      "currency": "USD",
      "quantity": 2,
      "sku": "WM123",
      "category": "Electronics",
      "brand": "ClickPlus",
      "image": "https://example.com/images/mouse.jpg"
    }
  ]
}

Events types

Event	Description
Search	User initiates a search, indicating interest or need for specific information, products, or services.
Category Viewed	User browses a specific category, which could be a product category, content type, or service grouping.
Product Viewed	User views details of a product, plan, or piece of content. Includes viewing pages for services or software features.
Add to Wishlist	User saves items or content to a personal list for later review or purchase, applicable for products or saving content like articles or videos.
View Wishlist	User reviews items or content saved in their wishlist, signifying ongoing interest.
Remove from Wishlist	User removes items or content from their wishlist, indicating a change in preference or interest.
Product Added	User adds a product, subscription plan, or paid content to their cart, showing intent to purchase or subscribe.
Cart Viewed	User views their cart or list of intended purchases, reviewing chosen items before final actions.
Remove from Cart	User removes an item from their cart, reflecting a change in decision regarding a potential purchase.
Cart Updated	User changes the quantity or selection of items in the cart, adjusting their intended purchase details.
Checkout Started	User begins the checkout process, indicating readiness to finalize a purchase or subscription.
Payment Add Contact Info	User enters contact information during the checkout process, necessary for processing the transaction or for communication.
Payment Add Shipping Info	User adds shipping information, relevant for physical goods delivery or geographical service personalization.
Payment Add Address Info	User provides billing or service address details, crucial for invoicing and service provision.
Payment Info Entered	User inputs payment details, a critical step towards transaction completion.
Order Completed	User successfully completes an order or subscription, resulting in a transaction or engagement agreement.
Subscription	User subscribes to a service or content platform, initiating a recurring relationship or continuous access.
Subscription Updated	User modifies their subscription details or preferences, which may involve changing the plan level, altering features, or updating personal information.
Subscription Cancelled	User terminates their subscription, ending their recurring access or membership.
Subscription Renewed	User's subscription is automatically or manually renewed, extending their access and terms under the existing agreement.
Order Updated	Changes made to an existing order post-purchase, which could involve modifications to subscriptions or service terms.
Order Cancelled	User cancels an order or subscription, discontinuing the purchase or service relationship.
Newsletter	User subscribes to a newsletter, indicating interest in regular updates, news, or promotional content.
Lead	User shows potential interest in a service or product, often through a form submission or a trial request, initiating a sales lead.
Contact Form Submitted	User submits a query or feedback via contact forms, important for user support and engagement.
Login	User logs into their account, initiating access to personalized services, content, or account management.
Logout	User logs out of their account, ending their current session securely.