# Platform: JavaScript ## / - [Readme](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/README.md): Provides high-level documentation for the Notifly JavaScript SDK, including npm/yarn installation commands, package versioning, changelog update requirements, and the GitHub Release workflow steps used to publish new SDK versions. - [Changelog](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/CHANGELOG.md): Documents the SDK’s versioned change history, detailing added/changed/fixed behavior (e.g. - [Package](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/package.json): Defines the Notifly JS SDK package metadata, build/test/lint/service-worker deployment scripts, output entry points (`lib/cjs`, `lib/esm`, UMD/global bundles), TypeScript type declarations, and runtime/dev dependency graph for publishing the browser SDK to npm and S3. - [Tsconfig](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/tsconfig.json): Configures TypeScript compilation for the SDK and tests (CommonJS, ES5 target, strict type-checking, DOM lib, Jest/Node typings), excluding `NotiflyServiceWorker.ts` from builds and emitting no JS while generating declaration maps and source maps. - [Tsconfig.esm](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/tsconfig.esm.json): Configures the TypeScript ESM build, extending `tsconfig.json` to compile `src/**/*. - [Tsconfig.es5](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/tsconfig.es5.json): Configures the ES5/CommonJS build, extending the base TypeScript config to compile `src/**/*.ts` into `lib/cjs` with `module: commonjs` and emitting output for the CommonJS distribution of the SDK. - [Tsconfig.sw](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/tsconfig.sw.json): TypeScript configuration for building the service worker entrypoint (`src/NotiflyServiceWorker.ts`) into `dist`, extending the main tsconfig while targeting `WebWorker` ES2015 libs and disabling declaration/source map emission. - [Rollup.config](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/rollup.config.js): Configures Rollup to bundle `src/index.ts` into a UMD `notifly` build using node-resolve, Babel (excluding `NotiflyServiceWorker. - [Rollup.global.config](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/rollup.global.config.js): Builds the browser-global `notifly` IIFE bundle from `src/index.ts` using Rollup with Node resolve, Babel (excluding `NotiflyServiceWorker. - [Babel.config](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/babel.config.js): Configures Babel to compile the SDK’s TypeScript/ES code to IE11-compatible JavaScript, switching to CommonJS modules (via `@babel/preset-env` and `@babel/transform-modules-commonjs`) when running tests or when `BABEL_ENV=commonjs`. - [Jest.config](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/jest.config.js): Jest configuration for notifly-js-sdk, defining a jsdom test environment, display name metadata, disabling coverage collection, and excluding node_modules, build outputs, and example directories from test discovery. - [.prettierrc](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/.prettierrc.yml): Configures Prettier formatting for the SDK, defining global style rules (quotes, semicolons, trailing commas, print width) and file-type-specific overrides for JSON/YAML indentation and TypeScript parsing. - [.eslintrc](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/.eslintrc.cjs): Configures ESLint for the SDK’s TypeScript/React codebase, defining environments, parser, plugins, shared configs, ignore patterns, and custom lint rules (e.g. - [](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/.npmignore): Configures which project files and directories (examples, tests, build configs, tooling, editor/CI metadata, archives, lockfiles, local service worker, etc.) are excluded from the published `notifly-js-sdk` npm package. - [Notifly Service Worker](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/notifly-service-worker.js): Service worker bootstrap that loads and executes the compiled Notifly service worker implementation by importing `/dist/NotiflyServiceWorker.js`, delegating all notification/push logic and event handling to the bundled SDK module. ## examples/react/public - [Notifly Service Worker](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/examples/react/public/notifly-service-worker.js): Loads the remote `NotiflyServiceWorker.js` script into the service worker context via `importScripts`, delegating all push notification handling, background event processing, and Notifly SDK integration logic to the hosted Notifly JS SDK. ## examples/react/src - [Index](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/examples/react/src/index.tsx): Bootstraps the React example app by creating the root with `ReactDOM.createRoot`, rendering `` within a `BrowserRouter` for client-side routing, loading global styles, and invoking `reportWebVitals` to optionally capture performance metrics. - [App](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/examples/react/src/App.tsx): React example app wiring Notifly JS SDK initialization, user identity/property management, event tracking, and IndexedDB-backed storage inspection into a routed UI (Home/Playground/MyPage), exposing flows via components like UserIdSetter, UserPropertySetter, TrackEventSection, and IndexedDBDumper. - [Mypage](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/examples/react/src/MyPage.tsx): React route component that renders a simple “My Page” view with header text and a `react-router-dom` `Link` back to the home route, serving as an example page within the React SDK demo app. - [App.test](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/examples/react/src/App.test.tsx): React Testing Library unit test that mounts the `App` component, queries for the “learn react” text via `screen.getByText`, and asserts its presence in the DOM as a basic integration check of the example React app. - [Setuptests](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/examples/react/src/setupTests.ts): Initializes the Jest test environment for the React examples by importing `@testing-library/jest-dom`, enabling extended DOM-specific matchers (e.g. - [Reportwebvitals](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/examples/react/src/reportWebVitals.ts): Reports Core Web Vitals metrics (CLS, FID, FCP, LCP, TTFB) to a provided `ReportHandler` by lazily importing `web-vitals`, serving as the performance monitoring entry point for the React example app. - [Playground](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/examples/react/src/Playground.tsx): Simple React functional component used in the examples app that renders a "Playground" subpage UI and provides navigation back to the home route via `react-router-dom`’s `Link` component. - [React App Env.d](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/examples/react/src/react-app-env.d.ts): Type declaration shim that augments the React example app’s TypeScript environment by pulling in `react-scripts` type definitions, ensuring proper tooling and typings for the Create React App–based example. ## examples/vanilla/js - [App](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/examples/vanilla/js/app.js): Example vanilla JS app wiring DOM inputs to `window.notifly. ## src - [Constants](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Constants.ts): Defines shared SDK constants: the `HashNamespace` enum for deterministic ID hashing namespaces, `BuiltInUserPropertyKey` enum for standard user profile fields, and `LAST_SESSION_TIME_LOGGING_INTERVAL` controlling session timestamp update frequency. - [Client](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Client.ts): Defines the main public Notifly browser SDK API, handling initialization, user identity/properties (including email/phone/timezone), event tracking, push-permission requests, SDK metadata (type/version/source), and delegating operations via CommandManager, NotiflyAPI, SessionManager, and SdkStateManager with state/validation guards. - [Index](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/index.ts): Aggregates and re-exports the core Client APIs (initialize, trackEvent, user identity/properties setters, permission requests, SDK metadata setters/getters) as the default `notifly` object, serving as the primary public entry point for the JS SDK. - [Version](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Version.ts): Defines the public `SDK_VERSION` constant exposing the current Notifly JS SDK semantic version (`2.17. - [Notiflyserviceworker](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/NotiflyServiceWorker.ts): Implements the Notifly service worker that handles install/activate lifecycle, receives and displays web push notifications, manages click navigation, logs internal push events to the Notifly API using IndexedDB-stored auth/config, and deterministically generates user IDs via a UUIDv5-like helper. ## src/Core - [Push](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Push.ts): Implements `NotiflyWebPushManager`, which initializes service workers for web push via VAPID, manages push subscriptions and logging (`EventLogger` `NotiflyStorage`), and renders a localized, customizable in-page permission prompt (auto/manual) that triggers `Notification.requestPermission()`. - [Sdkstate](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/SdkState.ts): Defines global SDK lifecycle state and metadata (type, version, source), exposes `SdkStateManager` as the central static controller for state transitions, observer registration/callbacks, halted detection, and configuration of user-supplied log event allowance. - [Session](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Session.ts): Implements `SessionManager`, handling session lifecycle and expiration based on persisted timestamps and remote `SdkConfiguration`, periodically saving session time on window focus, starting/refreshing sessions via `EventLogger` and `UserStateManager`, initializing `WebMessageManager` and `NotiflyWebPushManager`, and registering window lifecycle listeners. - [Event](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Event.ts): Implements the `EventLogger` for emitting internal and custom events to `https://e.notifly. ## src/Core/API - [Index](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/API/index.ts): Defines the `NotiflyAPI` static class that initializes and manages Cognito ID token–authenticated HTTP calls (with automatic token refresh and retry on 401), using `NotiflyStorage`, `SdkStateManager`, and `saveAndGetCognitoIdToken` as core dependencies and public entrypoints. - [Auth](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/API/Auth.ts): Implements Cognito authentication helpers by POSTing user credentials to `https://api.notifly. - [Configuration](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/API/Configuration.ts): Fetches and normalizes project-scoped SDK configuration from the Notifly backend, using `NotiflyStorage` for the project ID and `SdkStateManager` for versioning, and exposes `getSdkConfiguration()` to resolve validated web push and session settings with sane defaults. ## src/Core/Command - [Commands](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Command/Commands.ts): Defines the command layer for the SDK, implementing typed `CommandBase` classes (set/remove user ID, set user properties, track events, request permission, get user ID/properties) that delegate to `UserIdentityManager`, `EventLogger`, and `NotiflyWebPushManager` via the `CommandType` enum. - [Index](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Command/index.ts): Implements the singleton `CommandManager` that queues and executes `CommandBase` instances based on `SdkState`, manages active/pending commands via a priority queue, handles SET_USER_ID-driven state transitions, aborts on termination, and propagates recoverable/unrecoverable errors. - [Params](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Command/Params.ts): Defines strongly-typed parameter interfaces (`SetUserIdCommandParams`, `RemoveUserIdCommandParams`, `SetUserPropertiesCommandParams`, `TrackEventCommandParams`) for core identity and event commands, including user options (`SetUserIdOptions`) and generic payloads used throughout the command execution pipeline. ## src/Core/Interfaces - [Requestpermissionpromptdesignparams](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Interfaces/RequestPermissionPromptDesignParams.ts): Defines the `Language` locale enum, localized `TextContent` map, and the `RequestPermissionPromptDesignParams`/button/text design interfaces that configure colors and multilingual text for the SDK’s request-permission UI prompt. - [Comparable](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Interfaces/Comparable.ts): Defines the `IComparable` interface, requiring implementers to expose a `compareTo(other: T): number` method for consistent ordering/comparison semantics across SDK types. - [Campaign](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Interfaces/Campaign.ts): Defines the TypeScript types and enums modeling campaign configuration, including segment conditions, triggering conditions and event filters, re-eligibility rules, and message payload (via `InWebMessageTemplateProps`), used as the core schema for campaign evaluation and delivery logic. - [User](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Interfaces/User.ts): Defines strongly-typed interfaces for user-related analytics state—device properties, custom user attributes, campaign visibility metadata, and intermediate event counts—and composes them into the `UserData` type used throughout the SDK for user identity and tracking payloads. - [Options](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Interfaces/Options.ts): Defines the core option types `NotiflyInitializeOptions` (project credentials and optional `allowUserSuppliedLogEvent` flag) and `SetUserIdOptions` (conditional user ID updates) used by Notifly initialization and user-identification APIs. ## src/Core/Storage - [Idb](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Storage/IDB.ts): Implements `NotiflyIndexedDBStore`, an `SdkStateObserver`-backed IndexedDB wrapper that lazily opens a DB/object store, exposes async CRUD APIs (`ready`, `getItem`, `setItem`, `setItems`, `removeItem`, `removeItems`), tracks/aborts active `IDBTransaction`s, and closes safely on SDK termination. - [Index](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Storage/index.ts): Provides the `NotiflyStorage` IndexedDB-backed storage facade and `NotiflyStorageKeys` enum, handling initialization, CRUD operations, notifly user ID generation, and transaction timeouts via `NotiflyIndexedDBStore` and `generateNotiflyUserId`. ## src/Core/User - [State](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/User/State.ts): Manages global in-memory and persisted user state (eventIntermediateCounts, in-web-message campaigns, userData), including storage/REST synchronization with merge/overwrite policies, external_user_id reconciliation, campaign re-eligibility/hidden-until tracking, and user property/event count updates via `UserStateManager` static APIs. - [Utils](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/User/Utils.ts): Utility helpers for user state management, including KST date formatting, validation of user/campaign/event-intermediate-count structures, safe random bucket normalization, event count merging via lodash, shallow object merging, and construction of default `UserData` using `SdkStateManager` and `getPlatform()`. - [Index](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/User/index.ts): Manages user identity and properties by syncing `external_user_id` with `NotiflyStorage`, logging internal events, refreshing `UserStateManager` with appropriate `SyncStatePolicy`, and exposing `setUserId`, `getUserId`, `setUserProperties`, `getUserProperties`, and `removeUserId`. ## src/Core/Utils - [Timezone](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Utils/Timezone.ts): Defines the `supportedTimezoneIds` IANA timezone whitelist and provides `getCurrentTimezoneId()` (wrapper around `Intl.DateTimeFormat(). - [Priorityqueue](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Utils/PriorityQueue.ts): Implements a binary min-heap–backed `PriorityQueue>` with `enqueue`, `dequeue`, `peek`, `clear`, and size/emptiness checks, ordering elements via `IComparable.compareTo` and maintaining heap invariants through private `bubbleUp`/`sinkDown` operations. - [Index](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/Utils/index.ts): Provides core utility helpers including Notifly storage initialization (`initializeNotiflyStorage`), project/user/device ID validation and generation (`isValidProjectId`, `generateNotiflyUserId`), platform detection, random string generation, notification permission mapping, global scope/timestamp retrieval, key filtering, and re-exports timezone utilities. ## src/Core/WebMessages - [Manager](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/WebMessages/Manager.ts): Manages in-web-message campaign triggering by syncing user state, evaluating triggering conditions, event filters, and segment rules (including counts and user/device properties), deduplicating by delay/updated_at, and enqueueing matching campaigns into `WebMessageScheduler`; key APIs: `initialize`, `maybeTriggerWebMessagesAndUpdateEventCounts`, `getCampaignsToSchedule`, `isEntityOfSegment`, `isEventApplicableForCampaign`. - [Scheduler](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/WebMessages/Scheduler.ts): Implements `WebMessageScheduler`, which registers SDK state observers and coordinates delayed in-web-message campaign display via `notifly-web-message-renderer`, handling iframe message events, navigation, user property updates, internal/external event logging, and (de)scheduling by campaign ID. - [Utils](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/src/Core/WebMessages/Utils.ts): Implements `ValueComparator` utilities for type-safe campaign value comparisons (equality, ordering, array membership, text/regex operations with logging), plus helpers for regex matching, KST calendar date strings, null/undefined checks, and re-eligibility unit-to-seconds mapping. ## test/src - [Utils.spec](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/test/src/utils.spec.ts): Jest unit tests for `Core/Utils` verifying `getPlatform`’s user-agent based platform detection and `removeKeys`’s non-mutating key-stripping behavior, with mocked `NotiflyStorage` and `uuid` dependencies to isolate and validate these utility functions. - [Auth.spec](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/test/src/auth.spec.ts): Jest test suite validating `getCognitoIdToken` behavior, mocking `NotiflyStorage`, `SdkStateManager`, and `global.fetch` to assert correct POST payload/headers to the Notifly authorize endpoint and proper handling of successful responses and fetch errors. - [User.spec](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/test/src/user.spec.ts): Jest test suite validating `UserIdentityManager.setUserProperties` behavior, including storage interactions with `NotiflyStorage`, event emission via `EventLogger. - [State Utils.spec](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/test/src/state_utils.spec.ts): Jest test suite validating `mergeEventCounts` (from `src/Core/User/Utils`) correctly aggregates and merges event count records by `name`, `dt`, and `event_params` across multiple arrays, ensuring expected deduplication and count summation behavior. - [State.spec](https://raw.githubusercontent.com/team-michael/notifly-js-sdk/main/test/src/state.spec.ts): Jest test suite validating `UserStateManager` event count updates and `WebMessageManager` campaign selection/segmentation logic, including triggering conditions, event filters, regex operators, user-property and event-count segment rules, with storage mocked via `NotiflyStorage`.