@lessonkit/xapi 1.3.1 → 1.5.0

package/dist/index.d.cts

@@ -37,8 +37,10 @@ type XAPIQueue = {
     flush: (transport: XAPITransport) => Promise<void>;
     flushOnExit: (exitTransport: XAPIExitTransport) => void;
     size: () => number;
+    /** Statement id currently being delivered via flush, if any. */
+    getHeadInFlightId?: () => string | undefined;
 };
-type XAPIExitTransport = (statement: XAPIStatement) => void;
+type XAPIExitTransport = (statement: XAPIStatement) => void | Promise<void>;
 type XAPIClient = {
     send: (statement: XAPIStatement) => void;
     flush: () => Promise<void>;
@@ -65,24 +67,54 @@ type InMemoryXAPIQueueOptions = {
     onDepth?: (size: number) => void;
     /** Called when an oldest statement is dropped because the queue is at maxSize. */
     onCap?: () => void;
+    /** Called when a statement cannot be enqueued because the queue is full and the head is in-flight. */
+    onOverflow?: (statement: XAPIStatement) => void;
+    /** Failures at queue head before skipping (default 10). */
+    maxHeadFailures?: number;
+    /** Called when the queue head is skipped after repeated transport failures. */
+    onHeadSkipped?: (statement: XAPIStatement, err: unknown) => void;
 };
 declare function createInMemoryXAPIQueue(opts?: InMemoryXAPIQueueOptions): XAPIQueue;
 
+/**
+ * Imperative xAPI client with in-memory queue, retry flush, and optional pagehide delivery.
+ * Prefer wiring transport via `LessonkitProvider` config from `@lessonkit/react` in React apps.
+ */
 declare function createXAPIClient(opts?: {
     transport?: XAPITransport;
     /** Keepalive transport for pagehide flush (e.g. from createFetchTransport). */
     exitTransport?: XAPIExitTransport;
+    /** Abort in-flight transport by statement id (e.g. from createFetchTransport). */
+    abortInFlight?: (statementId: string) => void;
     courseId?: CourseId;
     queue?: XAPIQueue;
     /** When creating the default in-memory queue (max size 1000 unless overridden). */
     maxQueueSize?: number;
+    /** Consecutive head failures before skip (default queue only). */
+    maxHeadFailures?: number;
     onQueueDepth?: (size: number) => void;
     onQueueCap?: () => void;
+    onHeadSkipped?: (statement: XAPIStatement, err: unknown) => void;
+    /** Called when transport fails after retries (statement is re-queued). */
+    onTransportError?: (err: unknown) => void;
+    /** Called when telemetry → xAPI mapping fails. */
+    onMappingError?: (err: unknown) => void;
 }): XAPIClient;
+/** @internal Reset dead-letter storage between tests. */
+declare function resetXAPIDeadLetterForTests(): void;
+
+type AssertSafeLrsUrlOptions = {
+    /** Allow loopback, RFC1918, link-local, and metadata IPs (default false). */
+    allowPrivateHosts?: boolean;
+};
+/** Validate an LRS or analytics proxy URL before browser fetch transport use. */
+declare function assertSafeLrsUrl(url: string, opts?: AssertSafeLrsUrlOptions): void;
 
 type CreateFetchTransportOptions = {
     /** LRS or proxy endpoint (POST). */
     url: string;
+    /** Allow loopback and private-network hosts (default false). */
+    allowPrivateHosts?: boolean;
     /** Per-request timeout (default 30_000 ms). Uses AbortSignal.timeout when available. */
     timeoutMs?: number;
     /** Static headers merged into each request (e.g. Authorization from a short-lived token). */
@@ -100,7 +132,17 @@ type FetchTransportBundle = {
     transport: XAPITransport;
     /** Best-effort synchronous delivery for pagehide (keepalive fetch). */
     exitTransport: (statement: XAPIStatement) => void;
+    /** Abort an in-flight transport request by statement id (used on pagehide). */
+    abortInFlight: (statementId: string) => void;
 };
+/** HTTP error from fetch transport with status for retry policy. */
+declare class FetchHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, statusText: string, kind?: "xapi" | "batch");
+}
+/** Retry 429 and 5xx; do not retry other 4xx (auth/config errors). */
+declare function isRetryableFetchHttpStatus(status: number): boolean;
+declare function isRetryableFetchError(err: unknown): boolean;
 /**
  * Creates an xAPI transport backed by fetch with timeout, retry backoff, and a
  * keepalive exit transport for pagehide delivery.
@@ -117,10 +159,13 @@ type FetchBatchSinkBundle = {
  */
 declare function createFetchBatchSink(opts: CreateFetchBatchSinkOptions): FetchBatchSinkBundle;
 
