@sheepit-ai/sdk-js 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,170 @@
+import { F as FlagValue, E as ExperimentResult, S as SDKStatus, D as DiagnosticBus, a as DiagnosticEvent, G as GoaTechConfig } from './types-CxAq_Cds.mjs';
+export { B as BrowserErrorCapture, C as Condition, b as ConditionOp, c as DeviceInfo, d as DiagnosticCategory, e as DiagnosticListener, f as DiagnosticSeverity, g as EnrichedEvent, h as ErrorCaptureConfig, i as EventContext, j as ExperimentConfig, k as ExperimentStatus, l as ExperimentVariant, m as FlagConfig, n as FlagRule, H as HttpErrorCapture, o as HttpErrorCaptureConfig, p as HttpErrorEventDetail, q as SDKConfig, r as SubscribeOptions } from './types-CxAq_Cds.mjs';
+export { BootErrorPayload, BootErrorScriptOptions, getBootErrorScript } from './boot-error.mjs';
+
+/**
+ * Public API surface of a GoaTech client instance.
+ * Use this type when you need to pass around a client reference
+ * without depending on the concrete GoaTech class.
+ */
+interface IGoaTech {
+    track(eventName: string, properties?: Record<string, unknown>): void;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    reset(): void;
+    flag(flagKey: string, defaultValue?: FlagValue): FlagValue;
+    experiment(experimentKey: string): ExperimentResult;
+    /** Override a flag value for local testing. Only active when debug=true. */
+    overrideFlag(key: string, value: FlagValue): void;
+    /** Clear all debug overrides. */
+    clearOverrides(): void;
+    /** Get all current debug overrides (for debug menu UI). */
+    getOverrides(): Record<string, unknown>;
+    flush(): Promise<void>;
+    /** Notify the SDK of a route change in a single-page app. Emits a
+     * synthetic `$page_leave` for the prior route (if any) and resets
+     * the page-leave timer for the new path. */
+    recordPageView(path: string): void;
+    status(): SDKStatus;
+    destroy(): void;
+    /** Access the diagnostic event bus for runtime subscribe/unsubscribe. */
+    diagnostics(): DiagnosticBus;
+    /** Get buffered recent diagnostic events. */
+    getRecentDiagnostics(): DiagnosticEvent[];
+}
+
+declare class GoaTech implements IGoaTech {
+    private static instance;
+    private readonly cfg;
+    private readonly log;
+    private readonly bus;
+    private readonly context;
+    private readonly queue;
+    private readonly flagManager;
+    private readonly experimentManager;
+    private readonly identityManager;
+    private readonly configSync;
+    private readonly transport;
+    private readonly offlineQueue;
+    private readonly connectivity;
+    private readonly lifecycle;
+    private readonly errorCapture;
+    private readonly httpErrorCapture;
+    private readonly clickFrustrationCapture;
+    private flushTimer;
+    private destroyed;
+    private constructor();
+    /**
+     * Create a new, independent GoaTech instance.
+     * The caller owns the instance lifecycle — no global state.
+     * Preferred for React apps (pass instance to Context).
+     */
+    static create(config: GoaTechConfig): GoaTech;
+    /**
+     * Create a singleton instance. Returns existing instance if already
+     * initialized (logs a warning). Call `destroy()` first to re-initialize.
+     *
+     * For React apps, prefer `GoaTech.create()` + Context instead.
+     */
+    static init(config: GoaTechConfig): GoaTech;
+    /** Get the singleton instance. Throws if `init()` was never called. */
+    static getInstance(): GoaTech;
+    /**
+     * Returns true if the singleton has been initialized via `init()`.
+     * Useful for HMR guards and conditional initialization.
+     */
+    static isInitialized(): boolean;
+    /**
+     * Queue an analytics event. Auto-flushes when the queue reaches
+     * `flushSize` (default 20) or when the periodic flush timer fires.
+     *
+     * @example
+     * gt.track("course_viewed", { course_id: "c_123", source: "catalog" });
+     */
+    track(eventName: string, properties?: Record<string, unknown>): void;
+    /**
+     * Resolve a feature flag for the current device + identity. Reads
+     * the cached server-evaluated value from `/v1/config` (refreshed on
+     * `configRefreshInterval`). Fires `$flag_exposure` once per session
+     * per flag.
+     *
+     * @example
+     * if (gt.flag("new_checkout_flow", false)) {
+     *   renderNewCheckout();
+     * }
+     */
+    flag(flagKey: string, defaultValue?: FlagValue): FlagValue;
+    overrideFlag(key: string, value: FlagValue): void;
+    clearOverrides(): void;
+    getOverrides(): Record<string, unknown>;
+    /**
+     * Resolve the bucketed variant + payload for an experiment. Sticky
+     * per device. Fires `$experiment_exposure` once per session per
+     * experiment.
+     *
+     * @example
+     * const { variant, payload } = gt.experiment("hero_h1_copy_v1");
+     * if (variant !== "control") setHeadline((payload as { headline: string }).headline);
+     */
+    experiment(experimentKey: string): ExperimentResult;
+    /**
+     * Tie the current device to a stable user id and merge traits onto
+     * the GoaTech user record. Re-identifying with a different userId
+     * clears the cached experiment assignments so the new identity
+     * gets fresh buckets.
+     *
+     * @example
+     * await api.login(form);
+     * gt.identify("user_abc123", { email: "jane@example.com", plan: "pro" });
+     */
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    /**
+     * Forget the current identity + experiment assignments and start a
+     * fresh anonymous session. Call on logout.
+     *
+     * @example
+     * await api.logout();
+     * gt.reset();
+     */
+    reset(): void;
+    /**
+     * Drain any queued events to the GoaTech ingest endpoint. Useful
+     * before navigation in single-page apps and required before
+     * Vercel/Lambda function exits.
+     *
+     * @example
+     * router.beforeEach(async () => {
+     *   await gt.flush();
+     * });
+     */
+    flush(): Promise<void>;
+    /**
+     * Notify the SDK of a route change. The first call starts a page-leave
+     * timer; subsequent calls emit a synthetic `$page_leave` for the prior
+     * route (with `exit_kind: "spa_nav"`) before resetting state. Wire
+     * this into your router — for Next.js, use `<PageViewTracker>` from
+     * `@sheepit-ai/react`, which calls this for you.
+     *
+     * Idempotent for repeat calls with the same path.
+     */
+    recordPageView(path: string): void;
+    status(): SDKStatus;
+    diagnostics(): DiagnosticBus;
+    getRecentDiagnostics(): DiagnosticEvent[];
+    /**
+     * Stop all timers, drain remaining events, and tear down auto-error
+     * + lifecycle listeners. After `destroy()` further `track()` /
+     * `flag()` calls are no-ops. Idempotent.
+     *
+     * @example
+     * // Replacing the SDK instance (rare; usually just call once)
+     * const old = GoaTech.getInstance();
+     * old.destroy();
+     * const fresh = GoaTech.init({ apiKey: nextKey });
+     */
+    destroy(): void;
+    private start;
+    private applyConfig;
+    private postIdentityResolve;
+}
+
+export { DiagnosticBus, DiagnosticEvent, ExperimentResult, FlagValue, GoaTech, GoaTechConfig, type IGoaTech, SDKStatus };

