@timeback/caliper 0.2.0 → 0.2.1-beta.20260331190459

package/dist/index.d.ts

@@ -1,741 +1,1521 @@
-import * as _timeback_internal_client_infra from '@timeback/internal-client-infra';
-import { ClientConfig, TransportOnlyConfig, CaliperPaths, RequestOptions, PaginatedResponse, ProviderClientConfig, BaseTransportConfig, BaseTransport, Paginator as Paginator$1, ListParams, ProviderRegistry, TimebackProvider, AuthCheckResult } from '@timeback/internal-client-infra';
-export { AuthCheckResult, EnvAuth, Environment, ExplicitAuth } from '@timeback/internal-client-infra';
+import { CaliperEnvelope, ActivityCompletedEvent, AssessmentItemEvent, QuestionGradeEvent, TimeSpentEvent, CaliperEvent, SendEventsResult, ValidationResult, ListEventsResult, StoredEvent, JobStatus, WaitForCompletionOptions } from '@timeback/types/protocols/caliper';
+export { ActivityCompletedEvent, ActivityMetricType, AssessmentItemEvent, CaliperEnvelope, CaliperEvent, CaliperProfile, JobStatus, QuestionGradeEvent, SendEventsResult, StoredEvent, TimeSpentEvent, TimeSpentMetric, TimeSpentMetricType, TimebackActivity, TimebackActivityContext, TimebackActivityMetric, TimebackActivityMetricsCollection, TimebackApp, TimebackCourse, TimebackEvent, TimebackSubject, TimebackTimeSpentMetricsCollection, TimebackUser, TimebackUserRole, ValidationResult } from '@timeback/types/protocols/caliper';
+import { ActivityCompletedInput, QuestionAnsweredInput, QuestionGradedInput, QuestionSeenInput, TimeSpentInput, CaliperListEventsParams } from '@timeback/types/zod';
+export { ActivityCompletedInput, CaliperListEventsParams as ListEventsParams, QuestionAnsweredInput, QuestionGradedInput, QuestionSeenInput, TimeSpentInput } from '@timeback/types/zod';
 
 /**
- * Timeback Shared Primitives
+ * Interface for obtaining OAuth2 access tokens.
  *
- * Core types used across multiple Timeback protocols.
- *
- * Organization:
- * - Shared types (this file): Used by multiple protocols (Caliper, OneRoster, etc.)
- * - Protocol-specific types: Live in their respective protocols/X/primitives.ts files
- *
- * What belongs here:
- * - TimebackSubject - Used in OneRoster courses AND Caliper events
- * - TimebackGrade - Used across OneRoster, Caliper, and QTI
- * - IMSErrorResponse - IMS Global standard used by multiple 1EdTech protocols
- *
- * What doesn't belong here:
- * - OneRoster-specific: protocols/oneroster/primitives.ts
- * - QTI-specific: protocols/qti/primitives.ts
+ * Implementations handle token caching and refresh automatically.
  */
-
-// ─────────────────────────────────────────────────────────────────────────────
-// TIMEBACK SHARED TYPES
-// ─────────────────────────────────────────────────────────────────────────────
+interface TokenProvider {
+    /**
+     * Get a valid access token.
+     *
+     * Returns a cached token if still valid, otherwise fetches a new one.
+     *
+     * @returns A valid access token string
+     * @throws {Error} If token acquisition fails
+     */
+    getToken(): Promise<string>;
+    /**
+     * Invalidate the cached token.
+     *
+     * Forces the next getToken() call to fetch a fresh token.
+     * Should be called when a request fails with 401 Unauthorized.
+     *
+     * Optional - not all implementations may support invalidation.
+     */
+    invalidate?(): void;
+}
 
 /**
- * Valid Timeback subject values.
- * Used in OneRoster courses and Caliper events.
- */
-type TimebackSubject =
-	| 'Reading'
-	| 'Language'
-	| 'Vocabulary'
-	| 'Social Studies'
-	| 'Writing'
-	| 'Science'
-	| 'FastMath'
-	| 'Math'
-	| 'None'
-	| 'Other'
+ * All supported platforms.
+ */
+declare const PLATFORMS: readonly ["BEYOND_AI", "LEARNWITH_AI"];
 
 /**
- * Timeback Profile Types
+ * Type Definitions for `@timeback/internal-logger`
  *
- * First-class types for the Timeback Caliper profile, including
- * ActivityCompletedEvent and TimeSpentEvent.
+ * Central type definitions used across all logger components.
+ * These types define the contract between the logger, formatters, and consumers.
  */
-
-
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// TIMEBACK ACTIVITY CONTEXT
-// ═══════════════════════════════════════════════════════════════════════════════
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// TIMEBACK USER
-// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Log severity levels, ordered from least to most severe.
+ *
+ * - debug: Detailed diagnostic information for developers
+ * - info: General operational messages (app started, request received)
+ * - warn: Something unexpected but not breaking (deprecated API used)
+ * - error: Something failed (request failed, database connection lost)
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Runtime environments that determine how logs are formatted.
+ *
+ * - terminal: Local development with colors and icons
+ * - ci: CI/CD pipelines with plain text (no ANSI codes)
+ * - production: JSON lines for log aggregation (DataDog, CloudWatch, etc.)
+ * - browser: Browser console with CSS styling
+ * - test: Test environment with no output
+ */
+type Environment$2 = 'terminal' | 'ci' | 'production' | 'browser' | 'test';
+/**
+ * Arbitrary key-value data attached to log entries.
+ *
+ * Context is merged into log output - in production it becomes top-level
+ * JSON fields, in terminal it's displayed as key=value pairs.
+ *
+ * @example
+ * log.info('User created', { userId: 123, email: 'foo@bar.com' })
+ */
+type LogContext = Record<string, unknown>;
+/**
+ * Configuration options for creating a logger instance.
+ */
+interface LoggerOptions {
+    /**
+     * Logger scope/namespace for categorizing logs.
+     * Child loggers append to this with colons: "api" → "api:users"
+     */
+    scope?: string;
+    /**
+     * Minimum log level to output.
+     * Logs below this level are silently ignored.
+     * @default 'info' (or 'debug' if DEBUG env var is set)
+     */
+    minLevel?: LogLevel;
+    /**
+     * Override automatic environment detection.
+     * Useful for testing or forcing a specific format.
+     */
+    environment?: Environment$2;
+    /**
+     * Default context added to every log entry from this logger.
+     * Useful for request IDs, user IDs, etc.
+     */
+    defaultContext?: LogContext;
+}
 
 /**
- * User role in the Timeback platform.
+ * Logger instance with environment-aware formatting.
+ *
+ * Instances are lightweight and can be created freely.
+ * Common pattern: one logger per module/component.
  */
-type TimebackUserRole = 'student' | 'teacher' | 'admin' | 'guide'
+declare class Logger {
+    /** Namespace for this logger (e.g., "api", "api:users") */
+    private scope?;
+    /** Minimum level to output (logs below this are ignored) */
+    private minLevel;
+    /** The detected or configured environment */
+    private environment;
+    /** Function that formats and outputs log entries */
+    private formatter;
+    /** Context added to every log entry from this logger */
+    private defaultContext;
+    /**
+     * Create a new Logger instance.
+     *
+     * Usually you'd use createLogger() instead of new Logger().
+     */
+    constructor(options?: LoggerOptions);
+    /**
+     * Create a child logger with an additional scope segment.
+     *
+     * Child loggers inherit minLevel and defaultContext from parent.
+     * Scope is appended with a colon separator.
+     *
+     * @param scope - Additional scope segment to append
+     * @returns New Logger instance with extended scope
+     *
+     * @example
+     * const api = createLogger({ scope: 'api' })
+     * const users = api.child('users')
+     * users.info('Created') // scope: "api:users"
+     */
+    child(scope: string): Logger;
+    /**
+     * Create a logger with additional default context.
+     *
+     * The new context is merged with existing default context.
+     * Useful for adding request IDs, user IDs, etc.
+     *
+     * @param context - Additional context to include in all logs
+     * @returns New Logger instance with extended context
+     *
+     * @example
+     * const requestLog = log.withContext({ requestId: 'abc123' })
+     * requestLog.info('Processing') // requestId included automatically
+     */
+    withContext(context: LogContext): Logger;
+    /**
+     * Log a debug message.
+     *
+     * Use for detailed diagnostic information useful during development.
+     * These are typically filtered out in production.
+     *
+     * @param message - The log message
+     * @param context - Optional key-value context to include with the log
+     */
+    debug(message: string, context?: LogContext): void;
+    /**
+     * Log an info message.
+     *
+     * Use for general operational information.
+     * Examples: server started, request received, job completed.
+     *
+     * @param message - The log message
+     * @param context - Optional key-value context to include with the log
+     */
+    info(message: string, context?: LogContext): void;
+    /**
+     * Log a warning message.
+     *
+     * Use for unexpected but non-breaking issues.
+     * Examples: deprecated API used, retrying operation, approaching limit.
+     *
+     * @param message - The log message
+     * @param context - Optional key-value context to include with the log
+     */
+    warn(message: string, context?: LogContext): void;
+    /**
+     * Log an error message.
+     *
+     * Use for failures that need attention.
+     * Examples: request failed, database error, unhandled exception.
+     *
+     * @param message - The log message
+     * @param context - Optional key-value context to include with the log
+     */
+    error(message: string, context?: LogContext): void;
+    /**
+     * Internal method that builds the log entry and passes it to the formatter.
+     *
+     * All public log methods (debug, info, warn, error) delegate here.
+     *
+     * @param level - The log level
+     * @param message - The log message
+     * @param context - Optional key-value context to include with the log
+     */
+    private log;
+}
 
 /**
- * Timeback user entity.
+ * Where Clause Types
  *
- * Represents a user in the Timeback platform. The `id` should ideally be
- * the OneRoster URL for the user when available.
+ * Type-safe object syntax for building filter expressions.
+ */
+/**
+ * Primitive value types that can be used in filters.
+ */
+type FilterValue = string | number | boolean | Date;
+/**
+ * Operators for a single field.
  *
  * @example
  * ```typescript
- * const user: TimebackUser = {
- *   id: 'https://api.alpha-1edtech.ai/ims/oneroster/rostering/v1p2/users/123',
- *   type: 'TimebackUser',
- *   email: 'student@example.edu',
- *   name: 'Jane Doe',
- *   role: 'student',
- * }
+ * { status: { ne: 'deleted' } }
+ * { score: { gt: 90 } }
+ * { email: { contains: '@school.edu' } }
+ * { role: { in: ['teacher', 'aide'] } }
  * ```
  */
