@appxiom/web 0.1.8

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) 2026 BasilGregory Software Labs Private Limited
+
+All rights reserved.
+
+This software is licensed, not sold. No part of this software may be copied, modified, distributed, reverse engineered, or used except as expressly permitted by BasilGregory Software Labs Private Limited.

package/README.md

@@ -0,0 +1,313 @@
+# Appxiom Web SDK (`@appxiom/web`)
+
+The official client-side JavaScript SDK for Appxiom. Use this package to initialize monitoring, track goals, report issues, and attach custom activity data from your web app.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Vite](#vite)
+- [Frameworks and SSR](#frameworks-and-ssr)
+- [Production Deployment](#production-deployment)
+- [Public API](#public-api)
+- [Error Types](#error-types)
+
+## Installation
+
+```bash
+npm install @appxiom/web
+```
+
+## Quick Start
+
+### JavaScript
+
+```javascript
+import init from '@appxiom/web';
+
+const ax = await init(
+  'YOUR_APP_KEY',
+  'YOUR_PLATFORM_KEY',
+  'YOUR_APP_VERSION',
+  'YOUR_BUILD_IDENTIFIER'
+);
+```
+
+### TypeScript
+
+`@appxiom/web` ships first-party TypeScript declarations. No separate `@types` package is needed.
+
+```typescript
+import init, { type AX } from '@appxiom/web';
+
+const ax: AX = await init(
+  'YOUR_APP_KEY',
+  'YOUR_PLATFORM_KEY',
+  'YOUR_APP_VERSION',
+  'YOUR_BUILD_IDENTIFIER',
+);
+```
+
+`init(...)` returns `Promise<AX>`. The SDK actions available on `AX` are documented below.
+
+## Vite
+
+`@appxiom/web` includes a WebAssembly binary. During local development, exclude the package from Vite dependency optimization so Vite preserves the binary's source-relative URL:
+
+```javascript
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  optimizeDeps: {
+    exclude: ['@appxiom/web'],
+  },
+});
+```
+
+After adding this setting, clear Vite's optimized-dependency cache and restart the development server:
+
+```bash
+rm -rf node_modules/.vite
+npm run dev -- --force
+```
+
+This setting affects Vite's development server only. It is safe to retain for production builds; Vite does not use dependency optimization when running `vite build`.
+
+## Frameworks and SSR
+
+The SDK is framework-neutral and runs in the browser. Initialize it from your application's browser entry point or client-side lifecycle code.
+
+- React: initialize in a client-side application entry point, or use `@appxiom/4react` for React-specific integrations.
+- Vue: initialize from `main.ts` or another browser-only application entry point.
+- Angular: initialize from a browser-only service or application lifecycle path.
+- Svelte: initialize from browser code such as `onMount`.
+- Next.js, Nuxt, SvelteKit, and other SSR frameworks: initialize only on the client. Do not import or initialize the SDK from server-rendered code, route handlers, or server components.
+
+Vite-powered frameworks, including Vite React, Vue, SvelteKit, and Nuxt applications, need the Vite configuration above during local development.
+
+For an SSR application, load and initialize the SDK only after the browser is available:
+
+```typescript
+const { default: init } = await import('@appxiom/web');
+
+const ax = await init(
+  'YOUR_APP_KEY',
+  'YOUR_PLATFORM_KEY',
+  'YOUR_APP_VERSION',
+  'YOUR_BUILD_IDENTIFIER',
+);
+```
+
+## Production Deployment
+
+Run your framework's production build as usual. For Vite applications, this is typically:
+
+```bash
+npm run build
+```
+
+Vite emits the SDK's WebAssembly binary into the production output and rewrites the loader to its generated asset URL. Deploy the complete build output, including the generated `.wasm` asset, without renaming or omitting files.
+
+Your CDN or web server must serve `.wasm` files with this response header:
+
+```http
+Content-Type: application/wasm
+```
+
+Also ensure SPA fallback rules do not return `index.html` for `.wasm` asset requests. Receiving HTML instead of the binary produces errors such as `expected magic word 00 61 73 6d`.
+
+For non-Vite applications, use the same deployment rules: the bundler must emit the package's `.wasm` asset, the asset must be deployed with the application, and the host must serve it with the WASM MIME type.
+
+## Public API
+
+The following APIs are available to client projects.
+
+### `init(appKey, platformKey, version, buildIdentifier)`
+
+Initializes the SDK and returns an `AX` instance.
+
+#### JavaScript
+
+```javascript
+const ax = await init('APP_KEY', 'PLATFORM_KEY', 'YOUR_APP_VERSION', 'YOUR_BUILD_IDENTIFIER');
+```
+
+#### TypeScript
+
+```typescript
+import type { AX } from '@appxiom/web';
+
+const ax: AX = await init('APP_KEY', 'PLATFORM_KEY', 'YOUR_APP_VERSION', 'YOUR_BUILD_IDENTIFIER');
+```
+
+Both forms also support values loaded from application configuration:
+
+```javascript
+const ax = await init(
+  config.appKey,
+  config.platformKey,
+  config.version,
+  config.buildId
+);
+```
+
+```typescript
+import type { AX } from '@appxiom/web';
+
+const ax: AX = await init(
+  config.appKey,
+  config.platformKey,
+  config.version,
+  config.buildId,
+);
+```
+
+### `AX` class
+
+The package also exports the `AX` class.
+
+#### JavaScript
+
+```javascript
+import init, { AX } from '@appxiom/web';
+```
+
+#### TypeScript
+
+```typescript
+import init, { AX } from '@appxiom/web';
+
+const ax: AX = await init('APP_KEY', 'PLATFORM_KEY', 'YOUR_APP_VERSION', 'YOUR_BUILD_IDENTIFIER');
+```
+
+### `ax.launch()`
+
+Starts SDK runtime initialization. This is called by `init(...)`, so you usually do not need to call it manually.
+
+### `ax.setCustomId(customId)`
+
+Associates your user/account identifier with telemetry.
+
+#### JavaScript
+
+```javascript
+ax.setCustomId('user-12345');
+```
+
+#### TypeScript
+
+```typescript
+ax.setCustomId('user-12345');
+```
+
+### `ax.startGoal(name)`
+
+Starts a named goal.
+
+#### JavaScript
+
+```javascript
+ax.startGoal('checkout-flow');
+```
+
+#### TypeScript
+
+```typescript
+ax.startGoal('checkout-flow');
+```
+
+### `ax.endGoal(name, properties = {}, value = null)`
+
+Ends a named goal.
+
+#### JavaScript
+
+```javascript
+ax.endGoal('checkout-flow', { cartValue: 120.0 }, 120.0);
+```
+
+#### TypeScript
+
+```typescript
+ax.endGoal('checkout-flow', { cartValue: 120.0 }, 120.0);
+```
+
+### `ax.logActivity(name, properties = {})`
+
+Adds a custom activity entry.
+
+#### JavaScript
+
+```javascript
+ax.logActivity('Checkout Step Completed', {
+  step: 'payment',
+  orderId: 'ORD-10023'
+});
+```
+
+#### TypeScript
+
+```typescript
+ax.logActivity('Checkout Step Completed', {
+  step: 'payment',
+  orderId: 'ORD-10023',
+});
+```
+
+### `ax.reportCustomIssue(title, description, severity, data = {}, stacktrace = null)`
+
+Reports a custom issue from your application. Severity values are `0` (Minor), `1` (Major), and `2` (Fatal).
+
+#### JavaScript
+
+```javascript
+ax.reportCustomIssue(
+  'Checkout Validation Failed',
+  'Payment token was missing.',
+  1,
+  { module: 'checkout' },
+  new Error('Missing payment token').stack
+);
+```
+
+#### TypeScript
+
+```typescript
+import type { IssueSeverity } from '@appxiom/web';
+
+const severity: IssueSeverity = 1;
+ax.reportCustomIssue(
+  'Checkout Validation Failed',
+  'Payment token was missing.',
+  severity,
+  { module: 'checkout' },
+  new Error('Missing payment token').stack,
+);
+```
+
+### Type exports
+
+The package exports the following TypeScript declarations:
+
+- `AX`: the initialized SDK instance returned by `init(...)`.
+- `AppxiomProperties`: a string-keyed object for telemetry metadata.
+- `IssueSeverity`: `0 | 1 | 2`, corresponding to Minor, Major, and Fatal.
+
+## Error Types
+
+The SDK categorizes detected problems into a set of structured error types so that telemetry, debugging, and reporting are easier to analyze. The values below correspond to the internal error-type mapping used by the SDK.
+
+- `HTTPStatusError`: Indicates that an HTTP request completed with a non-success status code such as `4xx` or `5xx`. This is commonly used for failed API responses or backend-side errors.
+- `HTTPDuplicateRequestError`: Represents a situation where the same request was issued more than once, often causing duplicate work or duplicate network activity.
+- `HTTPDelayedResponseError`: Signals that an HTTP request took longer than expected to respond. This usually points to latency, slow network conditions, or backend delays.
+- `HTTPExceptionError`: Captures unexpected exceptions thrown during the HTTP request lifecycle, such as runtime failures, parsing issues, or transport-level exceptions.
+- `MemoryLeak`: Indicates a suspected memory leak where memory usage grows over time without being released.
+- `MemoryAnomaly`: Represents abnormal memory behavior that does not necessarily meet the threshold of a full leak, but still suggests unusual retention or allocation patterns.
+- `MemoryRisk`: Marks a potential memory-related issue that should be monitored closely, even if it has not yet become a confirmed leak or spike.
+- `MemorySpike`: Represents a sudden rise in memory consumption over a short time window, often indicating pressure from a temporary workload or an underlying issue.
+- `AutoCapturedError`: Refers to errors that the SDK captures automatically from the runtime environment without requiring manual instrumentation.
+- `ResourceLoadError`: Indicates that a critical resource such as an image, script, stylesheet, or other asset failed to load properly.
+- `CustomException`: Represents an exception that your application reports manually through the SDK for domain-specific or application-level errors.
+- `CustomIssue`: Denotes a manually reported issue that is not necessarily an exception, but still needs to be tracked as a meaningful product or engineering problem.
+- `FrameDrop`: Signals a frame-rate drop or rendering anomaly that may indicate performance degradation, jank, or excessive main-thread work.
+

package/ax_web_core/ax_web_core.d.ts

@@ -0,0 +1,192 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * LeakAnalyzer Struct
+ */
+export class LeakAnalyzer {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Evaluate current records for leaks
+     */
+    evaluate_leaks(): Promise<LeakRecord[]>;
+    /**
+     * Create a new LeakAnalyzer
+     */
+    constructor();
+    /**
+     * Notify a GC epoch occurrence
+     */
+    notify_gc_epoch(): Promise<void>;
+    /**
+     * Report a detected leak
+     * Convert the LeakRecord to MemoryLeak.
+     */
+    static report_leak(leak_record: LeakRecord): Promise<void>;
+    /**
+     * Track a detached instance
+     */
+    track_instance(instance_id: number): Promise<void>;
+}
+
+/**
+ * Leak Record Struct
+ */
+export class LeakRecord {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    age: number;
+    first_seen: bigint;
+    gc_survivals: number;
+    instance_id: number;
+    last_gc_epoch: number;
+}
+
+/**
+ * End a goal
+ */
+export function end_goal(name: string): Promise<void>;
+
+/**
+ * JS interface for get_device_state function. This allows JavaScript code to call this Rust function and get the device state information as a JavaScript object.
+ */
+export function get_device_state_js(): Promise<any>;
+
+/**
+ * API handler when API call is initiated`
+ */
+export function handle_api_after_request(url: string, request: any, request_timestamp: bigint): Promise<void>;
+
+/**
+ * API handler when API call is done`
+ */
+export function handle_api_after_response(url: string, request: any, request_timestamp: bigint, response: any, response_timestamp: bigint | null | undefined, error: any): Promise<void>;
+
+/**
+ * API handler when API call fails due to network error or other reasons.
+ */
+export function handle_api_on_error(url: string, request: any, request_timestamp: bigint, error: any): Promise<void>;
+
+/**
+ * Init the SDK with the given app key, platform key, version, and build identifier.
+ * sdk_type is configured at build time via AX_SDK_TYPE.
+ * if app_key is not provided, it will be set to 01KJ7FF0CS16ZPXF2T4TCN9EKB
+ * if platform_key is not provided, it will be set to 1d7a4689674373fac78b4d5fe8555d8fdcf2e2bc28fc4d196dcf7c69931c89b7
+ *
+ */
+export function init(app_key: string, platform_key: string, version: string, build_identifier?: string | null): Promise<void>;
+
+/**
+ * Add activity
+ */
+export function log_activity(name: string, details: any): Promise<void>;
+
+/**
+ * Log event
+ */
+export function log_event(type_id: number, info: any): Promise<void>;
+
+/**
+ * Add Event Activity
+ */
+export function log_event_activity(name: string, details: any): Promise<void>;
+
+/**
+ * Log resource load error
+ */
+export function log_resource_load_error(url: string, data: any): Promise<void>;
+
+/**
+ * Report CustomIssue
+ */
+export function report_custom_issue(title: string, description: string, severity: number, data: any, stacktrace?: string | null): Promise<void>;
+
+/**
+ * Report Error
+ */
+export function report_error(error: any): Promise<void>;
+
+/**
+ * Set custom ID for the current device. This can be used to link the device with user information in the application.
+ */
+export function set_custom_id(custom_id: string): Promise<void>;
+
+/**
+ * Start a goal
+ */
+export function start_goal(name: string): Promise<void>;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_get_leakrecord_age: (a: number) => number;
+    readonly __wbg_get_leakrecord_first_seen: (a: number) => bigint;
+    readonly __wbg_get_leakrecord_gc_survivals: (a: number) => number;
+    readonly __wbg_get_leakrecord_instance_id: (a: number) => number;
+    readonly __wbg_get_leakrecord_last_gc_epoch: (a: number) => number;
+    readonly __wbg_leakanalyzer_free: (a: number, b: number) => void;
+    readonly __wbg_leakrecord_free: (a: number, b: number) => void;
+    readonly __wbg_set_leakrecord_age: (a: number, b: number) => void;
+    readonly __wbg_set_leakrecord_first_seen: (a: number, b: bigint) => void;
+    readonly __wbg_set_leakrecord_gc_survivals: (a: number, b: number) => void;
+    readonly __wbg_set_leakrecord_instance_id: (a: number, b: number) => void;
+    readonly __wbg_set_leakrecord_last_gc_epoch: (a: number, b: number) => void;
+    readonly end_goal: (a: number, b: number) => number;
+    readonly get_device_state_js: () => number;
+    readonly handle_api_after_request: (a: number, b: number, c: number, d: bigint) => number;
+    readonly handle_api_after_response: (a: number, b: number, c: number, d: bigint, e: number, f: number, g: bigint, h: number) => number;
+    readonly handle_api_on_error: (a: number, b: number, c: number, d: bigint, e: number) => number;
+    readonly init: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => number;
+    readonly leakanalyzer_evaluate_leaks: (a: number) => number;
+    readonly leakanalyzer_new: () => number;
+    readonly leakanalyzer_notify_gc_epoch: (a: number) => number;
+    readonly leakanalyzer_report_leak: (a: number) => number;
+    readonly leakanalyzer_track_instance: (a: number, b: number) => number;
+    readonly log_activity: (a: number, b: number, c: number) => number;
+    readonly log_event: (a: number, b: number) => number;
+    readonly log_event_activity: (a: number, b: number, c: number) => number;
+    readonly log_resource_load_error: (a: number, b: number, c: number) => number;
+    readonly report_custom_issue: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => number;
+    readonly report_error: (a: number) => number;
+    readonly set_custom_id: (a: number, b: number) => number;
+    readonly start_goal: (a: number, b: number) => number;
+    readonly __wasm_bindgen_func_elem_458: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_1045: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_1102: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_455: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_461: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_461_4: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_450: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_465: (a: number, b: number) => void;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_export3: (a: number) => void;
+    readonly __wbindgen_export4: (a: number, b: number) => void;
+    readonly __wbindgen_export5: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;