+declare function loadDeadLetterStatements(): XAPIStatement[];
+declare function persistDeadLetterStatement(statement: XAPIStatement): void;
+
 /**
  * Map a LessonKit telemetry event to an xAPI statement, or null if the event should not emit xAPI.
  * `lesson_time_on_task` returns null (companion metric; lesson_completed carries duration).
  */
 declare function telemetryEventToXAPIStatement(event: TelemetryEvent): XAPIStatement | null;
 
-export { type CreateFetchBatchSinkOptions, type CreateFetchTransportOptions, type FetchBatchSinkBundle, type FetchTransportBundle, type InMemoryXAPIQueueOptions, type XAPIClient, type XAPIExitTransport, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, createFetchBatchSink, createFetchTransport, createInMemoryXAPIQueue, createXAPIClient, telemetryEventToXAPIStatement };
+export { type AssertSafeLrsUrlOptions, type CreateFetchBatchSinkOptions, type CreateFetchTransportOptions, type FetchBatchSinkBundle, FetchHttpError, type FetchTransportBundle, type InMemoryXAPIQueueOptions, type XAPIClient, type XAPIExitTransport, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, assertSafeLrsUrl, createFetchBatchSink, createFetchTransport, createInMemoryXAPIQueue, createXAPIClient, isRetryableFetchError, isRetryableFetchHttpStatus, loadDeadLetterStatements, persistDeadLetterStatement, resetXAPIDeadLetterForTests, telemetryEventToXAPIStatement };

package/dist/index.d.ts

@@ -37,8 +37,10 @@ type XAPIQueue = {
     flush: (transport: XAPITransport) => Promise<void>;
     flushOnExit: (exitTransport: XAPIExitTransport) => void;
     size: () => number;
+    /** Statement id currently being delivered via flush, if any. */
+    getHeadInFlightId?: () => string | undefined;
 };
