How saasquatch/squatch-js works
Based on our analysis of the complete file tree and the README content, this project is a JavaScript SDK designed to help integrate referral widgets and related API operations into web pages and applications under the “Referral SaaSquatch Javascript SDK” banner. It’s both a toolkit for rendering web components (via custom elements such as <squatch-embed> and <squatch-popup>) and a set of APIs for operations like upserting users, tracking events, and fetching referral cookie codes.
Main Components
• API Layer:
• Widget Components:
– Located in “src/widgets” and “src/widgets/declarative”, this includes implementations for the EmbedWidget, PopupWidget, and DeclarativeWidgets. These components offer the custom HTML elements used in the UI.
– They are directly referenced in the README as “squatch-embed” and “squatch-popup” and have specific properties like "widget", "container", and "locale".
• Loader and Initialization:
– Files like “src/loader.js” and “src/async.ts” are part of the client-side logic to load the necessary scripts (either asynchronously or via the provided script snippet) and initialize the SDK.
– This is where the “squatch.ready” function is set up, allowing for initializing API calls or widget rendering.
• Utilities and Shared Logic:
– The “src/utils” directory contains common helper functions (for cookies, JWT decoding, DOM readiness, IO operations, UTM utilities, etc.) that support the API and widget operations.
– “src/globals.ts” and “src/types.ts” define core types and global configurations used by the SDK.
• Demo and Integration Examples:
– The “demo” folder shows how to integrate and test the SDK in a web context. This includes sample HTML (index.html), TSX examples, CSS styling, and template examples, which drive the demonstration of both widget rendering and API usage.
• Testing Infrastructure:
– The “test” directory holds the integration and unit tests, including Cucumber-based acceptance tests (features and step definitions) and traditional tests (using Jest or TDD). These indicate how components interact and confirm system behavior.
Relationships and Data Flows
• External Application or Web Page:
– At the outer layer, the client web page includes the SDK script either via a CDN snippet or as an npm-installed module.
• SDK Loader/Initializer:
– The loader module (from “loader.js” and “async.ts”) asynchronously loads further components and initializes the SDK once the document is ready.
• API Calls:
– When the page or widget calls “squatch.ready”, the SDK initiates API calls through the API layer (via AnalyticsApi, EventsApi, or WidgetApi) to interact with the backend services.
• Widget Rendering:
– Custom HTML elements (<squatch-embed> and <squatch-popup>) are rendered. They internally depend on the Widget components in the “src/widgets” directory to display the UI.
– These widgets may also interact with the API layer to fetch data, such as referral cookie codes or user information.
• Utility and Configuration Flow:
– Utilities ensure proper processing of cookies, decoding JWT tokens, and handling DOM events to seamlessly deliver the integration.
• Testing and Demo:
– The “demo” and “test” directories simulate integration usage and verify that each component (API calls and widget functionalities) work as expected.
Architectural Patterns and Design Principles
• Modularity:
– The project is organized into clearly separated concerns (API, widgets, utilities, tests) – typical of a modular, layered architecture.
• Asynchronous Initialization:
– The use of asynchronous script loading and a “ready” callback (squatch.ready) emphasizes non-blocking operations, ensuring that integration in third-party pages does not hinder overall page performance.
• Declarative Components:
– The adoption of custom elements (web components) for widgets indicates a design that separates the presentation layer from business logic.
• Extensibility:
– With both legacy API interfaces and newer declarative approaches, the design supports backward compatibility and future evolution.
Technologies, Frameworks, and Libraries
• JavaScript/TypeScript:
– The main implementation is in JavaScript and TypeScript.
• Web Components:
– The browser’s native support for custom elements is used for defining widget behaviors.
• Build and Automation Tools:
– Configuration files such as webpack.config.js, tsconfig.json, babel.config.js, and workflows in .github/workflows indicate the use of Babel, Webpack, and CI/CD pipelines.
• Testing Tools:
– The presence of Jest, Cucumber (features and step definitions), and test helpers in the “test” directory demonstrates a comprehensive testing framework.