@atsignal/js-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,393 @@
+type MaybePromise<T> = T | Promise<T>;
+type FlushMode = "immediate" | "scheduled";
+type FlushReason = "scheduled" | "immediate" | "manual" | "shutdown" | "retry";
+declare const EVENT_TIME_KEY = "@time";
+declare const EVENT_INSERT_ID_KEY = "@insertid";
+declare const EVENT_USER_ID_KEY = "@userid";
+declare const EVENT_TYPE_KEY = "@event";
+interface RetryConfig {
+    baseMs?: number;
+    maxMs?: number;
+    maxAttempts?: number;
+    jitter?: number;
+}
+interface TrackedEvent {
+    [EVENT_TYPE_KEY]: string;
+    [EVENT_TIME_KEY]: number;
+    [EVENT_USER_ID_KEY]: string | null;
+    [EVENT_INSERT_ID_KEY]: string;
+    [key: string]: unknown;
+}
+type TrackProperties = Record<string, unknown>;
+interface TrackOptions {
+    flush?: FlushMode;
+    endpoint?: string;
+    timeoutMs?: number;
+    retries?: number;
+}
+interface ResolvedTrackOptions {
+    flush: FlushMode;
+    endpoint: string;
+    timeoutMs?: number;
+    retries: number;
+}
+interface PersistedQueueEntry {
+    id: string;
+    deviceId: string;
+    event: TrackedEvent;
+    options: ResolvedTrackOptions;
+    attempts: number;
+}
+interface TransportEventGroup {
+    deviceId: string;
+    events: TrackedEvent[];
+}
+interface KeyValueStorage {
+    get<T>(key: string): MaybePromise<T | null>;
+    set<T>(key: string, value: T): MaybePromise<void>;
+    remove(key: string): MaybePromise<void>;
+}
+/**
+ * Queue storage contract is intentionally queue-oriented (not key-value)
+ * so backends like IndexedDB/SQLite can persist deltas efficiently.
+ * `load` must return entries in enqueue order (oldest first).
+ */
+interface QueueStorage {
+    load(limit: number): MaybePromise<PersistedQueueEntry[]>;
+    upsert(entries: PersistedQueueEntry[]): MaybePromise<void>;
+    remove(ids: string[]): MaybePromise<void>;
+    trim(maxEntries: number): MaybePromise<void>;
+    clear(): MaybePromise<void>;
+}
+type QueueStorageInput = QueueStorage | KeyValueStorage;
+interface ClientStorageConfig {
+    identity: KeyValueStorage;
+    queue: QueueStorageInput;
+}
+interface TransportRequest {
+    apiKey: string;
+    endpoint: string;
+    /**
+     * Flattened view of the request payload for transports that want
+     * to inspect every event without regrouping by device ID.
+     */
+    events: TrackedEvent[];
+    /**
+     * Canonical transport payload grouped by request device ID.
+     */
+    eventGroups: TransportEventGroup[];
+    /**
+     * Request-level location-from-IP toggle.
+     * This is distinct from any event-level `@ip` value.
+     */
+    locationFromIp: boolean;
+    txTime: number;
+    timeoutMs?: number;
+}
+interface TransportResult {
+    ok: boolean;
+    status?: number;
+    retryable?: boolean;
+    error?: unknown;
+}
+interface Transport {
+    send(request: TransportRequest): Promise<TransportResult>;
+    flush?(): Promise<void>;
+    shutdown?(): Promise<void>;
+}
+interface ClientIdentity {
+    userId: string | null;
+    deviceId: string;
+}
+interface ResolvedClientConfig {
+    endpoint: string;
+    flushIntervalMs: number;
+    maxBatchSize: number;
+    maxQueueSize: number;
+    retry: Required<RetryConfig>;
+    /**
+     * Queue durability toggle.
+     * `true`: persist queue using configured queue storage.
+     * `false`: keep queue in memory only.
+     */
+    persistQueue: boolean;
+    /**
+     * Request-level location-from-IP toggle.
+     * This is distinct from any event-level `@ip` value.
+     */
+    locationFromIp: boolean;
+    optOut: boolean;
+    partId: string;
+    version?: string;
+    blockedProperties: readonly string[];
+}
+interface InitHookContext {
+    config: ResolvedClientConfig;
+    identity: Readonly<ClientIdentity>;
+    optOut: boolean;
+}
+interface EventCreatedHookContext {
+    event: TrackedEvent;
+    options: Readonly<ResolvedTrackOptions>;
+    drop: () => void;
+}
+interface BeforeEnqueueHookContext {
+    event: TrackedEvent;
+    options: Readonly<ResolvedTrackOptions>;
+    drop: () => void;
+}
+interface EventQueuedHookContext {
+    event: Readonly<TrackedEvent>;
+    options: Readonly<ResolvedTrackOptions>;
+    queuedEvents: number;
+}
+interface BeforeFlushHookContext {
+    reason: FlushReason;
+    queuedEvents: number;
+}
+interface AfterFlushHookContext {
+    reason: FlushReason;
+    attempted: number;
+    sent: number;
+    dropped: number;
+    queuedEvents: number;
+}
+interface BeforeSendHookContext {
+    reason: FlushReason;
+    event: TrackedEvent;
+    options: Readonly<ResolvedTrackOptions>;
+    attempt: number;
+    drop: () => void;
+}
+type SendOutcome = "sent" | "retry" | "dropped";
+interface AfterSendHookContext {
+    reason: FlushReason;
+    event: Readonly<TrackedEvent>;
+    options: Readonly<ResolvedTrackOptions>;
+    attempt: number;
+    outcome: SendOutcome;
+    txTime?: number;
+    result?: Readonly<TransportResult>;
+    queuedEvents: number;
+}
+interface OptOutChangedHookContext {
+    previousOptOut: boolean;
+    optOut: boolean;
+}
+type IdentityChangeReason = "logged-in" | "logged-out" | "reset";
+interface IdentityChangedHookContext {
+    reason: IdentityChangeReason;
+    previousIdentity: Readonly<ClientIdentity>;
+    identity: Readonly<ClientIdentity>;
+}
+interface ErrorHookContext {
+    stage: string;
+    error: unknown;
+    pluginName?: string;
+}
+type Unsubscribe = () => void;
+interface ClientHooks {
+    onInit(listener: (context: InitHookContext) => MaybePromise<void>): Unsubscribe;
+    onEventCreated(listener: (context: EventCreatedHookContext) => MaybePromise<void>): Unsubscribe;
+    onBeforeEnqueue(listener: (context: BeforeEnqueueHookContext) => MaybePromise<void>): Unsubscribe;
+    onEventQueued(listener: (context: EventQueuedHookContext) => MaybePromise<void>): Unsubscribe;
+    onBeforeFlush(listener: (context: BeforeFlushHookContext) => MaybePromise<void>): Unsubscribe;
+    onAfterFlush(listener: (context: AfterFlushHookContext) => MaybePromise<void>): Unsubscribe;
+    onBeforeSend(listener: (context: BeforeSendHookContext) => MaybePromise<void>): Unsubscribe;
+    onAfterSend(listener: (context: AfterSendHookContext) => MaybePromise<void>): Unsubscribe;
+    onIdentityChanged(listener: (context: IdentityChangedHookContext) => MaybePromise<void>): Unsubscribe;
+    onOptOutChanged(listener: (context: OptOutChangedHookContext) => MaybePromise<void>): Unsubscribe;
+    onError(listener: (context: ErrorHookContext) => void): Unsubscribe;
+}
+interface PluginSetupContext {
+    hooks: ClientHooks;
+    config: ResolvedClientConfig;
+}
+interface ClientPlugin {
+    name: string;
+    setup?(context: PluginSetupContext): MaybePromise<void>;
+    flush?(): Promise<void>;
+    teardown?(): Promise<void>;
+}
+interface ClientConfig {
+    userId?: string | null;
+    deviceId?: string;
+    /**
+     * Request-level location-from-IP toggle.
+     * This is distinct from any event-level `@ip` value.
+     */
+    locationFromIp?: boolean;
+    optOut?: boolean;
+    version?: string | null;
+    endpoint?: string;
+    flushIntervalMs?: number;
+    maxBatchSize?: number;
+    maxQueueSize?: number;
+    retry?: RetryConfig;
+    /**
+     * Queue durability toggle.
+     * `true` (default): persist queue using configured `storage.queue`.
+     * `false`: keep queue in memory only.
+     */
+    persistQueue?: boolean;
+    partId?: string;
+    /**
+     * Event property names to omit from queued and transported events.
+     * The list is fixed for the lifetime of the client instance.
+     */
+    blockedProperties?: readonly string[];
+    plugins?: ClientPlugin[];
+    storage?: Partial<ClientStorageConfig>;
+    transport?: Transport;
+}
+
+declare class SignalClient<TInitOptions extends object = ClientConfig> {
+    private _apiKey;
+    private _config;
+    private _storage;
+    private _transport;
+    private _hooks;
+    private _insertIdGenerator;
+    private _pluginRuntime;
+    private _blockedProperties;
+    private _identity;
+    private _optOut;
+    private _queue;
+    private _ready;
+    private _state;
+    private _initError;
+    private _queuedMutations;
+    private _drainingQueuedMutations;
+    private _flushTask;
+    private _mutationQueue;
+    private _mutationDrainPromise;
+    private _automaticFlushPending;
+    private _activeAutomaticFlushReason;
+    private _acceptEvents;
+    private _shutdownPromise;
+    hooks(): ClientHooks;
+    init(apiKey: string, options?: TInitOptions): Promise<this>;
+    protected resolveInitConfig(options: TInitOptions): ClientConfig;
+    add(plugin: ClientPlugin): Promise<void>;
+    remove(pluginName: string): Promise<boolean>;
+    listPlugins(): ClientPlugin[];
+    loggedIn(userId: string): Promise<void>;
+    loggedOut(): Promise<void>;
+    reset(deviceId?: string): Promise<void>;
+    userId(): string | null;
+    optOut(): boolean;
+    setOptOut(optOut: boolean): Promise<void>;
+    track(event: string, properties?: TrackProperties, options?: TrackOptions): Promise<void>;
+    trackNow(event: string, properties?: TrackProperties, options?: Omit<TrackOptions, "flush">): Promise<void>;
+    flush(reason?: FlushReason): Promise<void>;
+    shutdown(): Promise<void>;
+    config(): Readonly<ResolvedClientConfig>;
+    private _applyNormalizedConfig;
+    private _requireReadyRuntime;
+    private _queueOrRunMutation;
+    private _queueOrRunMutationWithResult;
+    private _drainQueuedMutations;
+    private _rejectQueuedMutations;
+    private _shutdownError;
+    private _isShutdown;
+    private _enqueueMutation;
+    private _ensureMutationDrain;
+    private _drainMutations;
+    private _rejectMutationTask;
+    private _awaitMutationPrerequisites;
+    private _runMutationTask;
+    private _runIdentityMutationTask;
+    private _runOptOutMutationTask;
+    private _runTrackFamilyMutationTask;
+    private _runFlushMutationTask;
+    private _runShutdownMutationTask;
+    private _initialize;
+    private _hydrateIdentity;
+    private _applyInitialIdentityOverrides;
+    private _hydrateQueue;
+    private _createQueueEntry;
+    private _resolveTrackOptions;
+    private _enqueue;
+    private _scheduleAutomaticFlush;
+    private _performFlush;
+    private _computeBackoff;
+    private _persistIdentity;
+    private _emitIdentityChanged;
+    private _cancelScheduledFlush;
+    private _clearQueueStorage;
+    private _upsertQueueEntries;
+    private _removeQueueEntries;
+    private _trimQueueStorage;
+    private _emitError;
+    private _prepareBatchForTransport;
+    private _removeDroppedBeforeSendEntries;
+    private _createTransportRequest;
+    private _handleSuccessfulTransportBatch;
+    private _handleFailedTransportBatch;
+    private _emitTransportFailure;
+    private _stripBlockedProperties;
+}
+
+declare class HookRegistry implements ClientHooks {
+    private _onInit;
+    private _onEventCreated;
+    private _onBeforeEnqueue;
+    private _onEventQueued;
+    private _onBeforeFlush;
+    private _onAfterFlush;
+    private _onBeforeSend;
+    private _onAfterSend;
+    private _onIdentityChanged;
+    private _onOptOutChanged;
+    private _onError;
+    onInit(listener: (context: InitHookContext) => MaybePromise<void>): Unsubscribe;
+    onEventCreated(listener: (context: EventCreatedHookContext) => MaybePromise<void>): Unsubscribe;
+    onBeforeEnqueue(listener: (context: BeforeEnqueueHookContext) => MaybePromise<void>): Unsubscribe;
+    onEventQueued(listener: (context: EventQueuedHookContext) => MaybePromise<void>): Unsubscribe;
+    onBeforeFlush(listener: (context: BeforeFlushHookContext) => MaybePromise<void>): Unsubscribe;
+    onAfterFlush(listener: (context: AfterFlushHookContext) => MaybePromise<void>): Unsubscribe;
+    onBeforeSend(listener: (context: BeforeSendHookContext) => MaybePromise<void>): Unsubscribe;
+    onAfterSend(listener: (context: AfterSendHookContext) => MaybePromise<void>): Unsubscribe;
+    onIdentityChanged(listener: (context: IdentityChangedHookContext) => MaybePromise<void>): Unsubscribe;
+    onOptOutChanged(listener: (context: OptOutChangedHookContext) => MaybePromise<void>): Unsubscribe;
+    onError(listener: (context: ErrorHookContext) => void): Unsubscribe;
+    emitInit(context: InitHookContext): Promise<void>;
+    emitEventCreated(context: EventCreatedHookContext): Promise<void>;
+    emitBeforeEnqueue(context: BeforeEnqueueHookContext): Promise<void>;
+    emitEventQueued(context: EventQueuedHookContext): Promise<void>;
+    emitBeforeFlush(context: BeforeFlushHookContext): Promise<void>;
+    emitAfterFlush(context: AfterFlushHookContext): Promise<void>;
+    emitBeforeSend(context: BeforeSendHookContext): Promise<void>;
+    emitAfterSend(context: AfterSendHookContext): Promise<void>;
+    emitIdentityChanged(context: IdentityChangedHookContext): Promise<void>;
+    emitOptOutChanged(context: OptOutChangedHookContext): Promise<void>;
+    emitError(context: ErrorHookContext): void;
+    private _emitAsync;
+}
+
+declare class InMemoryStorage implements KeyValueStorage {
+    private _map;
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T): void;
+    remove(key: string): void;
+}
+
+interface FetchResponseLike {
+    ok: boolean;
+    status: number;
+}
+interface FetchRequestInitLike {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    keepalive?: boolean;
+}
+type FetchLike = (input: string, init?: FetchRequestInitLike) => Promise<FetchResponseLike>;
+interface FetchTransportOptions {
+    fetch?: FetchLike;
+    keepalive?: boolean;
+    headers?: Record<string, string>;
+}
+declare function createFetchTransport(options?: FetchTransportOptions): Transport;
+
+export { type ClientConfig, type ClientHooks, type ClientIdentity, type ClientPlugin, type FlushMode, type FlushReason, HookRegistry, InMemoryStorage, type KeyValueStorage, type PersistedQueueEntry, type PluginSetupContext, type QueueStorage, type QueueStorageInput, type ResolvedClientConfig, type RetryConfig, SignalClient, type TrackOptions, type TrackProperties, type TrackedEvent, type Transport, type TransportEventGroup, type TransportRequest, type TransportResult, createFetchTransport };