@bilyai/types v1.0.32

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

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": "john.doe@example.com"
  },
  "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.

Client Type

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

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": "john.doe@example.com",
    "phone": "+1234567890",
    "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

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

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