-interface TimebackUser {
-	/** User identifier (IRI format, preferably OneRoster URL) */
-	id: string
-	/** Must be 'TimebackUser' */
-	type: 'TimebackUser'
-	/** User email address */
-	email: string
-	/** User display name */
-	name?: string
-	/** User role */
-	role?: TimebackUserRole
-	/** Additional custom attributes */
-	extensions?: Record<string, unknown>
-	/** Index signature for Caliper compatibility */
-	[key: string]: unknown
+interface FieldOperators<T> {
+    /** Not equal */
+    ne?: T;
+    /** Greater than */
+    gt?: T;
+    /** Greater than or equal */
+    gte?: T;
+    /** Less than */
+    lt?: T;
+    /** Less than or equal */
+    lte?: T;
+    /** Contains substring (strings only) */
+    contains?: T extends string ? string : never;
+    /** Match any of the values */
+    in?: T[];
+    /** Match none of the values */
+    notIn?: T[];
 }
-
 /**
- * Application reference within activity context.
+ * A field condition can be:
+ * - A direct value (implies equality)
+ * - An object with operators
  */
-interface TimebackApp {
-	/** Application identifier (IRI format) */
-	id?: string
-	/** Application name */
-	name: string
-	/** Additional custom attributes */
-	extensions?: Record<string, unknown>
+type FieldCondition<T> = T | FieldOperators<T>;
+/**
+ * Map filter field types to field conditions.
+ *
+ * Each field in F becomes an optional filter condition.
+ *
+ * @typeParam F - Filter fields type (e.g., UserFilterFields)
+ */
+type FilterFields<F> = {
+    [K in keyof F]?: FieldCondition<F[K] & FilterValue>;
+};
+/**
+ * OR condition for combining multiple field conditions.
+ */
+interface OrCondition<F> {
+    OR: WhereClause<F>[];
 }
+/**
+ * A where clause for filtering entities.
+ *
+ * The type parameter F should be a filter fields type that defines
+ * the available fields and their value types for filtering.
+ *
+ * Multiple fields at the same level are combined with AND.
+ * Use `OR` for explicit OR logic.
+ *
+ * @typeParam F - Filter fields type (e.g., UserFilterFields)
+ *
+ * @example
+     * ```typescript
+     * // Simple equality (implicit AND)
+     * { status: 'active', role: 'teacher' }
+ * // → status='active' AND role='teacher'
+ * ```
+ *
+ * @example
+     * ```typescript
+     * // With operators
+     * { status: { ne: 'deleted' }, score: { gte: 90 } }
+ * // → status!='deleted' AND score>=90
+ * ```
+ *
+ * @example
+     * ```typescript
+     * // OR condition
+     * { OR: [{ role: 'teacher' }, { role: 'aide' }] }
+ * // → role='teacher' OR role='aide'
+ * ```
+ *
+ * @example
+     * ```typescript
+     * // Match multiple values
+     * { role: { in: ['teacher', 'aide'] } }
+ * // → role='teacher' OR role='aide'
+ * ```
+ */
+type WhereClause<F> = FilterFields<F> | OrCondition<F>;
 
 /**
- * Course reference within activity context.
+ * Shared Types
+ *
+ * Common types for API client infrastructure.
  */
-interface TimebackCourse {
-	/** Course identifier (IRI format, preferably OneRoster URL) */
-	id?: string
-	/** Course name */
-	name?: string
-	/** Additional custom attributes */
-	extensions?: Record<string, unknown>
-}
 
 /**
- * Activity reference within activity context.
+ * Fetch function signature for HTTP requests.
+ * Avoids Bun-specific extensions on `typeof fetch`.
+ */
+type FetchFn$1 = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/**
+ * Supported Timeback platform implementations.
+ */
+type Platform$1 = (typeof PLATFORMS)[number];
+/**
+ * Supported deployment environments.
+ */
+type Environment$1 = 'staging' | 'production';
+/**
+ * Auth credentials for environment mode.
+ * Token URL is derived automatically from environment.
  */
-interface TimebackActivity {
-	/** Activity identifier (IRI format) */
-	id?: string
-	/** Activity name */
-	name: string
-	/** Additional custom attributes */
-	extensions?: Record<string, unknown>
+interface EnvAuth$1 {
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * Auth credentials for explicit mode.
+ * Includes authUrl for custom APIs.
+ * @deprecated Use separate authUrl and ProviderAuth fields instead
+ */
+interface ExplicitAuth$1 {
+    clientId: string;
+    clientSecret: string;
+    authUrl: string;
+}
+/**
+ * Base configuration options shared by all modes.
+ */
+interface BaseConfig$1 {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Custom fetch implementation */
+    fetch?: FetchFn$1;
+}
+/**
+ * Environment-based configuration for Timeback APIs.
+ */
+interface EnvConfig extends BaseConfig$1 {
+    /** Timeback platform implementation (defaults to 'BEYOND_AI') */
+    platform?: Platform$1;
+    /** Target environment - determines base URL and token URL */
+    env: Environment$1;
+    /** OAuth2 client credentials */
+    auth: EnvAuth$1;
+}
+/**
+ * Environment-based configuration with shared token provider.
+ */
+interface TokenProviderEnvConfig extends BaseConfig$1 {
+    /** Timeback platform implementation (defaults to 'BEYOND_AI') */
+    platform?: Platform$1;
+    /** Target environment - determines base URL */
+    env: Environment$1;
+    /** Shared token provider (from @timeback/auth) */
+    tokenProvider: TokenProvider;
+}
+/**
+ * Explicit URL configuration for custom APIs.
+ * Supports both authenticated and public/no-auth services.
+ */
+interface ExplicitConfig extends BaseConfig$1 {
+    /** API base URL */
+    baseUrl: string;
+    /**
+     * OAuth2 token URL. Omit for public/no-auth services.
+     * Can also be provided via auth.authUrl (legacy format).
+     */
+    authUrl?: string;
+    /**
+     * OAuth2 credentials. Required if authUrl is provided.
+     * Supports both ExplicitAuth (with authUrl) and ProviderAuth (without).
+     */
+    auth?: ExplicitAuth$1 | ProviderAuth;
+    /**
+     * Use a built-in path profile by name.
+     * Defaults to 'BEYOND_AI' if neither pathProfile nor paths is specified.
+     */
+    pathProfile?: Platform$1;
+    /** Custom path overrides (takes precedence over pathProfile) */
+    paths?: Partial<PlatformPaths>;
+    /** Not applicable to explicit config — use `EnvConfig` instead */
+    env?: never;
 }
-
 /**
- * Timeback activity context.
+ * Use pre-configured transport.
+ */
+interface TransportConfig extends BaseConfig$1 {
+    /** Transport configuration */
+    transport: TransportLike;
+}
+/**
+ * HTTP request options.
+ */
+interface RequestOptions$1 {
+    /** HTTP method */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Query parameters to append to the URL */
+    params?: Record<string, string | number | boolean | undefined>;
+    /** Request body (will be JSON-serialized) */
+    body?: unknown;
+    /** Additional headers to include */
+    headers?: Record<string, string>;
+    /**
+     * Unique identifier for this request.
+     * Used for log correlation and debugging.
+     * Auto-generated if not provided.
+     */
+    requestId?: string;
+}
+/**
+ * Duck-typed transport interface for testing and advanced use.
+ */
+interface TransportLike {
+    /** Base URL of the API */
+    baseUrl: string;
+    /** Make an authenticated request */
+    request<T>(path: string, options?: RequestOptions$1): Promise<T>;
+}
+/**
+ * Configuration using a pre-configured transport.
+ *
+ * For advanced use cases like sharing a transport between clients
+ * or using a custom transport implementation.
  *
- * Represents the context where an event was recorded, including
- * subject, application, course, and activity information.
+ * @template T - Transport type (defaults to TransportLike, clients should specify their full transport type)
+ */
+interface TransportOnlyConfig<T extends TransportLike = TransportLike> {
+    /** Existing transport instance */
+    transport: T;
+}
+/**
+ * Union of all client configuration types.
+ */
+type ClientConfig = EnvConfig | TokenProviderEnvConfig | ExplicitConfig | TransportConfig | Partial<ExplicitConfig>;
+/**
+ * Parameters for listing resources with pagination, sorting, and filtering.
+ *
+ * Common across all Timeback APIs (OneRoster, Edubridge, QTI, etc.).
+ *
+ * @typeParam T - Entity type for type-safe `where` clause (defaults to unknown)
  *
  * @example
  * ```typescript
- * const context: TimebackActivityContext = {
- *   id: 'https://myapp.example.com/activities/123',
- *   type: 'TimebackActivityContext',
- *   subject: 'Math',
- *   app: { name: 'My Learning App' },
- *   course: { name: 'Algebra 101' },
- *   activity: { name: 'Chapter 1 Quiz' },
- * }
+ * // Type-safe where
+ * client.users.list({
+ *   where: { status: 'active', role: 'teacher' },
+ *   sort: 'familyName',
+ * })
  * ```
  */
-interface TimebackActivityContext {
-	/** Context identifier (IRI format) */
-	id: string
-	/** Must be 'TimebackActivityContext' */
-	type: 'TimebackActivityContext'
-	/** Subject area */
-	subject: TimebackSubject
-	/** Application where event was recorded */
-	app: TimebackApp
-	/** Course where event was recorded */
-	course: TimebackCourse
-	/** Activity where event was recorded */
-	activity?: TimebackActivity
-	/** Whether to process this event */
-	process?: boolean
-	/** Index signature for Caliper compatibility */
-	[key: string]: unknown
+interface ListParams<T = unknown> {
+    /**
+     * Maximum items per page.
+     * @default 100
+     */
+    limit?: number;
+    /**
+     * Number of items to skip (for pagination).
+     * @default 0
+     */
+    offset?: number;
+    /**
+     * Field name to sort results by.
+     *
+     * Type-safe: only valid field names for this resource are accepted.
+     *
+     * @example
+     * ```typescript
+     * sort: 'familyName'
+     * ```
+     */
+    sort?: keyof T & string;
+    /**
+     * Sort direction.
+     * @default "asc"
+     */
+    orderBy?: 'asc' | 'desc';
+    /**
+     * Type-safe filter using object syntax.
+     *
+     * Multiple fields are combined with AND. Use `OR` for OR logic.
+     *
+     * @example
+     * ```typescript
+     * // Simple equality
+     * where: { status: 'active' }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Multiple fields (AND)
+     * where: { status: 'active', role: 'teacher' }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With operators
+     * where: { score: { gte: 90 }, status: { ne: 'deleted' } }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // OR condition
+     * where: { role: { in: ['teacher', 'aide'] } }
+     * ```
+     */
+    where?: WhereClause<T>;
+    /**
+     * Fields to include in the response.
+     * Reduces payload size by requesting only needed fields.
+     * @example ['sourcedId', 'givenName', 'familyName']
+     */
+    fields?: string[];
+    /**
+     * Free-text search across multiple fields (proprietary extension).
+     * For users: searches givenName, familyName, email.
+     * @example "john@example.com"
+     */
+    search?: string;
+    /**
+     * Maximum total items to return across all pages.
+     *
+     * Unlike `limit` (which sets page size), `max` caps the total number
+     * of items yielded by the paginator. Pagination stops once this many
+     * items have been returned.
+     *
+     * @example
+     * ```typescript
+     * // Get at most 50 users total
+     * client.users.list({ max: 50 })
+     * ```
+     */
+    max?: number;
+}
+/**
+ * Response from a paginated API request.
+ */
+interface PaginatedResponse<T> {
+    /** Array of items in this page */
+    data: T[];
+    /** Whether more pages are available */
+    hasMore: boolean;
+    /** Total count of items (if provided by server) */
+    total?: number;
 }
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// ACTIVITY METRICS
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
- * Types of activity metrics.
+ * Result of fetching a single page of resources.
+ *
+ * @typeParam T - The type of items in the page
+ */
+interface PageResult<T> {
+    /** Array of items in this page */
+    data: T[];
+    /** Whether more pages are available */
+    hasMore: boolean;
+    /** Total count of items (if provided by server) */
+    total?: number;
+    /** Offset to use for fetching the next page */
+    nextOffset?: number;
+}
+/**
+ * Options for toArray() method.
+ */
+interface ToArrayOptions {
+    /**
+     * Maximum number of items to collect.
+     *
+     * Throws an error if this limit is exceeded, preventing OOM on large datasets.
+     * Use `for await...of` to stream results instead.
+     *
+     * @default 10_000
+     * @example Set to Infinity to disable (use with caution!)
+     */
+    maxItems?: number;
+}
+/**
+ * Function that fetches a page of results.
+ * Provided by the transport layer.
+ */
+type PageFetcher<T> = (path: string, options: {
+    params: Record<string, string | number | boolean | undefined>;
+}) => Promise<PaginatedResponse<T>>;
+/**
+ * Pagination style for API requests.
+ *
+ * - `'offset'`: Uses limit/offset parameters (default, e.g., OneRoster)
+ * - `'page'`: Uses limit/page parameters (1-indexed, e.g., QTI)
  */
-type ActivityMetricType =
-	| 'xpEarned'
-	| 'totalQuestions'
-	| 'correctQuestions'
-	| 'masteredUnits'
+type PaginationStyle = 'offset' | 'page';
+/**
+ * Options for creating a Paginator.
+ */
+interface PaginatorOptions<T, F = unknown> {
+    /** Function to fetch a page of results */
+    fetcher: PageFetcher<T>;
+    /** API endpoint path */
+    path: string;
+    /** List parameters (filter, sort, limit, offset) */
+    params?: ListParams<F>;
+    /** Maximum total items to return across all pages (client-side cap) */
+    max?: number;
+    /** Response key containing the items array (e.g., "users") */
+    unwrapKey?: string;
+    /** Logger instance (defaults to client-common logger) */
+    logger?: Logger;
+    /** Optional transform function applied to each item before yielding */
+    transform?: (item: T) => T;
+    /**
+     * Pagination style to use for API requests.
+     *
+     * - `'offset'` (default): Sends `limit` and `offset` params
+     * - `'page'`: Sends `limit` and `page` params (1-indexed)
+     *
+     * @default 'offset'
+     */
+    paginationStyle?: PaginationStyle;
+}
+/**
+ * Result of an auth check operation.
+ */
+interface AuthCheckResult$1 {
+    /** Whether auth succeeded */
+    ok: boolean;
+    /** Time taken to complete the check (ms) */
+    latencyMs: number;
+    /** Error message if failed */
+    error?: string;
+    /** Detailed check results */
+    checks: {
+        /** Token acquisition succeeded */
+        tokenAcquisition: boolean;
+    };
+}
 
 /**
- * Individual activity metric.
+ * Config Types
  *
- * @example
- * ```typescript
- * const metric: TimebackActivityMetric = {
- *   type: 'correctQuestions',
- *   value: 8,
- * }
- * ```
+ * Types for TimebackProvider and provider resolution.
+ */
+
+/**
+ * Caliper API path profile.
+ * Defines paths for Caliper operations. Use `null` for unsupported operations.
+ */
+interface CaliperPaths {
+    /** Path for sending events (POST) */
+    send: string;
+    /** Path for validating events (POST), null if not supported */
+    validate: string | null;
+    /** Path for listing events (GET), null if not supported */
+    list: string | null;
+    /** Path template for getting single event (GET), use {id} placeholder */
+    get: string | null;
+    /** Path template for job status (GET), use {id} placeholder */
+    jobStatus: string | null;
+}
+/**
+ * Webhook API path profile.
+ * Defines paths for webhook management operations.
+ * Nullability is at the platform level (`webhooks: WebhookPaths | null` in PlatformPaths).
+ */
+interface WebhookPaths {
+    /** Path for listing webhooks (GET) */
+    webhookList: string;
+    /** Path template for getting a single webhook (GET), use {id} placeholder */
+    webhookGet: string;
+    /** Path for creating a webhook (POST) */
+    webhookCreate: string;
+    /** Path template for updating a webhook (PUT), use {id} placeholder */
+    webhookUpdate: string;
+    /** Path template for deleting a webhook (DELETE), use {id} placeholder */
+    webhookDelete: string;
+    /** Path template for activating a webhook (PUT), use {id} placeholder */
+    webhookActivate: string;
+    /** Path template for deactivating a webhook (PUT), use {id} placeholder */
+    webhookDeactivate: string;
+    /** Path for listing all webhook filters (GET) */
+    webhookFilterList: string;
+    /** Path template for getting a single webhook filter (GET), use {id} placeholder */
+    webhookFilterGet: string;
+    /** Path for creating a webhook filter (POST) */
+    webhookFilterCreate: string;
+    /** Path template for updating a webhook filter (PUT), use {id} placeholder */
+    webhookFilterUpdate: string;
+    /** Path template for deleting a webhook filter (DELETE), use {id} placeholder */
+    webhookFilterDelete: string;
+    /** Path template for listing filters by webhook (GET), use {webhookId} placeholder */
+    webhookFiltersByWebhook: string;
+}
+/**
+ * Reporting API path profile.
+ * Defines paths for reporting MCP and REST operations.
+ * Nullability is at the platform level (`reporting: ReportingPaths | null` in PlatformPaths).
+ */
+interface ReportingPaths {
+    /** Path for the reporting MCP JSON-RPC endpoint (POST) */
+    mcp: string;
+    /** Path template for executing a saved query (GET), use {id} placeholder */
+    savedQueryExecute: string;
+    /** Path template for checking reporting group membership (GET), use {email} placeholder */
+    adminGroupCheck: string;
+    /** Path template for adding a user to the reporting group (POST), use {email} placeholder */
+    adminGroupAdd: string;
+    /** Path template for removing a user from the reporting group (DELETE), use {email} placeholder */
+    adminGroupRemove: string;
+}
+/**
+ * OneRoster API path profile.
+ * Defines the base path prefix for all OneRoster resources.
+ */
+interface OneRosterPaths {
+    /** Base path prefix for rostering resources (users, schools, classes, etc.) */
+    rostering: string;
+    /** Base path prefix for gradebook resources (lineItems, results, etc.) */
+    gradebook: string;
+    /** Base path prefix for resources API (digital learning resources) */
+    resources: string;
+}
+/**
+ * Edubridge API path profile.
+ * Defines path prefixes for Edubridge operations.
+ */
+interface EdubridgePaths {
+    /** Base path prefix for all Edubridge resources */
+    base: string;
+}
+/**
+ * PowerPath API path profile.
+ * Defines path prefixes for PowerPath operations.
+ */
+interface PowerPathPaths {
+    /** Base path prefix for all PowerPath resources */
+    base: string;
+}
+/**
+ * CASE API path profile.
+ * Defines path prefix for CASE (Competency and Academic Standards Exchange) operations.
+ */
+interface CasePaths {
+    /** Base path prefix for all CASE resources */
+    base: string;
+}
+/**
+ * CLR API path profile.
+ * Defines path prefixes for CLR (Comprehensive Learner Record) operations.
+ */
+interface ClrPaths {
+    /** Path for upserting CLR credentials (POST) */
+    credentials: string;
+    /** Path for API discovery (GET) */
+    discovery: string;
+}
+/**
+ * Platform path profiles for all services.
+ * Use `null` to indicate a service is not supported on the platform.
+ */
+interface PlatformPaths {
+    caliper: CaliperPaths;
+    oneroster: OneRosterPaths;
+    webhooks: WebhookPaths | null;
+    reporting: ReportingPaths | null;
+    edubridge: EdubridgePaths | null;
+    powerpath: PowerPathPaths | null;
+    clr: ClrPaths | null;
+    case: CasePaths | null;
+}
+/**
+ * Services that have path configuration.
+ * Subset of ServiceName - excludes services without path profiles (e.g., 'qti').
+ */
+type PathEnabledService = keyof PlatformPaths;
+/**
+ * Supported Timeback platform implementations.
+ */
+type Platform = (typeof PLATFORMS)[number];
+/**
+ * Supported deployment environments.
+ */
+type Environment = 'staging' | 'production';
+/**
+ * Supported service names.
+ */
+type ServiceName = 'oneroster' | 'caliper' | 'webhooks' | 'reporting' | 'edubridge' | 'qti' | 'powerpath' | 'clr' | 'case';
+/**
+ * Resolved endpoint for a single service.
+ */
+interface ResolvedEndpoint {
+    /** Base URL for the service API */
+    baseUrl: string;
+    /** OAuth2 token URL for this endpoint. Undefined for public/no-auth services. */
+    authUrl?: string;
+}
+/**
+ * Auth credentials for a provider.
+ */
+interface ProviderAuth {
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * Configuration for environment-based provider.
+ * Uses known Timeback platform endpoints.
+ */
+interface ProviderEnvConfig {
+    /** Timeback platform (defaults to 'BEYOND_AI') */
+    platform?: Platform;
+    /** Target environment */
+    env: Environment;
+    /** OAuth2 credentials */
+    auth: ProviderAuth;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Configuration for explicit URL provider.
+ * Single base URL for all services.
+ */
+interface ProviderExplicitConfig {
+    /** Base URL for all services */
+    baseUrl: string;
+    /** OAuth2 token URL. Omit for public/no-auth services. */
+    authUrl?: string;
+    /** OAuth2 credentials. Required if authUrl is provided. */
+    auth?: ProviderAuth;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /**
+     * Use a built-in path profile by name.
+     * Defaults to 'BEYOND_AI' if neither pathProfile nor paths is specified.
+     */
+    pathProfile?: Platform;
+    /** Custom path overrides (takes precedence over pathProfile) */
+    paths?: Partial<PlatformPaths>;
+}
+/**
+ * Configuration for multi-service provider.
+ * Different URLs for different services.
+ */
+interface ProviderServicesConfig {
+    /** Per-service base URLs */
+    services: Partial<Record<ServiceName, string>>;
+    /** OAuth2 token URL. Omit for public/no-auth services. */
+    authUrl?: string;
+    /** OAuth2 credentials. Required if authUrl is provided. */
+    auth?: ProviderAuth;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /**
+     * Use a built-in path profile by name.
+     * Defaults to 'BEYOND_AI' if neither pathProfile nor paths is specified.
+     */
+    pathProfile?: Platform;
+    /** Custom path overrides (takes precedence over pathProfile) */
+    paths?: Partial<PlatformPaths>;
+}
+/**
+ * Union of all provider configuration types.
+ */
+type TimebackProviderConfig = ProviderEnvConfig | ProviderExplicitConfig | ProviderServicesConfig;
+/**
+ * Provider template - endpoints without auth.
+ * Used internally to define available platform+env combinations.
  */
-interface TimebackActivityMetric {
-	/** Metric type */
-	type: ActivityMetricType
-	/** Metric value */
-	value: number
-	/** Additional custom attributes */
-	extensions?: Record<string, unknown>
+interface ProviderTemplate {
+    platform: Platform;
+    env: Environment;
 }
-
 /**
- * Collection of activity metrics.
+ * Registry of provider templates indexed by platform and environment.
+ *
+ * Use `satisfies ProviderRegistry` when defining a registry for type checking.
  *
  * @example
- * ```typescript
- * const metrics: TimebackActivityMetricsCollection = {
- *   id: 'https://myapp.example.com/metrics/123',
- *   type: 'TimebackActivityMetricsCollection',
- *   attempt: 1,
- *   items: [
- *     { type: 'totalQuestions', value: 10 },
- *     { type: 'correctQuestions', value: 8 },
- *     { type: 'xpEarned', value: 150 },
- *   ],
- *   extensions: { pctCompleteApp: 67 },
- * }
- * ```
+ * const myRegistry = {
+ *   defaultPlatform: 'MY_PLATFORM',
+ *   templates: {
+ *     MY_PLATFORM: {
+ *       staging: { platform: 'BEYOND_AI', env: 'staging' },
+ *       production: { platform: 'BEYOND_AI', env: 'production' },
+ *     },
+ *   },
+ * } satisfies ProviderRegistry
  */
-interface TimebackActivityMetricsCollection {
-	/** Collection identifier (IRI format) */
-	id: string
-	/** Must be 'TimebackActivityMetricsCollection' */
-	type: 'TimebackActivityMetricsCollection'
-	/** Attempt number (1-based) */
-	attempt?: number
-	/** Array of metrics */
-	items: TimebackActivityMetric[]
-	/**
-	 * Additional custom attributes.
-	 *
-	 * Common fields:
-	 * - `pctCompleteApp`: App-defined course completion percentage (0–100)
-	 */
-	extensions?: Record<string, unknown>
-	/** Index signature for Caliper compatibility */
-	[key: string]: unknown
+interface ProviderRegistry {
+    /** Default platform when none specified */
+    defaultPlatform: string;
+    /** Available templates indexed by platform → env */
+    templates: Record<string, Record<string, ProviderTemplate>>;
 }
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// TIME SPENT METRICS
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
- * Types of time spent metrics.
+ * Client config that accepts a pre-built provider.
  */
-type TimeSpentMetricType = 'active' | 'inactive' | 'waste' | 'unknown' | 'anti-pattern'
+interface ProviderClientConfig {
+    /** Pre-built provider */
+    provider: TimebackProvider;
+}
 
 /**
- * Individual time spent metric.
+ * Timeback Provider
  *
- * @example
- * ```typescript
- * const metric: TimeSpentMetric = {
- *   type: 'active',
- *   value: 1800, // 30 minutes in seconds
- *   startDate: '2024-01-15T10:00:00Z',
- *   endDate: '2024-01-15T10:30:00Z',
- * }
- * ```
+ * Encapsulates platform connection configuration including endpoints and auth.
+ * Providers are complete "connection" objects that clients consume.
  */
-interface TimeSpentMetric {
-	/** Metric type */
-	type: TimeSpentMetricType
-	/** Time spent in seconds (max 86400 = 24 hours) */
-	value: number
-	/** Sub-type for additional categorization */
-	subType?: string
-	/** Start of the time period */
-	startDate?: string
-	/** End of the time period */
-	endDate?: string
-	/** Additional custom attributes */
-	extensions?: Record<string, unknown>
-}
 
 /**
- * Collection of time spent metrics.
+ * Timeback Provider - encapsulates a complete platform connection.
+ *
+ * A provider contains everything needed to connect to Timeback APIs:
+ * - Service endpoints (URLs)
+ * - Authentication credentials
+ * - Configuration options
+ *
+ * Providers can be created from:
+ * - Platform + environment (uses known Timeback endpoints)
+ * - Explicit base URL (single URL for all services)
+ * - Per-service URLs (different URLs for each service)
  *
  * @example
  * ```typescript
- * const metrics: TimebackTimeSpentMetricsCollection = {
- *   id: 'https://myapp.example.com/time-metrics/123',
- *   type: 'TimebackTimeSpentMetricsCollection',
- *   items: [
- *     { type: 'active', value: 1800 },
- *     { type: 'inactive', value: 300 },
- *   ],
- * }
+ * // Environment-based provider (Timeback hosted)
+ * const provider = new TimebackProvider({
+ *   platform: 'BEYOND_AI',
+ *   env: 'staging',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
  * ```
- */
-interface TimebackTimeSpentMetricsCollection {
-	/** Collection identifier (IRI format) */
-	id: string
-	/** Must be 'TimebackTimeSpentMetricsCollection' */
-	type: 'TimebackTimeSpentMetricsCollection'
-	/** Array of time spent metrics */
-	items: TimeSpentMetric[]
-	/** Additional custom attributes */
-	extensions?: Record<string, unknown>
-	/** Index signature for Caliper compatibility */
-	[key: string]: unknown
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// TIMEBACK EVENTS
-// ═══════════════════════════════════════════════════════════════════════════════
-
-/**
- * Base properties common to all Timeback events.
- */
-interface TimebackEventBase {
-	/** JSON-LD context */
-	'@context': 'http://purl.imsglobal.org/ctx/caliper/v1p2'
-	/** Unique identifier (URN UUID format) */
-	id: string
-	/** The user who performed the action */
-	actor: TimebackUser
-	/** The activity context */
-	object: TimebackActivityContext
-	/** ISO 8601 datetime when event occurred */
-	eventTime: string
-	/** Must be 'TimebackProfile' */
-	profile: 'TimebackProfile'
-	/** Application context (IRI or entity) */
-	edApp?: string | Record<string, unknown>
-	/** Target segment within object */
-	target?: string | Record<string, unknown>
-	/** Referring context */
-	referrer?: string | Record<string, unknown>
-	/** Organization/group context */
-	group?: string | Record<string, unknown>
-	/** User's membership/role */
-	membership?: string | Record<string, unknown>
-	/** Current user session */
-	session?: string | Record<string, unknown>
-	/** LTI session context */
-	federatedSession?: string | Record<string, unknown>
-	/** Additional custom attributes */
-	extensions?: Record<string, unknown>
-}
-
-/**
- * Timeback Activity Completed Event.
- *
- * Records when a student completes an activity, along with performance metrics.
  *
  * @example
  * ```typescript
- * const event: ActivityCompletedEvent = {
- *   '@context': 'http://purl.imsglobal.org/ctx/caliper/v1p2',
- *   id: 'urn:uuid:c51570e4-f8ed-4c18-bb3a-dfe51b2cc594',
- *   type: 'ActivityEvent',
- *   action: 'Completed',
- *   actor: {
- *     id: 'https://api.example.com/users/123',
- *     type: 'TimebackUser',
- *     email: 'student@example.edu',
- *   },
- *   object: {
- *     id: 'https://myapp.example.com/activities/456',
- *     type: 'TimebackActivityContext',
- *     subject: 'Math',
- *     app: { name: 'My Learning App' },
- *   },
- *   eventTime: '2024-01-15T14:30:00Z',
- *   profile: 'TimebackProfile',
- *   generated: {
- *     id: 'https://myapp.example.com/metrics/789',
- *     type: 'TimebackActivityMetricsCollection',
- *     items: [
- *       { type: 'totalQuestions', value: 10 },
- *       { type: 'correctQuestions', value: 8 },
- *     ],
- *   },
- * }
+ * // Explicit URL provider (self-hosted)
+ * const provider = new TimebackProvider({
+ *   baseUrl: 'https://api.myschool.edu',
+ *   authUrl: 'https://auth.myschool.edu/oauth/token',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
  * ```
- */
-interface ActivityCompletedEvent extends TimebackEventBase {
-	/** Must be 'ActivityEvent' */
-	type: 'ActivityEvent'
-	/** Must be 'Completed' */
-	action: 'Completed'
-	/** Activity metrics generated from this completion */
-	generated: TimebackActivityMetricsCollection
-}
-
-/**
- * Timeback Time Spent Event.
- *
- * Records time spent on an activity, categorized by engagement type.
  *
  * @example
  * ```typescript
- * const event: TimeSpentEvent = {
- *   '@context': 'http://purl.imsglobal.org/ctx/caliper/v1p2',
- *   id: 'urn:uuid:d62681f5-g9fe-5d29-cc4b-efg62c3dd695',
- *   type: 'TimeSpentEvent',
- *   action: 'SpentTime',
- *   actor: {
- *     id: 'https://api.example.com/users/123',
- *     type: 'TimebackUser',
- *     email: 'student@example.edu',
- *   },
- *   object: {
- *     id: 'https://myapp.example.com/activities/456',
- *     type: 'TimebackActivityContext',
- *     subject: 'Reading',
- *     app: { name: 'My Learning App' },
- *   },
- *   eventTime: '2024-01-15T15:00:00Z',
- *   profile: 'TimebackProfile',
- *   generated: {
- *     id: 'https://myapp.example.com/time-metrics/789',
- *     type: 'TimebackTimeSpentMetricsCollection',
- *     items: [
- *       { type: 'active', value: 1800 },
- *       { type: 'inactive', value: 300 },
- *     ],
+ * // Per-service URLs
+ * const provider = new TimebackProvider({
+ *   services: {
+ *     oneroster: 'https://roster.myschool.edu',
+ *     caliper: 'https://analytics.myschool.edu',
  *   },
- * }
+ *   authUrl: 'https://auth.myschool.edu/oauth/token',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
  * ```
  */
-interface TimeSpentEvent extends TimebackEventBase {
-	/** Must be 'TimeSpentEvent' */
-	type: 'TimeSpentEvent'
-	/** Must be 'SpentTime' */
-	action: 'SpentTime'
-	/** Time spent metrics generated from this session */
-	generated: TimebackTimeSpentMetricsCollection
+declare class TimebackProvider {
+    /** Platform identifier (if using known platform) */
+    readonly platform?: Platform;
+    /** Environment (if using known platform) */
+    readonly env?: Environment;
+    /** OAuth2 credentials. Undefined for public/no-auth services. */
+    readonly auth?: ProviderAuth;
+    /** Request timeout in milliseconds */
+    readonly timeout: number;
+    /** Resolved endpoints for each service */
+    /** @internal */
+    readonly _endpoints: Partial<Record<ServiceName, ResolvedEndpoint>>;
+    /** Token URL for authentication. Undefined for public/no-auth services. */
+    /** @internal */
+    readonly _authUrl?: string;
+    /** OAuth2 scope to request with access tokens. */
+    /** @internal */
+    readonly _tokenScope?: string;
+    /** API path profiles for this platform */
+    /** @internal */
+    readonly _pathProfiles: PlatformPaths;
+    /** Cached TokenManagers by authUrl (for token sharing) */
+    /** @internal */
+    readonly _tokenManagers: Map<string, TokenProvider>;
+    /**
+     * Create a new TimebackProvider.
+     *
+     * @param config - Provider configuration (env-based, explicit URL, or per-service)
+     * @throws {Error} If configuration is invalid or missing required fields
+     */
+    constructor(config: TimebackProviderConfig);
+    /**
+     * Get the resolved endpoint for a specific service.
+     *
+     * @param service - Service name (oneroster, caliper, edubridge, qti, powerpath)
+     * @returns Resolved endpoint with baseUrl and authUrl
+     * @throws If the service is not configured in this provider
+     */
+    getEndpoint(service: ServiceName): ResolvedEndpoint;
+    /**
+     * Check if a service is available in this provider.
+     *
+     * @param service - Service name to check
+     * @returns True if the service is configured
+     */
+    hasService(service: ServiceName): boolean;
+    /**
+     * Get all configured service names.
+     *
+     * @returns Array of service names available in this provider
+     */
+    getAvailableServices(): ServiceName[];
+    /**
+     * Get the token URL for this provider.
+     * @returns The token URL for authentication
+     */
+    getTokenUrl(): string | undefined;
+    /**
+     * Get endpoint with paths for a service that has path configuration.
+     *
+     * @param service - Service name that has paths in PlatformPaths
+     * @returns Resolved endpoint with baseUrl, authUrl, and paths
+     * @throws If service is not configured or not supported on this platform
+     */
+    getEndpointWithPaths<S extends PathEnabledService>(service: S & ServiceName): ResolvedEndpoint & {
+        paths: NonNullable<PlatformPaths[S]>;
+    };
+    /**
+     * Get all path profiles for this provider (raw, may contain nulls).
+     *
+     * @returns Platform path profiles
+     */
+    getPaths(): PlatformPaths;
+    /**
+     * Get paths for a specific service.
+     *
+     * @param service - Service name
+     * @returns Path configuration for the service
+     * @throws If the service is not supported on this platform
+     */
+    getServicePaths<S extends PathEnabledService>(service: S): NonNullable<PlatformPaths[S]>;
+    /**
+     * Check if a service is supported on this platform.
+     *
+     * @param service - Service name
+     * @returns true if the service has path configuration
+     */
+    hasServiceSupport(service: PathEnabledService): boolean;
+    /**
+     * Get a TokenProvider for a specific service.
+     *
+     * TokenProviders are cached by authUrl, so services sharing the same
+     * token endpoint will share the same cached OAuth tokens.
+     *
+     * @param service - Service name (oneroster, caliper, edubridge, qti, powerpath)
+     * @returns Cached TokenProvider for the service's token endpoint, or undefined for public/no-auth services
+     * @throws If the service is not configured in this provider
+     * @throws If auth is required but not configured
+     */
+    getTokenProvider(service: ServiceName): TokenProvider | undefined;
+    /**
+     * Verify that OAuth authentication is working.
+     *
+     * Attempts to acquire a token using the provider's credentials.
+     * Returns a health check result with success/failure and latency info.
+     *
+     * @returns Auth check result
+     * @throws {Error} If no auth is configured on this provider
+     */
+    checkAuth(): Promise<AuthCheckResult$1>;
+    /**
+     * Invalidate all cached OAuth tokens.
+     *
+     * Call this when closing the client or when tokens need to be refreshed.
+     * New tokens will be acquired on the next API call.
+     */
+    invalidateTokens(): void;
 }
 
 /**
- * Union of all Timeback event types.
- */
-type TimebackEvent = ActivityCompletedEvent | TimeSpentEvent
-
-/**
- * Caliper Event Types
+ * Transport Types
  *
- * Types for Caliper Analytics events and envelopes.
+ * Types for HTTP transport layer.
  */
 
-
-
-/**
- * Supported Caliper profiles.
- */
-type CaliperProfile =
-	| 'AnnotationProfile'
-	| 'AssessmentProfile'
-	| 'ToolUseProfile'
-	| 'GeneralProfile'
-	| 'FeedbackProfile'
-	| 'MediaProfile'
-	| 'SurveyProfile'
-	| 'ResourceManagementProfile'
-	| 'ForumProfile'
-	| 'AssignableProfile'
-	| 'GradingProfile'
-	| 'ReadingProfile'
-	| 'SessionProfile'
-	| 'SearchProfile'
-	| 'ToolLaunchProfile'
-	| 'TimebackProfile'
-
 /**
- * Base Caliper entity representation.
- *
- * Many Caliper fields can be provided either as an IRI string or as an
- * object-shaped entity, so the shared protocol model keeps this flexible.
+ * Fetch function signature for HTTP requests.
+ * Avoids Bun-specific extensions on `typeof fetch`.
  */
-type CaliperEntity = string | { [key: string]: unknown }
-
+type FetchFn = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 /**
- * One actor-object shape for sending events.
- *
- * This is a structured actor object with an `id`, a `type`, and an
- * `extensions` bag containing `email`. It is one valid actor-object shape,
- * not the only representation allowed by `CaliperEvent.actor`.
- */
-interface CaliperActor {
-	/** Unique identifier (IRI format) */
-	id: string
-	/** Entity type (e.g., 'Person', 'TimebackUser') */
-	type: string
-	/** Extensions carried on this actor-object shape */
-	extensions: {
-		/** Actor email on this actor-object shape */
-		email: string
-		/** Additional extension properties */
-		[key: string]: unknown
-	}
+ * HTTP request options.
+ */
+interface RequestOptions {
+    /** HTTP method */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Query parameters to append to the URL */
+    params?: Record<string, string | number | boolean | undefined>;
+    /** Request body (will be JSON-serialized) */
+    body?: unknown;
+    /** Additional headers to include */
+    headers?: Record<string, string>;
+    /**
+     * Unique identifier for this request.
+     * Used for log correlation and debugging.
+     * Auto-generated if not provided.
+     */
+    requestId?: string;
 }
-
 /**
- * Caliper Event.
- *
- * Represents a learning activity event conforming to IMS Caliper v1.2.
- */
-interface CaliperEvent {
-	/** JSON-LD context */
-	'@context'?: string
-	/** Unique identifier (URN UUID format) */
-	id: string
-	/** Event type */
-	type: string
-	/** The agent who initiated the event (IRI string, CaliperActor, TimebackUser, or generic entity) */
-	actor: CaliperEntity | CaliperActor | TimebackUser
-	/** The action or predicate */
-	action: string
-	/** The object of the interaction */
-	object: CaliperEntity
-	/** ISO 8601 datetime when event occurred */
-	eventTime: string
-	/** Profile governing interpretation */
-	profile: CaliperProfile
-	/** Application context */
-	edApp?: CaliperEntity
-	/** Entity generated as result */
-	generated?: CaliperEntity
-	/** Target segment within object */
-	target?: CaliperEntity
-	/** Referring context */
-	referrer?: CaliperEntity
-	/** Organization/group context */
-	group?: CaliperEntity
-	/** User's membership/role */
-	membership?: CaliperEntity
-	/** Current user session */
-	session?: CaliperEntity
-	/** LTI session context */
-	federatedSession?: CaliperEntity
-	/** Additional custom attributes */
-	extensions?: Record<string, unknown>
+ * Auth credentials for environment mode.
+ * Token URL is derived automatically from environment.
+ */
+interface EnvAuth {
+    clientId: string;
+    clientSecret: string;
 }
-
 /**
- * Caliper Envelope.
- *
- * Container for transmitting Caliper events to the API.
- */
-interface CaliperEnvelope {
-	/** Sensor identifier (IRI format) */
-	sensor: string
-	/** ISO 8601 datetime when data was sent */
-	sendTime: string
-	/** Caliper data version */
-	dataVersion: 'http://purl.imsglobal.org/ctx/caliper/v1p2'
-	/** Array of events or entities */
-	data: CaliperEvent[]
-	/** Allow additional properties for forward-compatibility and transformer passthrough. */
-	[key: string]: unknown
+ * Auth credentials for explicit mode.
+ * Requires explicit authUrl for custom APIs.
+ */
+interface ExplicitAuth {
+    clientId: string;
+    clientSecret: string;
+    authUrl: string;
 }
-
 /**
- * Result of sending events.
+ * Base configuration options shared by all modes.
  */
-interface SendEventsResult {
-	/** Job ID for tracking async processing (undefined when the platform does not return one) */
-	jobId: string | undefined
+interface BaseConfig {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Custom fetch implementation */
+    fetch?: FetchFn;
 }
-
 /**
- * Individual event result from job completion.
+ * Internal resolved transport configuration.
  */
-interface EventResult {
-	/** Allocated internal ID */
-	allocatedId: string
-	/** External event ID */
-	externalId: string
+interface ResolvedTransportConfig {
+    /** Base URL of the API */
+    baseUrl: string;
+    /** Request timeout in milliseconds */
+    timeout: number;
+    /** Fetch implementation */
+    fetch: FetchFn;
+    /** Token provider for authentication. Undefined for public/no-auth services. */
+    tokenProvider?: TokenProvider;
 }
-
 /**
- * Job status response.
+ * Transport configuration with explicit auth.
  */
-interface JobStatus {
-	id: string
-	state: 'waiting' | 'active' | 'completed' | 'failed'
-	returnValue?: {
-		status: 'success' | 'error'
-		results: EventResult[]
-	}
-	processedOn?: string | null
+interface TransportConfigWithAuth extends BaseConfig {
+    baseUrl: string;
+    auth: ExplicitAuth;
+    tokenProvider?: never;
 }
-
 /**
- * Stored Caliper event (from list/get).
- *
- * This represents an event as returned by the API, which differs from the
- * input CaliperEvent format. The API adds internal fields and transforms
- * the original event ID to `externalId`.
- *
- * @remarks
- * **API Docs Drift**: The official OpenAPI spec (caliper-api.yaml) does not
- * accurately document this response structure. This type was derived from
- * actual API responses. Key differences:
- * - `id` is a number (internal DB ID), not a string
- * - `externalId` contains the original URN UUID (use this for `get()` calls)
- * - Response is wrapped in `{ events: StoredEvent[] }` for list, `{ event: StoredEvent }` for get
- */
-interface StoredEvent {
-	/** Internal numeric ID (allocated by the database) */
-	id: number
-	/** Original event ID (URN UUID format) - use this for get() calls */
-	externalId: string
-	/** Sensor that sent the event */
-	sensor: string
-	/** Event type (e.g., 'ActivityEvent', 'Event') */
-	type: string
-	/** Caliper profile (e.g., 'TimebackProfile') */
-	profile?: string
-	/** The action or predicate */
-	action: string
-	/** When the event occurred */
-	eventTime: string
-	/** When the event was sent */
-	sendTime: string
-	/** When the record was last updated */
-	updated_at: string | null
-	/** When the record was created */
-	created_at: string
-	/** When the record was deleted (soft delete) */
-	deleted_at: string | null
-	/** The agent who initiated the event */
-	actor: CaliperEntity
-	/** The object of the event */
-	object: CaliperEntity
-	/** Generated entity (e.g., result, score) */
-	generated?: CaliperEntity | null
-	/** Target entity */
-	target?: CaliperEntity | null
-	/** Referrer entity */
-	referrer?: CaliperEntity | null
-	/** EdApp entity */
-	edApp?: CaliperEntity | null
-	/** Group/organization entity */
-	group?: CaliperEntity | null
-	/** Membership entity */
-	membership?: CaliperEntity | null
-	/** Session entity */
-	session?: CaliperEntity | null
-	/** Federated session entity */
-	federatedSession?: CaliperEntity | null
-	/** Extension data */
-	extensions?: Record<string, unknown> | null
-	/** Client application ID */
-	clientAppId?: string | null
+ * Transport configuration with shared token provider.
+ */
+interface TransportConfigWithTokenProvider extends BaseConfig {
+    baseUrl: string;
+    tokenProvider: TokenProvider;
+    auth?: never;
 }
-
 /**
- * Result from listing events.
+ * Transport configuration for public/no-auth services.
  */
-interface ListEventsResult {
-	events: StoredEvent[]
-	pagination: PaginationMeta
+interface TransportConfigNoAuth extends BaseConfig {
+    baseUrl: string;
+    auth?: never;
+    tokenProvider?: never;
 }
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// QUESTION EVENT TYPES (Standard Caliper)
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
- * AssessmentItemEvent (Question Seen / Question Answered).
- *
- * Represents when a student is presented with a question (Started)
- * or submits an answer (Completed).
+ * Configuration for BaseTransport.
+ */
+type BaseTransportConfig = TransportConfigWithAuth | TransportConfigWithTokenProvider | TransportConfigNoAuth;
+/**
+ * Options for creating a BaseTransport.
  */
-interface AssessmentItemEvent extends CaliperEvent {
-	type: 'AssessmentItemEvent'
-	action: 'Started' | 'Completed'
-	profile: 'AssessmentProfile'
+interface BaseTransportOptions {
+    /** Transport configuration */
+    config: BaseTransportConfig;
+    /** Logger instance for request/response logging */
+    logger: Logger;
 }
-
 /**
- * GradeEvent for question-level grading.
- *
- * Represents when a question response is graded, with a Score entity
- * containing `scoreType: "QUESTION_RESULT"` in the `generated` field.
+ * Result of an auth check operation.
  */
-interface QuestionGradeEvent extends CaliperEvent {
-	type: 'GradeEvent'
-	action: 'Graded'
-	profile: 'GradingProfile'
+interface AuthCheckResult {
+    /** Whether auth succeeded */
+    ok: boolean;
+    /** Time taken to complete the check (ms) */
+    latencyMs: number;
+    /** Error message if failed */
+    error?: string;
+    /** Detailed check results */
+    checks: {
+        /** Token acquisition succeeded */
+        tokenAcquisition: boolean;
+    };
 }
 
 /**
- * API Response Types
+ * Base Transport Layer
  *
- * Types for Caliper API responses.
+ * HTTP transport with OAuth2 authentication, retries, and error handling.
+ * Clients can extend this for protocol-specific features.
  *
- * @remarks
- * **IMPORTANT - API Docs Drift**: The official API documentation (caliper/response.yaml
- * and caliper-api.yaml) does NOT accurately reflect actual API responses. The types
- * in this file were derived from testing actual API responses. See individual type
- * comments for specific discrepancies.
  */
-
-
-
 /**
- * Pagination metadata returned by list endpoints.
- */
-interface PaginationMeta {
-	/** Total number of items across all pages */
-	total: number
-	/** Total number of pages */
-	totalPages: number
-	/** Current page number (1-indexed) */
-	currentPage: number
-	/** Number of items per page */
-	limit: number
+ * Base HTTP transport layer for API communication.
+ *
+ * Handles OAuth2 authentication, request/response lifecycle,
+ * and automatic retries for transient failures.
+ *
+ * Clients can extend this class to add protocol-specific features
+ * like custom error parsing or pagination.
+ */
+declare class BaseTransport {
+    protected readonly config: ResolvedTransportConfig;
+    protected readonly log: Logger;
+    /**
+     * Create a new BaseTransport instance.
+     *
+     * @param options - Transport options with config and logger
+     */
+    constructor(options: BaseTransportOptions);
+    /**
+     * The base URL for API requests.
+     * @returns The base URL
+     */
+    get baseUrl(): string;
+    /**
+     * Make an authenticated request to the API.
+     *
+     * Automatically retries on transient failures (429, 503).
+     *
+     * @template T - Expected response type
+     * @param path - API endpoint path
+     * @param options - Request options including method, params, body
+     * @returns Parsed JSON response
+     * @throws {ApiError} On API errors (4xx/5xx responses)
+     */
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Check whether a resource exists at the given path.
+     *
+     * Returns `true` for successful 2xx responses, `false` only for 404 Not Found,
+     * and rethrows all other errors.
+     *
+     * @param path - API endpoint path
+     * @param options - Request options including method, params, body
+     * @returns Promise resolving to whether the resource exists
+     */
+    exists(path: string, options?: RequestOptions): Promise<boolean>;
+    /**
+     * Make a raw request, returning the Response object.
+     *
+     * ## Retry Behavior
+     * Automatically retries on transient failures (429, 503) with exponential
+     * backoff. Respects Retry-After header when present.
+     *
+     * ## Timeout Behavior
+     * Uses an operation-level timeout that spans ALL retry attempts.
+     * If configured timeout is 30s, the entire operation (including retries
+     * and backoff delays) must complete within 30s total.
+     *
+     * ## Flow
+     * 1. Build URL from path and query params
+     * 2. Start operation timer
+     * 3. Loop up to MAX_RETRIES times:
+     *    a. Check if we've exceeded the operation deadline
+     *    b. Get OAuth token (may be cached)
+     *    c. Make the HTTP request with per-request timeout
+     *    d. If 429/503 and not last attempt → calculate backoff and retry
+     *    e. If other error → throw appropriate ApiError subclass
+     *    f. If success → return response
+     * 4. If all retries exhausted → throw "Max retries exceeded"
+     *
+     * @param path - API endpoint path (relative to baseUrl)
+     * @param options - Request options (method, params, body, headers)
+     * @returns Raw fetch Response for custom handling
+     * @throws {ApiError} On timeout, non-retryable errors, or max retries exceeded
+     */
+    requestRaw(path: string, options?: RequestOptions): Promise<Response>;
+    /**
+     * Get a valid OAuth2 access token.
+     * @returns Promise resolving to access token or undefined
+     */
+    protected getAccessToken(): Promise<string | undefined>;
+    /**
+     * Construct full URL with query parameters.
+     *
+     * @param path - The relative path or absolute URL
+     * @param params - Query parameters
+     * @returns Full URL string
+     * @throws {Error} If path is an absolute URL (security protection)
+     */
+    protected buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string;
+    /**
+     * Parse successful response or delegate to error handler.
+     * @param response - The fetch Response
+     * @returns Parsed response as type T
+     */
+    protected handleResponse<T>(response: Response): Promise<T>;
+    /**
+     * Parse JSON response with context-preserving error handling.
+     *
+     * Unlike raw `response.json()`, this method:
+     * - Logs structured error context (URL, status, content-type, body preview)
+     * - Throws `ApiError` with `parseError` and `body` in the response object
+     * - Aids debugging when upstream services return malformed JSON
+     *
+     * @template T - Expected shape of the parsed response
+     * @param response - The fetch Response to parse
+     * @returns Parsed JSON as type T
+     * @throws {ApiError} When JSON parsing fails, with status code and body preview
+     */
+    protected parseJsonResponse<T>(response: Response): Promise<T>;
+    /**
+     * Parse error response and throw appropriate ApiError subclass.
+     *
+     * Handles both JSON and non-JSON error responses gracefully.
+     * Clients can override this to add protocol-specific error parsing.
+     *
+     * @param response - The error Response (status >= 400)
+     * @param requestId - Request ID for log correlation
+     * @throws {UnauthorizedError} For 401 responses (also invalidates token)
+     * @throws {ForbiddenError} For 403 responses
+     * @throws {NotFoundError} For 404 responses
+     * @throws {ValidationError} For 422 responses
+     * @throws {ApiError} For all other error status codes
+     */
+    protected handleErrorResponse(response: Response, requestId?: string): Promise<never>;
+    /**
+     * Extract error message from response body.
+     *
+     * Checks common error formats:
+     * - `message` (most APIs)
+     * - `error` (some APIs)
+     * - `imsx_description` (IMS Global: OneRoster, Caliper, QTI)
+     *
+     * Override in client transports for API-specific error formats
+     * not covered here (e.g., Edubridge's `errors[]` array format).
+     *
+     * @param body - The error response body
+     * @param fallback - Fallback message if none found
+     * @returns Extracted error message
+     */
+    protected extractErrorMessage(body: unknown, fallback: string): string;
+    /**
+     * Delay execution for retry backoff.
+     *
+     * @param ms - Number of milliseconds to delay
+     * @returns Promise that resolves after delay
+     */
+    protected sleep(ms: number): Promise<void>;
+    /**
+     * Parse Retry-After header value.
+     *
+     * Handles both formats per RFC 7231:
+     * - Numeric seconds: "120"
+     * - HTTP-date: "Wed, 21 Oct 2025 07:28:00 GMT"
+     *
+     * @param retryAfter - Retry-After header value
+     * @param attempt - Current attempt number (0-based)
+     * @returns Delay in milliseconds
+     */
+    protected parseRetryAfter(retryAfter: string | null, attempt: number): number;
 }
 
 /**
- * Options for waitForCompletion polling.
+ * Pagination Utilities
+ *
+ * Helpers for iterating over paginated API responses.
  */
-interface WaitForCompletionOptions {
-	/** Maximum time to wait in milliseconds (default: 30000) */
-	timeoutMs?: number
-	/** Interval between status checks in milliseconds (default: 1000) */
-	pollIntervalMs?: number
-}
 
 /**
- * Validation result from the validate endpoint.
+ * Async iterator for paginated API responses.
+ *
+ * Automatically fetches subsequent pages as you iterate, making it easy
+ * to process large datasets without manual pagination handling.
+ *
+ * @typeParam T - The type of items being paginated
+ *
+ * @example
+ * ```typescript
+ * // Iterate over all items
+ * for await (const user of paginator) {
+ *   console.log(user.name)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Collect all items into an array
+ * const allUsers = await paginator.toArray()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Get just the first page
+ * const page = await paginator.firstPage()
+ * console.log(`Got ${page.data.length} of ${page.total} users`)
+ * ```
  */
-interface ValidationResult {
-	/** Whether validation succeeded */
-	status: 'success' | 'error'
-	/** Human-readable message */
-	message?: string
-	/** Validation errors (if any) */
-	errors?: unknown
+declare class Paginator$1<T, F = unknown> implements AsyncIterable<T> {
+    private readonly fetcher;
+    private readonly path;
+    private readonly params;
+    private readonly max?;
+    private readonly unwrapKey?;
+    private readonly log;
+    private readonly transform?;
+    private readonly paginationStyle;
+    /**
+     * Create a new Paginator.
+     *
+     * @param options - Paginator configuration
+     */
+    constructor(options: PaginatorOptions<T, F>);
+    /**
+     * Builds query parameters for the paginated request.
+     *
+     * Converts the type-safe `where` clause to a filter string for the API,
+     * and merges with other list parameters (sort, orderBy, fields, search).
+     * Excludes client-side params like `max` that shouldn't be sent to the API.
+     *
+     * Uses the configured pagination style:
+     * - `'offset'`: Sends `{ limit, offset }` params
+     * - `'page'`: Sends `{ limit, page }` params (1-indexed)
+     *
+     * @param limit - Maximum items per page
+     * @param offset - Number of items to skip (converted to page if using page style)
+     * @returns Query parameters ready for the request
+     */
+    private buildRequestParams;
+    /**
+     * Extracts and validates items from response data.
+     *
+     * Handles two response formats:
+     * - Direct array: `[item1, item2, ...]`
+     * - Wrapped object: `{ users: [item1, item2, ...] }` (when unwrapKey is set)
+     *
+     * @param data - Raw response data from the API
+     * @param pageNumber - Current page number (for error messages)
+     * @returns Validated array of items
+     * @throws {Error} If extracted data is not an array
+     */
+    private extractItems;
+    /**
+     * Validates that extracted data is an array.
+     *
+     * Protects against malformed API responses that could cause:
+     * - Infinite loops (empty non-array values)
+     * - Unexpected iteration (strings yield characters, not items)
+     * - Runtime crashes (objects are not iterable)
+     *
+     * @param data - Data to validate (should be an array)
+     * @param pageNumber - Current page number (for error messages)
+     * @returns The data cast to T[] if valid
+     * @throws {Error} If data is not an array (with helpful message including unwrapKey)
+     */
+    private validateItems;
+    /**
+     * Determines if more pages are available based on response metadata.
+     *
+     * Uses a three-tier fallback strategy:
+     * 1. Link header (most reliable)
+     * 2. X-Total-Count header
+     * 3. Full page heuristic (assumes more if page is full and no total provided)
+     *
+     * Always returns false if the page is empty to prevent infinite loops
+     * from buggy servers that return hasMore: true with no data.
+     * @param response - Response with pagination metadata
+     * @param itemCount - Number of items in current page
+     * @param offset - Current offset
+     * @param limit - Current limit
+     * @returns True if more pages are available
+     */
+    private hasMorePages;
+    /**
+     * Async iterator implementation.
+     *
+     * Yields items one at a time, automatically fetching new pages as needed.
+     * Stops when `max` items have been yielded (if specified).
+     *
+     * @yields Items of type T from paginated responses
+     */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    /**
+     * Collect all items into an array.
+     *
+     * **Warning**: Use with caution on large datasets as this loads
+     * all items into memory. Consider iterating with `for await...of`
+     * for better memory efficiency.
+     *
+     * @param options - Optional configuration
+     * @param options.maxItems - Maximum items to collect (default: 10,000).
+     *   Throws if limit is reached. Set to `Infinity` to disable.
+     * @returns Promise resolving to an array of all items
+     * @throws {Error} If maxItems limit is exceeded
+     */
+    toArray(options?: ToArrayOptions): Promise<T[]>;
+    /**
+     * Fetch only the first page of results.
+     *
+     * Useful when you need pagination metadata (total count, hasMore)
+     * or want to implement custom pagination UI.
+     *
+     * @returns Promise resolving to the first page with metadata
+     */
+    firstPage(): Promise<PageResult<T>>;
 }
 
 /**
@@ -800,175 +1580,6 @@ interface EventTransformer {
  */
 type CaliperClientInstance = InstanceType<typeof CaliperClient>;
 
-type input<T> = T extends {
-    _zod: {
-        input: any;
-    };
-} ? T["_zod"]["input"] : unknown;
-
-/**
- * Caliper Schemas
- *
- * Zod schemas for the IMS Caliper Analytics standard with Timeback Profile.
- */
-
-
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// BUILDER INPUTS
-// ═══════════════════════════════════════════════════════════════════════════════
-
-declare const ActivityCompletedInput = z
-	.object({
-		actor: TimebackUser,
-		object: TimebackActivityContext,
-		metrics: z.array(TimebackActivityMetric).min(1, 'metrics must contain at least one metric'),
-		eventTime: IsoDateTimeString.optional(),
-		metricsId: z.string().optional(),
-		id: z.string().optional(),
-		/** Event-level extensions */
-		extensions: z.record(z.string(), z.unknown()).optional(),
-		/**
-		 * Application context (IRI or entity).
-		 *
-		 * Maps to `edApp` in the Caliper event. Identifies the educational
-		 * application where the event occurred.
-		 */
-		edApp: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
-		/**
-		 * Session context (IRI or entity).
-		 *
-		 * Maps to `session` in the Caliper event. Used for event-to-session
-		 * correlation (e.g., linking heartbeats with completions via runId).
-		 */
-		session: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
-		/**
-		 * Attempt number (1-based).
-		 *
-		 * Maps to `generated.attempt` in the Caliper event.
-		 */
-		attempt: z.number().int().min(1).optional(),
-		/**
-		 * Extensions for the generated metrics collection.
-		 *
-		 * Maps to `generated.extensions` in the Caliper event.
-		 * Use `generatedExtensions.pctCompleteApp` (0–100) for app-reported course progress.
-		 */
-		generatedExtensions: z
-			.object({
-				/**
-				 * App-reported course progress (per enrollment), as a percentage from 0–100.
-				 *
-				 * This is emitted to Caliper as `generated.extensions.pctCompleteApp`.
-				 *
-				 * @remarks
-				 * This value is not clamped here (Caliper client keeps the raw shape).
-				 */
-				pctCompleteApp: z.number().optional(),
-			})
-			.loose()
-			.optional(),
-	})
-	.strict()
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// TYPE EXPORTS (REQUEST INPUTS)
-// ═══════════════════════════════════════════════════════════════════════════════
-
-type ActivityCompletedInput = input<typeof ActivityCompletedInput>
-
-declare const TimeSpentInput = z
-	.object({
-		actor: TimebackUser,
-		object: TimebackActivityContext,
-		metrics: z.array(TimebackTimeMetric).min(1, 'metrics must contain at least one metric'),
-		eventTime: IsoDateTimeString.optional(),
-		metricsId: z.string().optional(),
-		id: z.string().optional(),
-		extensions: z.record(z.string(), z.unknown()).optional(),
-		edApp: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
-		session: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
-	})
-	.strict()
-type TimeSpentInput = input<typeof TimeSpentInput>
-
-declare const QuestionSeenInput = z
-	.object({
-		/** Actor (Person IRI or entity object with id, type, name, etc.) */
-		actor: z.union([z.string(), CaliperActor, TimebackUser]),
-		/** AssessmentItem being presented */
-		object: AssessmentItemObject,
-		/** Application identifier (IRI or entity) */
-		edApp: CaliperEntity,
-		/** Event identifier (auto-generated if omitted) */
-		id: z.string().optional(),
-		/** ISO 8601 datetime (defaults to now) */
-		eventTime: IsoDateTimeString.optional(),
-		/** Session context (IRI or entity) */
-		session: CaliperEntity.optional(),
-		/** Event-level extensions */
-		extensions: z.record(z.string(), z.unknown()).optional(),
-	})
-	.strict()
-type QuestionSeenInput = input<typeof QuestionSeenInput>
-
-declare const QuestionAnsweredInput = z
-	.object({
-		/** Actor (Person IRI or entity object with id, type, name, etc.) */
-		actor: z.union([z.string(), CaliperActor, TimebackUser]),
-		/** AssessmentItem being answered */
-		object: AssessmentItemObject,
-		/** Application identifier (IRI or entity) */
-		edApp: CaliperEntity,
-		/** Response entity with optional attempt and timing */
-		generated: ResponseGenerated.optional(),
-		/** Event identifier (auto-generated if omitted) */
-		id: z.string().optional(),
-		/** ISO 8601 datetime (defaults to now) */
-		eventTime: IsoDateTimeString.optional(),
-		/** Session context (IRI or entity) */
-		session: CaliperEntity.optional(),
-		/** Event-level extensions */
-		extensions: z.record(z.string(), z.unknown()).optional(),
-	})
-	.strict()
-type QuestionAnsweredInput = input<typeof QuestionAnsweredInput>
-
-declare const QuestionGradedInput = z
-	.object({
-		/** Actor (Person IRI or entity object with id, type, name, etc.) */
-		actor: z.union([z.string(), CaliperActor, TimebackUser]),
-		/** Attempt being graded (IRI) */
-		object: z.string(),
-		/** Score awarded for the question */
-		generated: ScoreGenerated,
-		/** Application identifier (IRI or entity) */
-		edApp: CaliperEntity,
-		/** Event identifier (auto-generated if omitted) */
-		id: z.string().optional(),
-		/** ISO 8601 datetime (defaults to now) */
-		eventTime: IsoDateTimeString.optional(),
-		/** Session context (IRI or entity) */
-		session: CaliperEntity.optional(),
-		/** Event-level extensions */
-		extensions: z.record(z.string(), z.unknown()).optional(),
-	})
-	.strict()
-type QuestionGradedInput = input<typeof QuestionGradedInput>
-
-declare const CaliperListEventsParams = z
-	.object({
-		limit: z.number().int().positive().optional(),
-		offset: z.number().int().min(0).optional(),
-		sensor: NonEmptyString.optional(),
-		startDate: IsoDateTimeString.optional(),
-		endDate: IsoDateTimeString.optional(),
-		actorId: NonEmptyString.optional(),
-		actorEmail: z.email().optional(),
-	})
-	.strict()
-type CaliperListEventsParams = input<typeof CaliperListEventsParams>
-
 /**
  * Transport Layer
  *
@@ -1604,11 +2215,11 @@ declare class JobsResource {
 declare const CaliperClient: {
     new (config?: CaliperClientConfig): {
         readonly transport: CaliperTransportLike;
-        readonly _provider?: _timeback_internal_client_infra.TimebackProvider | undefined;
+        readonly _provider?: TimebackProvider | undefined;
         readonly events: EventsResource;
         readonly jobs: JobsResource;
         getTransport(): CaliperTransportLike;
-        checkAuth(): Promise<_timeback_internal_client_infra.AuthCheckResult>;
+        checkAuth(): Promise<AuthCheckResult>;
     };
 };
 
@@ -1657,5 +2268,5 @@ declare const CALIPER_DATA_VERSION = "http://purl.imsglobal.org/ctx/caliper/v1p2
  */
 declare const QUESTION_RESULT_SCORE_TYPE: "QUESTION_RESULT";
 
-export { ActivityCompletedInput, CALIPER_DATA_VERSION, CaliperClient, CaliperListEventsParams as ListEventsParams, QUESTION_RESULT_SCORE_TYPE, QuestionAnsweredInput, QuestionGradedInput, QuestionSeenInput, TimeSpentInput, Transport, createActivityEvent, createCaliperClient, createQuestionAnsweredEvent, createQuestionGradedEvent, createQuestionSeenEvent, createTimeSpentEvent };
-export type { ActivityCompletedEvent, ActivityMetricType, AssessmentItemEvent, CaliperClientConfig, CaliperClientInstance, CaliperEnvelope, CaliperEvent, CaliperProfile, JobStatus, QuestionGradeEvent, SendEventsResult, StoredEvent, TimeSpentEvent, TimeSpentMetric, TimeSpentMetricType, TimebackActivity, TimebackActivityContext, TimebackActivityMetric, TimebackActivityMetricsCollection, TimebackApp, TimebackCourse, TimebackEvent, TimebackSubject, TimebackTimeSpentMetricsCollection, TimebackUser, TimebackUserRole, ValidationResult };
+export { CALIPER_DATA_VERSION, CaliperClient, QUESTION_RESULT_SCORE_TYPE, Transport, createActivityEvent, createCaliperClient, createQuestionAnsweredEvent, createQuestionGradedEvent, createQuestionSeenEvent, createTimeSpentEvent };
+export type { AuthCheckResult, CaliperClientConfig, CaliperClientInstance, EnvAuth, Environment, ExplicitAuth };