@allstak/react 0.2.1 → 0.3.0

package/README.md

@@ -114,6 +114,49 @@ import { AllStak } from '@allstak/react';
 AllStak.setUser({ id: user.id, email: user.email });
 ```
 
+## HTTP tracking
+
+Setting `enableHttpTracking: true` (off by default) auto-wraps `fetch`,
+`XMLHttpRequest`, and `axios` (when installed) so every outbound HTTP
+call is recorded as an `http_request` event.
+
+**Privacy defaults are aggressive:**
+
+- request/response bodies are **not** captured
+- headers are **not** captured
+- `Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key`, `X-Auth-Token`,
+  `Proxy-Authorization` are **always** redacted
+- query params named `token`, `password`, `api_key`, `apikey`,
+  `authorization`, `auth`, `secret`, `access_token`, `refresh_token`,
+  `session`, `sessionid`, `jwt` are **always** redacted in the URL
+
+To enable richer capture (only on routes you control):
+
+```ts
+AllStak.init({
+  apiKey: '...',
+  enableHttpTracking: true,
+  httpTracking: {
+    captureRequestBody: true,
+    captureResponseBody: true,
+    captureHeaders: true,             // auth headers still hard-redacted
+    redactHeaders: ['x-tenant'],
+    redactQueryParams: ['custom_id'],
+    ignoredUrls: [/health/i, '/metrics'],
+    allowedUrls: [],
+    maxBodyBytes: 4096,
+  },
+});
+
+// axios with custom adapter (rare):
+import axios from 'axios';
+const api = AllStak.instrumentAxios(axios.create({ baseURL: 'https://api.example.com' }));
+```
+
+When an exception fires after a failed request, the most recent failed
+HTTP requests (last 10) are automatically attached to the error
+metadata under `http.recentFailed` for easy triage.
+
 ## Production Endpoint
 
 Production endpoint: `https://api.allstak.sa`. Override via `host` for self-hosted installs:

package/dist/index.d.mts

@@ -1,5 +1,113 @@
 import * as React from 'react';
 