package/dist/index.d.ts

@@ -0,0 +1,170 @@
+import { F as FlagValue, E as ExperimentResult, S as SDKStatus, D as DiagnosticBus, a as DiagnosticEvent, G as GoaTechConfig } from './types-CxAq_Cds.js';
+export { B as BrowserErrorCapture, C as Condition, b as ConditionOp, c as DeviceInfo, d as DiagnosticCategory, e as DiagnosticListener, f as DiagnosticSeverity, g as EnrichedEvent, h as ErrorCaptureConfig, i as EventContext, j as ExperimentConfig, k as ExperimentStatus, l as ExperimentVariant, m as FlagConfig, n as FlagRule, H as HttpErrorCapture, o as HttpErrorCaptureConfig, p as HttpErrorEventDetail, q as SDKConfig, r as SubscribeOptions } from './types-CxAq_Cds.js';
+export { BootErrorPayload, BootErrorScriptOptions, getBootErrorScript } from './boot-error.js';
+
+/**
+ * Public API surface of a GoaTech client instance.
+ * Use this type when you need to pass around a client reference
+ * without depending on the concrete GoaTech class.
+ */
+interface IGoaTech {
+    track(eventName: string, properties?: Record<string, unknown>): void;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    reset(): void;
+    flag(flagKey: string, defaultValue?: FlagValue): FlagValue;
+    experiment(experimentKey: string): ExperimentResult;
+    /** Override a flag value for local testing. Only active when debug=true. */
+    overrideFlag(key: string, value: FlagValue): void;
+    /** Clear all debug overrides. */
+    clearOverrides(): void;
+    /** Get all current debug overrides (for debug menu UI). */
+    getOverrides(): Record<string, unknown>;
+    flush(): Promise<void>;
+    /** Notify the SDK of a route change in a single-page app. Emits a
+     * synthetic `$page_leave` for the prior route (if any) and resets
+     * the page-leave timer for the new path. */
+    recordPageView(path: string): void;
+    status(): SDKStatus;
+    destroy(): void;
+    /** Access the diagnostic event bus for runtime subscribe/unsubscribe. */
+    diagnostics(): DiagnosticBus;
+    /** Get buffered recent diagnostic events. */
+    getRecentDiagnostics(): DiagnosticEvent[];
+}
+
+declare class GoaTech implements IGoaTech {
+    private static instance;
+    private readonly cfg;
+    private readonly log;
+    private readonly bus;
+    private readonly context;
+    private readonly queue;
+    private readonly flagManager;
+    private readonly experimentManager;
+    private readonly identityManager;
+    private readonly configSync;
+    private readonly transport;
+    private readonly offlineQueue;
+    private readonly connectivity;
+    private readonly lifecycle;
+    private readonly errorCapture;
+    private readonly httpErrorCapture;
+    private readonly clickFrustrationCapture;
+    private flushTimer;
+    private destroyed;
+    private constructor();
+    /**
+     * Create a new, independent GoaTech instance.
+     * The caller owns the instance lifecycle — no global state.
+     * Preferred for React apps (pass instance to Context).
+     */
+    static create(config: GoaTechConfig): GoaTech;
+    /**
+     * Create a singleton instance. Returns existing instance if already
+     * initialized (logs a warning). Call `destroy()` first to re-initialize.
+     *
+     * For React apps, prefer `GoaTech.create()` + Context instead.
+     */
+    static init(config: GoaTechConfig): GoaTech;
+    /** Get the singleton instance. Throws if `init()` was never called. */
+    static getInstance(): GoaTech;
+    /**
+     * Returns true if the singleton has been initialized via `init()`.
+     * Useful for HMR guards and conditional initialization.
+     */
+    static isInitialized(): boolean;
+    /**
+     * Queue an analytics event. Auto-flushes when the queue reaches
+     * `flushSize` (default 20) or when the periodic flush timer fires.
+     *
+     * @example
+     * gt.track("course_viewed", { course_id: "c_123", source: "catalog" });
+     */
+    track(eventName: string, properties?: Record<string, unknown>): void;
+    /**
+     * Resolve a feature flag for the current device + identity. Reads
+     * the cached server-evaluated value from `/v1/config` (refreshed on
+     * `configRefreshInterval`). Fires `$flag_exposure` once per session
+     * per flag.
+     *
+     * @example
+     * if (gt.flag("new_checkout_flow", false)) {
+     *   renderNewCheckout();
+     * }
+     */
+    flag(flagKey: string, defaultValue?: FlagValue): FlagValue;
+    overrideFlag(key: string, value: FlagValue): void;
+    clearOverrides(): void;
+    getOverrides(): Record<string, unknown>;
+    /**
+     * Resolve the bucketed variant + payload for an experiment. Sticky
+     * per device. Fires `$experiment_exposure` once per session per
+     * experiment.
+     *
+     * @example
+     * const { variant, payload } = gt.experiment("hero_h1_copy_v1");
+     * if (variant !== "control") setHeadline((payload as { headline: string }).headline);
+     */
+    experiment(experimentKey: string): ExperimentResult;
+    /**
+     * Tie the current device to a stable user id and merge traits onto
+     * the GoaTech user record. Re-identifying with a different userId
+     * clears the cached experiment assignments so the new identity
+     * gets fresh buckets.
+     *
+     * @example
+     * await api.login(form);
+     * gt.identify("user_abc123", { email: "jane@example.com", plan: "pro" });
+     */
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    /**
+     * Forget the current identity + experiment assignments and start a
+     * fresh anonymous session. Call on logout.
+     *
+     * @example
+     * await api.logout();
+     * gt.reset();
+     */
+    reset(): void;
+    /**
+     * Drain any queued events to the GoaTech ingest endpoint. Useful
+     * before navigation in single-page apps and required before
+     * Vercel/Lambda function exits.
+     *
+     * @example
+     * router.beforeEach(async () => {
+     *   await gt.flush();
+     * });
+     */
+    flush(): Promise<void>;
+    /**
+     * Notify the SDK of a route change. The first call starts a page-leave
+     * timer; subsequent calls emit a synthetic `$page_leave` for the prior
+     * route (with `exit_kind: "spa_nav"`) before resetting state. Wire
+     * this into your router — for Next.js, use `<PageViewTracker>` from
+     * `@sheepit-ai/react`, which calls this for you.
+     *
+     * Idempotent for repeat calls with the same path.
+     */
+    recordPageView(path: string): void;
+    status(): SDKStatus;
+    diagnostics(): DiagnosticBus;
+    getRecentDiagnostics(): DiagnosticEvent[];
+    /**
+     * Stop all timers, drain remaining events, and tear down auto-error
+     * + lifecycle listeners. After `destroy()` further `track()` /
+     * `flag()` calls are no-ops. Idempotent.
+     *
+     * @example
+     * // Replacing the SDK instance (rare; usually just call once)
+     * const old = GoaTech.getInstance();
+     * old.destroy();
+     * const fresh = GoaTech.init({ apiKey: nextKey });
+     */
+    destroy(): void;
+    private start;
+    private applyConfig;
+    private postIdentityResolve;
+}
+
+export { DiagnosticBus, DiagnosticEvent, ExperimentResult, FlagValue, GoaTech, GoaTechConfig, type IGoaTech, SDKStatus };