-type XAPIExitTransport = (statement: XAPIStatement) => void;
+type XAPIExitTransport = (statement: XAPIStatement) => void | Promise<void>;
 type XAPIClient = {
     send: (statement: XAPIStatement) => void;
     flush: () => Promise<void>;
@@ -65,24 +67,54 @@ type InMemoryXAPIQueueOptions = {
     onDepth?: (size: number) => void;
     /** Called when an oldest statement is dropped because the queue is at maxSize. */
     onCap?: () => void;
+    /** Called when a statement cannot be enqueued because the queue is full and the head is in-flight. */
+    onOverflow?: (statement: XAPIStatement) => void;
+    /** Failures at queue head before skipping (default 10). */
+    maxHeadFailures?: number;
+    /** Called when the queue head is skipped after repeated transport failures. */
+    onHeadSkipped?: (statement: XAPIStatement, err: unknown) => void;
 };
 declare function createInMemoryXAPIQueue(opts?: InMemoryXAPIQueueOptions): XAPIQueue;
 
+/**
+ * Imperative xAPI client with in-memory queue, retry flush, and optional pagehide delivery.
+ * Prefer wiring transport via `LessonkitProvider` config from `@lessonkit/react` in React apps.
+ */
 declare function createXAPIClient(opts?: {
     transport?: XAPITransport;
     /** Keepalive transport for pagehide flush (e.g. from createFetchTransport). */
     exitTransport?: XAPIExitTransport;
+    /** Abort in-flight transport by statement id (e.g. from createFetchTransport). */
+    abortInFlight?: (statementId: string) => void;
     courseId?: CourseId;
     queue?: XAPIQueue;
     /** When creating the default in-memory queue (max size 1000 unless overridden). */
     maxQueueSize?: number;
+    /** Consecutive head failures before skip (default queue only). */
+    maxHeadFailures?: number;
     onQueueDepth?: (size: number) => void;
     onQueueCap?: () => void;
+    onHeadSkipped?: (statement: XAPIStatement, err: unknown) => void;
+    /** Called when transport fails after retries (statement is re-queued). */
+    onTransportError?: (err: unknown) => void;
+    /** Called when telemetry → xAPI mapping fails. */
+    onMappingError?: (err: unknown) => void;
 }): XAPIClient;
+/** @internal Reset dead-letter storage between tests. */
+declare function resetXAPIDeadLetterForTests(): void;
+
+type AssertSafeLrsUrlOptions = {
+    /** Allow loopback, RFC1918, link-local, and metadata IPs (default false). */
+    allowPrivateHosts?: boolean;
+};
+/** Validate an LRS or analytics proxy URL before browser fetch transport use. */
+declare function assertSafeLrsUrl(url: string, opts?: AssertSafeLrsUrlOptions): void;
 
 type CreateFetchTransportOptions = {
     /** LRS or proxy endpoint (POST). */
     url: string;
+    /** Allow loopback and private-network hosts (default false). */
+    allowPrivateHosts?: boolean;
     /** Per-request timeout (default 30_000 ms). Uses AbortSignal.timeout when available. */
     timeoutMs?: number;
     /** Static headers merged into each request (e.g. Authorization from a short-lived token). */
@@ -100,7 +132,17 @@ type FetchTransportBundle = {
     transport: XAPITransport;
     /** Best-effort synchronous delivery for pagehide (keepalive fetch). */
     exitTransport: (statement: XAPIStatement) => void;
+    /** Abort an in-flight transport request by statement id (used on pagehide). */
+    abortInFlight: (statementId: string) => void;
 };
+/** HTTP error from fetch transport with status for retry policy. */
+declare class FetchHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, statusText: string, kind?: "xapi" | "batch");
+}
+/** Retry 429 and 5xx; do not retry other 4xx (auth/config errors). */
+declare function isRetryableFetchHttpStatus(status: number): boolean;
+declare function isRetryableFetchError(err: unknown): boolean;
 /**
  * Creates an xAPI transport backed by fetch with timeout, retry backoff, and a
  * keepalive exit transport for pagehide delivery.
@@ -117,10 +159,13 @@ type FetchBatchSinkBundle = {
  */
 declare function createFetchBatchSink(opts: CreateFetchBatchSinkOptions): FetchBatchSinkBundle;
 
+declare function loadDeadLetterStatements(): XAPIStatement[];
+declare function persistDeadLetterStatement(statement: XAPIStatement): void;
+
 /**
  * Map a LessonKit telemetry event to an xAPI statement, or null if the event should not emit xAPI.
  * `lesson_time_on_task` returns null (companion metric; lesson_completed carries duration).
  */
 declare function telemetryEventToXAPIStatement(event: TelemetryEvent): XAPIStatement | null;
 
-export { type CreateFetchBatchSinkOptions, type CreateFetchTransportOptions, type FetchBatchSinkBundle, type FetchTransportBundle, type InMemoryXAPIQueueOptions, type XAPIClient, type XAPIExitTransport, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, createFetchBatchSink, createFetchTransport, createInMemoryXAPIQueue, createXAPIClient, telemetryEventToXAPIStatement };
+export { type AssertSafeLrsUrlOptions, type CreateFetchBatchSinkOptions, type CreateFetchTransportOptions, type FetchBatchSinkBundle, FetchHttpError, type FetchTransportBundle, type InMemoryXAPIQueueOptions, type XAPIClient, type XAPIExitTransport, type XAPIObjectDefinition, type XAPIQueue, type XAPIResult, type XAPIScore, type XAPIStatement, type XAPITransport, type XAPIVerbIri, assertSafeLrsUrl, createFetchBatchSink, createFetchTransport, createInMemoryXAPIQueue, createXAPIClient, isRetryableFetchError, isRetryableFetchHttpStatus, loadDeadLetterStatements, persistDeadLetterStatement, resetXAPIDeadLetterForTests, telemetryEventToXAPIStatement };