+/**
+ * Minimal HTTP transport for React Native. Uses the global `fetch` (always
+ * present in RN >= 0.60) with a 3s timeout. Failed sends fall into a small
+ * in-memory ring buffer that we retry on the next successful flush.
+ *
+ * No window, no AbortController fallback shims — RN exposes both natively.
+ */
+declare class HttpTransport {
+    private baseUrl;
+    private apiKey;
+    private buffer;
+    private flushing;
+    constructor(baseUrl: string, apiKey: string);
+    send(path: string, payload: unknown): Promise<void>;
+    private doFetch;
+    private flushBuffer;
+    getBufferSize(): number;
+    /**
+     * Wait for the in-flight retry-buffer to drain. Resolves `true` if the
+     * buffer empties within `timeoutMs` (default 2000ms), `false` otherwise.
+     * Useful at process exit / before navigation away.
+     */
+    flush(timeoutMs?: number): Promise<boolean>;
+}
+
+/**
+ * HTTP request batching + transport for the React Native SDK.
+ *
+ * Mirrors the wire shape used by `@allstak/js`'s HttpRequestModule so the
+ * existing backend ingest endpoint (`/ingest/v1/http-requests`) accepts
+ * events from this SDK without a schema change. Adds optional rich fields
+ * (headers, bodies, error string) — these ride alongside the existing
+ * required fields and are tolerated as additive metadata server-side.
+ *
+ * Batching:
+ *   - flushes on a 5s timer OR when 20 events queue up
+ *   - flushes immediately on `destroy()`
+ *   - `getRecentFailed(n)` returns the last n failed requests (statusCode
+ *     >= 400 OR error set), used by error-linking on the next captureException
+ */
+
+/** What instrumentation hands to the module per request. */
+interface HttpRequestEvent {
+    type: 'http_request';
+    method: string;
+    url: string;
+    statusCode?: number;
+    durationMs: number;
+    requestSize?: number;
+    responseSize?: number;
+    requestBody?: string;
+    responseBody?: string;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    error?: string;
+    traceId?: string;
+}
+interface HttpRequestIngestItem {
+    type: 'http_request';
+    traceId: string;
+    direction: 'outbound';
+    method: string;
+    host: string;
+    path: string;
+    url: string;
+    statusCode: number;
+    durationMs: number;
+    requestSize?: number;
+    responseSize?: number;
+    requestBody?: string;
+    responseBody?: string;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    error?: string;
+    environment?: string;
+    release?: string;
+    dist?: string;
+    platform?: string;
+    'sdk.name'?: string;
+    'sdk.version'?: string;
+    timestamp: string;
+}
+interface ModuleDefaults {
+    environment?: string;
+    release?: string;
+    dist?: string;
+    platform?: string;
+    sdkName?: string;
+    sdkVersion?: string;
+}
+declare class HttpRequestModule {
+    private transport;
+    private queue;
+    private recentFailed;
+    private flushTimer;
+    private destroyed;
+    private defaults;
+    constructor(transport: HttpTransport);
+    setDefaults(defaults: ModuleDefaults): void;
+    capture(ev: HttpRequestEvent): void;
+    /** Snapshot of the last failed requests for error-linking. Newest last. */
+    getRecentFailed(): ReadonlyArray<HttpRequestIngestItem>;
+    flush(): void;
+    destroy(): void;
+    /** @internal — for tests. */
+    getQueueSize(): number;
+}
+
 /**
  * Per-call scoped context isolation.
  *
@@ -41,31 +149,6 @@ declare class Scope {
     clear(): this;
 }
 
-/**
- * Minimal HTTP transport for React Native. Uses the global `fetch` (always
- * present in RN >= 0.60) with a 3s timeout. Failed sends fall into a small
- * in-memory ring buffer that we retry on the next successful flush.
- *
- * No window, no AbortController fallback shims — RN exposes both natively.
- */
-declare class HttpTransport {
-    private baseUrl;
-    private apiKey;
-    private buffer;
-    private flushing;
-    constructor(baseUrl: string, apiKey: string);
-    send(path: string, payload: unknown): Promise<void>;
-    private doFetch;
-    private flushBuffer;
-    getBufferSize(): number;
-    /**
-     * Wait for the in-flight retry-buffer to drain. Resolves `true` if the
-     * buffer empties within `timeoutMs` (default 2000ms), `false` otherwise.
-     * Useful at process exit / before navigation away.
-     */
-    flush(timeoutMs?: number): Promise<boolean>;
-}
-
 /**
  * Lightweight distributed tracing primitives.
  *
@@ -192,19 +275,37 @@ declare class ReplayRecorder {
     private safeAttribute;
 }
 
-/**
- * Standalone AllStak client for the browser/React environment. No external
- * AllStak SDK dependencies — only the browser's native `fetch`, AbortController,
- * Date, JSON, and (optionally) `window` for unhandled error auto-capture.
- *
- * Surface mirrors the public AllStak API used by web apps:
- *   init / captureException / captureMessage / addBreadcrumb / clearBreadcrumbs
- *   setUser / setTag / setIdentity / getSessionId
- */
+interface HttpTrackingOptions {
+    /** Capture request body. Default false. Truncated to maxBodyBytes. */
+    captureRequestBody?: boolean;
+    /** Capture response body. Default false. Truncated to maxBodyBytes. */
+    captureResponseBody?: boolean;
+    /**
+     * Capture request + response headers. Default false. Hard-redacted
+     * names are always stripped regardless of this flag.
+     */
+    captureHeaders?: boolean;
+    /** Additional header names to redact (case-insensitive). */
+    redactHeaders?: string[];
+    /** Additional query-param names to redact (case-insensitive). */
+    redactQueryParams?: string[];
+    /**
+     * Skip URLs matching any of these patterns. String = case-insensitive
+     * substring match; RegExp = `.test()` against the full URL.
+     */
+    ignoredUrls?: (string | RegExp)[];
+    /**
+     * If non-empty, only capture URLs matching at least one of these
+     * patterns. Takes precedence over ignoredUrls.
+     */
+    allowedUrls?: (string | RegExp)[];
+    /** Max bytes per captured body. Default 4096. */
+    maxBodyBytes?: number;
+}
 
 declare const INGEST_HOST = "https://api.allstak.sa";
 declare const SDK_NAME = "allstak-react";
