Design Public Interface & Improve Package Architecture

[ygrishajev]

The akashjs package currently suffers from:

• Poor organization
• Low code quality
• Insufficient documentation

We want to reduce frustration for current and future users by improving the experience of using akashjs.

Objective

Create a new public interface that is clearly structured, user-friendly, and future-proof. This interface will help us hide (and eventually refactor) the lower-quality internal code, while still exposing necessary functionality to developers.

Key Requirements

1. Design a Public Interface

   • Define which functions, classes, or modules should be part of the “official” public API.
   • Hide or refactor low-level or experimental code to prevent direct usage.

2. Reflect a Future Modular Structure

   • Organize the public interface in a way that aligns with an upcoming modular refactor
     (e.g., separate modules for deployments, certificates, fees, etc.).

3. Layered Functions

   • Lower-level utility functions (e.g., creating certificates, granting fees).
   • Higher-level flows combining those utility functions
     (e.g., end-to-end deployment creation).

4. Browser and Node Compatibility

   • Ensure the design acknowledges both browser-based and Node.js environments
     (e.g., where crypto libraries differ, bundling concerns, etc.).

5. Documentation

   • The interface must be easily documented (a separate issue will track the documentation
     tool and process).
   • Include clear code examples and usage guides.

6. Implementation Not Required (Yet)

   • This issue focuses on planning and design only.
   • Actual coding tasks and refactors will follow once the interface is settled and agreed upon.

Deliverables

• Proposed Public Interface: An outline or diagram showing modules, functions, classes, and how they interrelate.
• Compatibility Plan: Notes on handling browser vs. Node usage.
• Documentation Outline: High-level plan of what each part of the interface does and how it will be documented
  (detailed docs will be covered in a separate issue).

Acceptance Criteria

• A clearly defined set of functions/modules/classes that are public.
• A roadmap showing how these endpoints will map to a future modular architecture.
• Confirmation or plan showing how Node and browser differences will be handled (if any).
• Outline or short spec for how these endpoints will be documented.