SDK: Define Public API in client SDK

[rjvelazco]

Parent Issue

#30943

Overview

Currently, our NPM package lacks clear organization regarding which utility functions, constants, and helpers are meant for public use versus internal use. This lack of structure can lead to confusion and misuse of internal functions. To address this, we need to revisit our exports, create a public_api file, and ensure only necessary functions and utilities are exposed to the end users.

Task

1. Identify and classify all utility functions, constants, and helpers as either "Public API" or "Internal".
2. Refactor the package to export only the designated public API items from the main entry points.
3. Create a public_api.ts file to define and organize the public API.
4. Document the public API with usage examples and explanations.
5. Add internal aliases to facilitate easier development.

Example of Adding public_api Reference in the Build

File: project.json

{
  "build": {
    "executor": "@nx/rollup:rollup",
    "outputs": ["{options.outputPath}"],
    "options": {
      "format": ["esm", "cjs"],
      "compiler": "tsc",
      "generateExportsField": true,
      "assets": [{ "input": "libs/sdk/client", "output": ".", "glob": "*.md" }],
      "outputPath": "dist/libs/sdk/client",
      "main": "${PUBLIC_API_PATH}",
      "tsConfig": "libs/sdk/client/tsconfig.lib.json"
    }
  }
}

Proposed Objective

Core Features

Proposed Priority

Priority 3 - Average

Acceptance Criteria

• The main entry points (index.js and relevant submodules) export only the items designated as Public API.
• Internal aliases are established in the project to facilitate easier development.
• The public API is well-documented, including usage examples and explanations.
• Updated package documentation to clearly define and explain the public API.
• A document is created to justify why each function, constant, or utility is exported or kept internal.
• A comprehensive list of all utility functions, constants, and helpers, categorized into Public API and Internal.

External Links... Slack Conversations, Support Tickets, Figma Designs, etc.

No response

Assumptions & Initiation Needs

• A clear understanding of which functions and utilities are intended for public use versus internal use.
• Collaboration with the development team to ensure accurate classification and refactoring.

Quality Assurance Notes & Workarounds

• Verify that the package's public API is accessible and functions correctly in various environments (e.g., Node.js, browser).
• Ensure internal utilities are not exposed or accessible through the package's public API.
• Test the package with existing projects to check for any unexpected regressions or issues.
• Ensure that all public API changes are backward compatible or properly documented if breaking changes are unavoidable.

Sub-Tasks & Estimates

No response