-declare const SDK_VERSION = "0.2.1";
+declare const SDK_VERSION = "0.3.0";
 
 interface AllStakConfig {
     /** Project API key (`ask_live_…`). Required. */
@@ -252,6 +353,17 @@ interface AllStakConfig {
      * the full privacy contract.
      */
     replay?: ReplayOptions;
+    /**
+     * Auto-instrument outbound HTTP — wraps `fetch`, `XMLHttpRequest`, and
+     * (when present) `axios`. Default: false.
+     */
+    enableHttpTracking?: boolean;
+    /**
+     * Privacy + capture controls for HTTP instrumentation. Bodies and
+     * headers are OFF by default; auth headers and sensitive query params
+     * are ALWAYS redacted.
+     */
+    httpTracking?: HttpTrackingOptions;
     /**
      * Probability in [0, 1] that any given error is sent. Default: 1 (no sampling).
      * Applied per event before {@link beforeSend}.
@@ -324,9 +436,15 @@ declare class AllStakClient {
     private scopeStack;
     private tracing;
     private replay;
+    private httpRequests;
+    private _instrumentAxios;
     private onErrorHandler;
     private onRejectionHandler;
     constructor(config: AllStakConfig);
+    /** Manually instrument an axios instance. No-op when HTTP tracking is off. */
+    instrumentAxios<T = any>(axios: T): T;
+    /** Snapshot of recent failed HTTP requests for error-linking. */
+    getRecentFailedHttp(): readonly HttpRequestIngestItem[];
     captureException(error: Error, context?: Record<string, unknown>): void;
     /** Start a new span — auto-parented to any currently-active span. */
     startSpan(operation: string, options?: {
@@ -450,6 +568,8 @@ declare const AllStak: {
     setTraceId(traceId: string): void;
     getCurrentSpanId(): string | null;
     resetTrace(): void;
+    /** Manually instrument an axios instance. No-op when HTTP tracking is off. */
+    instrumentAxios<T = any>(axios: T): T;
     getSessionId(): string;
     getConfig(): AllStakConfig | null;
     destroy(): void;
@@ -549,4 +669,4 @@ declare function useAllStak(): {
  */
 declare function withAllStakProfiler<P extends object>(Component: React.ComponentType<P>, name?: string): React.FC<P>;
 
-export { AllStak, AllStakClient, type AllStakConfig, AllStakErrorBoundary, type AllStakErrorBoundaryProps, type Breadcrumb, INGEST_HOST, type ReplayOptions, ReplayRecorder, SDK_NAME, SDK_VERSION, Scope, instrumentBrowserNavigation, instrumentConsole, instrumentFetch, instrumentNextRouter, instrumentReactRouter, useAllStak, withAllStakProfiler };
+export { AllStak, AllStakClient, type AllStakConfig, AllStakErrorBoundary, type AllStakErrorBoundaryProps, type Breadcrumb, type HttpRequestEvent, HttpRequestModule, type HttpTrackingOptions, INGEST_HOST, type ReplayOptions, ReplayRecorder, SDK_NAME, SDK_VERSION, Scope, instrumentBrowserNavigation, instrumentConsole, instrumentFetch, instrumentNextRouter, instrumentReactRouter, useAllStak, withAllStakProfiler };

package/dist/index.d.ts

@@ -1,5 +1,113 @@
 import * as React from 'react';
 
+/**
+ * Minimal HTTP transport for React Native. Uses the global `fetch` (always
+ * present in RN >= 0.60) with a 3s timeout. Failed sends fall into a small
+ * in-memory ring buffer that we retry on the next successful flush.
+ *
+ * No window, no AbortController fallback shims — RN exposes both natively.
+ */
+declare class HttpTransport {
+    private baseUrl;
+    private apiKey;
+    private buffer;
+    private flushing;
+    constructor(baseUrl: string, apiKey: string);
+    send(path: string, payload: unknown): Promise<void>;
+    private doFetch;
+    private flushBuffer;
+    getBufferSize(): number;
+    /**
+     * Wait for the in-flight retry-buffer to drain. Resolves `true` if the
+     * buffer empties within `timeoutMs` (default 2000ms), `false` otherwise.
+     * Useful at process exit / before navigation away.
+     */
+    flush(timeoutMs?: number): Promise<boolean>;
+}
+
+/**
+ * HTTP request batching + transport for the React Native SDK.
+ *
+ * Mirrors the wire shape used by `@allstak/js`'s HttpRequestModule so the
+ * existing backend ingest endpoint (`/ingest/v1/http-requests`) accepts
+ * events from this SDK without a schema change. Adds optional rich fields
+ * (headers, bodies, error string) — these ride alongside the existing
+ * required fields and are tolerated as additive metadata server-side.
+ *
+ * Batching:
+ *   - flushes on a 5s timer OR when 20 events queue up
+ *   - flushes immediately on `destroy()`
+ *   - `getRecentFailed(n)` returns the last n failed requests (statusCode
+ *     >= 400 OR error set), used by error-linking on the next captureException
+ */
+
+/** What instrumentation hands to the module per request. */
+interface HttpRequestEvent {
+    type: 'http_request';
+    method: string;
+    url: string;
+    statusCode?: number;
+    durationMs: number;
+    requestSize?: number;
+    responseSize?: number;
+    requestBody?: string;
+    responseBody?: string;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    error?: string;
+    traceId?: string;
+}
+interface HttpRequestIngestItem {
+    type: 'http_request';
+    traceId: string;
+    direction: 'outbound';
+    method: string;
+    host: string;
+    path: string;
+    url: string;
+    statusCode: number;
+    durationMs: number;
+    requestSize?: number;
+    responseSize?: number;
+    requestBody?: string;
+    responseBody?: string;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    error?: string;
+    environment?: string;
+    release?: string;
+    dist?: string;
+    platform?: string;
+    'sdk.name'?: string;
+    'sdk.version'?: string;
+    timestamp: string;
+}
+interface ModuleDefaults {
+    environment?: string;
+    release?: string;
+    dist?: string;
+    platform?: string;
+    sdkName?: string;
+    sdkVersion?: string;
+}
+declare class HttpRequestModule {
+    private transport;
+    private queue;
+    private recentFailed;
+    private flushTimer;
+    private destroyed;
+    private defaults;
+    constructor(transport: HttpTransport);
+    setDefaults(defaults: ModuleDefaults): void;
+    capture(ev: HttpRequestEvent): void;
+    /** Snapshot of the last failed requests for error-linking. Newest last. */
+    getRecentFailed(): ReadonlyArray<HttpRequestIngestItem>;
+    flush(): void;
+    destroy(): void;
+    /** @internal — for tests. */
+    getQueueSize(): number;
+}
+
 /**
  * Per-call scoped context isolation.
  *
@@ -41,31 +149,6 @@ declare class Scope {
     clear(): this;
 }
 
-/**
- * Minimal HTTP transport for React Native. Uses the global `fetch` (always
- * present in RN >= 0.60) with a 3s timeout. Failed sends fall into a small
- * in-memory ring buffer that we retry on the next successful flush.
- *
- * No window, no AbortController fallback shims — RN exposes both natively.
- */
-declare class HttpTransport {
-    private baseUrl;
-    private apiKey;
-    private buffer;
-    private flushing;
-    constructor(baseUrl: string, apiKey: string);
-    send(path: string, payload: unknown): Promise<void>;
-    private doFetch;
-    private flushBuffer;
-    getBufferSize(): number;
-    /**
-     * Wait for the in-flight retry-buffer to drain. Resolves `true` if the
-     * buffer empties within `timeoutMs` (default 2000ms), `false` otherwise.
-     * Useful at process exit / before navigation away.
-     */
-    flush(timeoutMs?: number): Promise<boolean>;
-}
-
 /**
  * Lightweight distributed tracing primitives.
  *
@@ -192,19 +275,37 @@ declare class ReplayRecorder {
     private safeAttribute;
 }
 
-/**
- * Standalone AllStak client for the browser/React environment. No external
- * AllStak SDK dependencies — only the browser's native `fetch`, AbortController,
- * Date, JSON, and (optionally) `window` for unhandled error auto-capture.
- *
- * Surface mirrors the public AllStak API used by web apps:
- *   init / captureException / captureMessage / addBreadcrumb / clearBreadcrumbs
- *   setUser / setTag / setIdentity / getSessionId
- */
+interface HttpTrackingOptions {
+    /** Capture request body. Default false. Truncated to maxBodyBytes. */
+    captureRequestBody?: boolean;
+    /** Capture response body. Default false. Truncated to maxBodyBytes. */
+    captureResponseBody?: boolean;
+    /**
+     * Capture request + response headers. Default false. Hard-redacted
+     * names are always stripped regardless of this flag.
+     */
+    captureHeaders?: boolean;
+    /** Additional header names to redact (case-insensitive). */
+    redactHeaders?: string[];
+    /** Additional query-param names to redact (case-insensitive). */
+    redactQueryParams?: string[];
+    /**
+     * Skip URLs matching any of these patterns. String = case-insensitive
+     * substring match; RegExp = `.test()` against the full URL.
+     */
+    ignoredUrls?: (string | RegExp)[];
+    /**
+     * If non-empty, only capture URLs matching at least one of these
+     * patterns. Takes precedence over ignoredUrls.
+     */
+    allowedUrls?: (string | RegExp)[];
+    /** Max bytes per captured body. Default 4096. */
+    maxBodyBytes?: number;
+}
 
 declare const INGEST_HOST = "https://api.allstak.sa";
 declare const SDK_NAME = "allstak-react";
-declare const SDK_VERSION = "0.2.1";
+declare const SDK_VERSION = "0.3.0";
 
 interface AllStakConfig {
     /** Project API key (`ask_live_…`). Required. */
@@ -252,6 +353,17 @@ interface AllStakConfig {
      * the full privacy contract.
      */
     replay?: ReplayOptions;
+    /**
+     * Auto-instrument outbound HTTP — wraps `fetch`, `XMLHttpRequest`, and
+     * (when present) `axios`. Default: false.
+     */
+    enableHttpTracking?: boolean;
+    /**
+     * Privacy + capture controls for HTTP instrumentation. Bodies and
+     * headers are OFF by default; auth headers and sensitive query params
+     * are ALWAYS redacted.
+     */
+    httpTracking?: HttpTrackingOptions;
     /**
      * Probability in [0, 1] that any given error is sent. Default: 1 (no sampling).
      * Applied per event before {@link beforeSend}.
@@ -324,9 +436,15 @@ declare class AllStakClient {
     private scopeStack;
     private tracing;
     private replay;
+    private httpRequests;
+    private _instrumentAxios;
     private onErrorHandler;
     private onRejectionHandler;
     constructor(config: AllStakConfig);
+    /** Manually instrument an axios instance. No-op when HTTP tracking is off. */
+    instrumentAxios<T = any>(axios: T): T;
+    /** Snapshot of recent failed HTTP requests for error-linking. */
+    getRecentFailedHttp(): readonly HttpRequestIngestItem[];
     captureException(error: Error, context?: Record<string, unknown>): void;
     /** Start a new span — auto-parented to any currently-active span. */
     startSpan(operation: string, options?: {
@@ -450,6 +568,8 @@ declare const AllStak: {
     setTraceId(traceId: string): void;
     getCurrentSpanId(): string | null;
     resetTrace(): void;
+    /** Manually instrument an axios instance. No-op when HTTP tracking is off. */
+    instrumentAxios<T = any>(axios: T): T;
     getSessionId(): string;
     getConfig(): AllStakConfig | null;
     destroy(): void;
@@ -549,4 +669,4 @@ declare function useAllStak(): {
  */
 declare function withAllStakProfiler<P extends object>(Component: React.ComponentType<P>, name?: string): React.FC<P>;
 
-export { AllStak, AllStakClient, type AllStakConfig, AllStakErrorBoundary, type AllStakErrorBoundaryProps, type Breadcrumb, INGEST_HOST, type ReplayOptions, ReplayRecorder, SDK_NAME, SDK_VERSION, Scope, instrumentBrowserNavigation, instrumentConsole, instrumentFetch, instrumentNextRouter, instrumentReactRouter, useAllStak, withAllStakProfiler };
+export { AllStak, AllStakClient, type AllStakConfig, AllStakErrorBoundary, type AllStakErrorBoundaryProps, type Breadcrumb, type HttpRequestEvent, HttpRequestModule, type HttpTrackingOptions, INGEST_HOST, type ReplayOptions, ReplayRecorder, SDK_NAME, SDK_VERSION, Scope, instrumentBrowserNavigation, instrumentConsole, instrumentFetch, instrumentNextRouter, instrumentReactRouter, useAllStak, withAllStakProfiler };